Rancher provides different storage services that are capable of exposing volumes to containers.
When setting up an environment template, you can select what storage services you’d like to use in your environment.
Alternatively, if you already have an environment set up, you can select and launch a storage service from the catalog.
Note: Some storage services may not be compatible with some container orchestration types (i.e. Kubernetes). Environment templates will restrict which ones are compatible based on orchestration, but all options are available from the catalog.
After your storage service has been launched, a storage driver has been created and is viewable in Infrastructure -> Storage. You will be able to see all the storage drivers that are available in your environment. The name of the storage driver is derived from the name of the stack.
In each storage driver, the hosts that have the storage service running will be listed. Typically, this is all hosts in the environment. The lists of volumes and their states in the storage driver are also listed. For each volume, you can see the name of the volume (i.e. the name of the volume on the host(s)), and the mounts of each volume. For each mount, there is the container name and the directory path inside the container.
With our storage service, we have volumes that can be scoped at different levels. Currently, only Rancher Compose supports creating the different types of volumes. The UI only creates volumes that are environment scoped.
With a stack scoped volume, services referencing the same volume in a stack would share the same volume. A service outside the stack could not use the same volume.
In Rancher, stack scoped volumes are named with the stack name as a prefix to indicate which stack the volume is scoped to and suffixed with a random number to guarantee no duplication. When referencing the volume, you still use the original volume name. For example, if you create a volume called
stackA, the volume name in the UI and on your hosts will be
stackA_foo_<randomNumber>, but to use the same volume in your service, you would use the name
With a container scoped volume, a new volume is created for each instance of a container. No containers would share the same volume.
In Rancher, container scoped volumes are prefixed with
containerscoped and have a suffix of the
<dockerContainerID> and a random number to guarantee no duplication. For example, if you create a volume called
foo1 with a container scope, the volume name in the UI and on your hosts will be
With an environment scoped volume, services referencing the same volume in an environment would share the same volume. Services in different stacks could share the same volume. Currently, an environment scoped volume can only be created through the UI.
After your storage service has been launched and is
active, services can start using the shared storage. when creating a service, in the Volumes tab, provide a volume and a volume driver. The volume will be in the same syntax as Docker,
<volume_name>:</path/in/container>. Docker volumes default to mount in read-write mode, but you can set it to be mounted read-only by adding the
:ro at the end of the volume. The volume driver will be the name of the storage driver.
<volume_name> already exists in the storage driver, the same volume will be used if the volume meets the volume scope requirements.
A volume can be created in 2 sections:
Upon creating a service, if the volume in the Volumes tab does not exist in the storage driver, then an environment scoped volume is created. If the volume already exists in the volume driver, a new volume will not be created.
In Infrastructure -> Storage, click on Add Volume. Provide the name of the volume and driver options if desired. This volume will be
inactive until a service starts to use it.
After the storage infrastructure services have been launched, you can start creating volumes. In our examples below, we are using the Rancher NFS storage service.
Volumes can be specified as part of a Docker Compose file under the
volumes key. Each volume can be associated with one or more services in the same file. This functionality is only available when using a Compose file in v2 format.
version: '2' services: foo: image: busybox volumes: - bar:/var/lib/storage volumes: bar: driver: rancher-nfs
By default, all volumes are created at the stack scope. Services referencing the same volume in a Compose file or stack will be sharing the same volume.
When launching a new stack from the same Compose file, a new volume will be created. When a stack is deleted, its corresponding volumes are removed.
In the above example, volume
bar has stack scope.
In some cases it makes sense to have a volume created for each instance of a container. This is indicated via the
per_container option for a volume.
version: '2' services: foo: image: busybox volumes: - bar:/var/lib/storage volumes: bar: driver: rancher-nfs per_container: true
When scaling up the
foo service, a volume will be created for each new container. When scaling down the
foo service, the volumes corresponding to the removed containers will be removed.
To use volumes across stacks, you would need to use an environment scoped volume. In this case, volumes must already be created in Rancher prior to starting services and stacks using the volume. To use an environment scoped volume, you’d add the
external option to the volume.
version: '2' services: foo: image: busybox volumes: - bar:/var/lib/storage volumes: bar: driver: rancher-nfs external: true
If a volume by the name of
bar is not found at the environment level when launching this stack, then an error will be thrown. Environment scoped volumes can only be removed from the UI.