Volumes are used to store data.
Volume names consist of lower case alphanumeric characters or ‘-‘, and must
start and end with an alphanumeric character. By default, volumes are 5GB in
size (overridden by
--size) and formatted as ext4 (overridden by
In order to mount volumes into containers, they are formatted with a filesystem
ext4. All volumes are accessible to any container anywhere on the cluster
(global namespace) but each volume may only be mounted by one container at a
time. Additional behaviours may be specified by adding labels.
Using the Docker CLI
The Docker CLI does not support namespaced volumes so all volumes created using the Docker CLI must be in the
To create a 15GB volume, run:
$ docker volume create --driver storageos --opt size=15 volume-name
To create a volume and provision to a Docker container in one step, run:
docker run --rm -ti --volume-driver storageos -v volume-name:/data alpine ash
When using dynamic provisioning it is not possible to specify options at creation time. The volume will default to 5GB, but the size can be dynamically expanded using the CLI or API.
To list all volume, run:
docker volume ls
Using the StorageOS CLI
With the StorageOS CLI, you must specify a namespace using the
To create a 15GB volume in the
default namespace, run:
$ storageos volume create --namespace default --size 15 --fstype ext4 volume-name default/volume-name
To view all volumes in all namespaces, run:
$ storageos volume ls NAMESPACE/NAME SIZE MOUNTED BY MOUNTPOINT STATUS REPLICAS default/volume-name 15GB active 0/0
To mount a volume on the current node into
/mnt, run (note this requires root):
sudo -E storageos volume mount default/volume-name /mnt
(Important: use the
sudo -E option to preserve the storageos environment credentials)
In order for the mount to succeed, StorageOS must be running on the node and the volume must not be mounted anywhere else. When the volume is mounted a lock is placed on the volume to ensure it is not written by multiple concurrent writers as this could lead to data inconsistency.
By default the volume will be formatted using
ext4, which may be overridden or
To resize a volume, use
storageos volume update --size <new_size_in_GB> default/volume-name.
The volume is expanded immediately but you will need to manually resize the
filesystem by calling
Shrinking a volume is not supported.
Unmounting and removing volumes
To unmount a volume on the current node, run:
storageos volume unmount default/volume-name
The unmount command should be run on the node that has the volume mounted.
Unmounting the volume detaches the filesystem from the node and removes the
mount lock. In cases where the filesystem was unmounted manually using the Linux
umount utility, or the node is no longer active, you can specify the
flag to only remove the mount lock.
To delete a volume, run:
$ storageos volume rm default/volume-name default/volume-name
All data in this volume will be lost.
This command will fail if the volume is mounted. To delete a mounted volume, add
$ storageos volume rm --force default/volume-name default/volume-name
Volumes may not be removed immediately as the data will be purged in the background.
Using node selector
A node selector is a constraint on where volumes may be deployed, based on node labels. For the volume to be eligible for a deployment on a node, selector must match node’s labels. An empty selector always matches a node.
If a group of nodes are labelled
country=US, then a node selector can be used
during volume creation:
$ storageos volume create --nodeSelector 'country=US'
Selectors may also be set-based:
country in (US, CA) country notin (UK)
Since StorageOS selectors are similar to Kubernetes selectors, please check out documentation available there: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors.