Document volume usage in cattle #800
Conversation
This document describe how to use volumes within cattle. It covers different volume scopes, volume management with Rancher CLI, and explains the difference between v2 and v1 compose.
| A `volume plugin` and `volume driver` are used interchangeably in Docker and Rancher documentation. They refer to the same thing: a plugin that provides local or shared persistent volumes to a Docker container. | ||
|
|
||
| A `storage driver` pertains to how containers and images are stored and managed on your Docker hosts. Examples are: aufs, btrfs, zfs, devicemapper. These drivers are beyond the scope of Rancher. More information is available [here](https://docs.docker.com/engine/userguide/storagedriver/imagesandcontainers/). | ||
|
|
There was a problem hiding this comment.
can we add in the examples of storage drivers that Rancher has?
| In this section you’re going to learn how to create persistent volumes that may be shared between containers. | ||
|
|
||
| #### Create a Volume | ||
|
|
There was a problem hiding this comment.
can you preface this section with the fact that you're using rancher CLI?
There was a problem hiding this comment.
Agreed. Worth mentioning what is / is not available through the UI.
| This will create a new local volume with name `app-data`. The name must start with an alphanumeric character, followed by `a-z0-9`, `_` (underscore), `.` (period) or `-` (hyphen). | ||
|
|
||
| The `--driver` flag specifies the volume driver to use. Docker ships with a `local` volume driver. Volumes using this driver persist their data to the host filesystem and are accessible to any container on the same host. | ||
|
|
There was a problem hiding this comment.
can we give an example using one of our storage drivers? not just local?
There was a problem hiding this comment.
One of the major pieces of feedback we receive was that jumping right into using drivers made the document much more complex and harder to get started. We intentionally avoided that. We can/should probably have examples that use drivers other than local, but that could/should be in an advanced section.
| ``` | ||
|
|
||
| Define the volume with `external: true` modifier to indicate the volume's lifecycle is managed externally (environment scope). Save the `docker-compose.yml` file below to a directory. | ||
|
|
There was a problem hiding this comment.
make a note that without external:true, the volume will be stack scoped and refer to the stack scoped section
|
|
||
| When a container is created, associated volumes enter `activating` state. Once the container enters the `running` phase, its volumes enter `active` state. Containers attaching to an already `active` volume will not impact that volume's state. | ||
|
|
||
| When all containers attached to a volume are marked for deletion, the volume enters a `dactivating` state. Once the conatiners are deleted, the volume enters `detached` state. |
| To avoid name collisions with other volumes, unique names are used for the stack scope volumes you define. They include the stack name, original volume name, and a random component. [List the volumes]({{site.baseurl}}/rancher/{{page.version}}/{{page.lang}}/cattle/volumes/#list-volumes) and identify the `data` volume exists in this form. | ||
|
|
||
| > **Note:** Stack-scope volumes could be mounted by other stacks. Stack scope is not a security mechanism. It is solely for managing the lifecycle of the volume. | ||
|
|
There was a problem hiding this comment.
How about documentation on the per_container setting?
There was a problem hiding this comment.
We've deemed that setting to be not ready for prime time. We've intentionally omitted it for the time being.
|
More really good feedback in this forum discussion: https://forums.rancher.com/t/rancher-storage-driver-vs-docker-volume-plugin/6217 |
|
@cjellick I agree our usage of the term |
|
I've attempted to address all comments on this PR, https://forums.rancher.com/t/rancher-storage-driver-vs-docker-volume-plugin/6217/8 and rancher/rancher#9158 (comment). Let me know if it all makes sense, thanks! |
|
@deniseschannon is it time for you to take over this PR (possibly in a new one)? I feel like at this point, the feedback is going to be so specific and precise that it would be more efficient for you to do it first hand. |
4 participants
This document describe how to use volumes within cattle. It covers
different volume scopes, volume management with Rancher CLI, and
explains the difference between v2 and v1 compose.