Using Volumes with vSphere Integrated Containers
vSphere Integrated Containers supports the use of container volumes. You can create container volumes either in volume stores on vSphere datastores or in NFS share points that you designate as volume stores. The vSphere datastore or NFS share point houses the volume store and containers build volumes in that volume store.
IMPORTANT: To use container volume capabilities with vSphere Integrated Containers, the vSphere administrator must configure one or more volume stores on the virtual container host (VCH). When the vSphere administrator creates a VCH, they can specify a vSphere datastore or NFS share point to use to store container volumes. For information about how to create VCHs with volume stores, see Specify Volume Stores. For information about how to add volume stores to existing VCHs, see Add Volume Stores.
- Obtain the List of Available Volume Stores
- Obtain the List of Available Volumes
- Create a Volume in a Volume Store
- Creating Volumes from Images
- Create a Container with a New Anonymous or Named Volume
- Mount Existing vSphere-Backed Volumes on Containers
- Sharing NFS-Backed Volumes Between Containers
- Obtain Information About a Volume
- Delete a Named Volume from a Volume Store
- Delete a Container and the Anonymous Volumes Attached to It
- Run a Container and Delete the Anonymous Volumes Attached to it when it Stops
For simplicity, the examples in this topic assume that the VCHs implement TLS authentication with self-signed server certificates, with no client verification.
To obtain the list of volume stores that are available on a VCH, run
docker -H virtual_container_host_address:2376 --tls info
The list of available volume stores for this VCH appears in the
docker info output under
[...] Storage Driver: vSphere Integrated Containers Backend Engine VolumeStores: volume_store_1 volume_store_2 ... volume_store_n vSphere Integrated Containers Backend Engine: RUNNING [...]
To obtain a list of volumes that are available on a VCH, run
docker volume ls.
docker -H virtual_container_host_address:2376 --tls volume ls DRIVER VOLUME NAME vsphere volume_1 vsphere volume_2 [...] [...] vsphere volume_n
When you use the
docker volume create command to create a volume, you can optionally provide a name for the volume by specifying the
--name option. If you do not specify
docker volume create assigns a random UUID to the volume.
If the vSphere administrator created the VCH with one or more volume stores, but none of the volume stores are named
default, you must specify the name of an existing volume store in the
--opt VolumeStoreoption. If you do not specify
docker volume createsearches for a volume store named
default, and returns an error if no such volume store exists.
docker -H virtual_container_host_address:2376 --tls volume create --opt VolumeStore=volume_store_label --name volume_name
If the vSphere administrator created the VCH with a volume store named
default, you do not need to specify
--opt VolumeStorein the
docker volume createcommand. If you do not specify a volume store name, the
docker volume createcommand automatically uses the
defaultvolume store if it exists.
docker -H virtual_container_host_address:2376 --tls volume create --name volume_name
You can optionally set the capacity of a volume by specifying the
--opt Capacityoption when you run
docker volume create. If you do not specify the
--opt Capacityoption, the volume is created with the default capacity of 1024MB.
If you do not specify a unit for the capacity, the default unit will be in Megabytes.
docker -H virtual_container_host_address:2376 --tls volume create --opt VolumeStore=volume_store_label --opt Capacity=2048 --name volume_name
To create a volume with a capacity in megabytes, gigabytes, or terabytes, include
TBin the value that you pass to
--opt Capacity. The unit is case insensitive.
docker -H virtual_container_host_address:2376 --tls volume create --opt VolumeStore=volume_store_label --opt Capacity=10GB --name volume_name
vSphere Integrated Containers Engine currently only supports
ext4file systems for volumes.
After you create a volume by using
docker volume create, you can mount that volume in a container by running either of the following commands:
docker -H virtual_container_host_address:2376 --tls create -v volume_name:/folder busybox
docker -H virtual_container_host_address:2376 --tls run -v volume_name:/folder busybox
In the examples above, Docker mounts the volume
/folder in the container.
NOTE: When using a vSphere Integrated Containers Engine VCH as your Docker endpoint, the storage driver is always the vSphere Integrated Containers Engine Backend Engine. If you specify the
docker volume create --driver option an error stating that a bad driver has been selected will occur.
Some images, for example,
redis:alpine, contain volume bind information in their metadata. vSphere Integrated Containers Engine creates such volumes with the default parameters and treats them as anonymous volumes. vSphere Integrated Containers Engine treats all volume mount paths as unique, in the same way that Docker does. This should be kept in mind if you attempt to bind other volumes to the same location as anonymous or image volumes. A specified volume always takes priority over an anonymous volume.
If you require an image volume with a different volume capacity to the default, create a named volume with the required capacity. You can mount that named volume to the location that the image metadata specifies. You can find the location by running
docker inspect image_name and consulting the
Volumes section of the output. The resulting container has the required storage capacity and the endpoint.
If you intend to create named or anonymous volumes by using
docker create -v when creating containers, a volume store named
default must exist in the VCH.
- vSphere Integrated Containers Engine does not support mounting vSphere datastore folders as data volumes. A command such as
docker create -v /folder_name:/folder_name busyboxis not supported if the volume store is a vSphere datastore.
- If you use
docker create -vto create containers and mount new volumes on them, vSphere Integrated Containers Engine only supports the
- Anonymous volumes are only recommended for development rather than production environments. A valid use case for anonymous volumes is the creation of ephemeral Docker build hosts for a CI pipeline.
To create an anonymous volume, you include the path to the destination at which you want to mount the anonymous volume in the
docker create -v command. Docker creates the anonymous volume in the
default volume store, if it exists. The VCH mounts the anonymous volume on the container.
docker create -v example below performs the following actions:
- Creates a busybox container that uses an anonymous volume in the
- Mounts the volume to
/volumesin the container.
docker -H virtual_container_host_address:2376 --tls create -v /volumes busybox
To create a container with a new named volume, you specify a volume name in the
docker create -v command. When you create containers that with named volumes, the VCH checks whether the volume exists in the volume store, and if it does not, creates it. The VCH mounts the existing or new volume on the container.
docker create -v example below performs the following actions:
- Creates a busybox container
- Creates volume named
- Mounts the volume to the
/volumesfolder in the container.
docker -H virtual_container_host_address:2376 --tls create -v volume_1:/volumes busybox
If your volume store is in a vSphere datastore, mounting existing volumes on containers is subject to the following limitations:
- vSphere Integrated Containers currently supports mounting a volume that is backed by vSphere on only one container at a time.
- Docker does not support unmounting a volume from a container, whether that container is running or not. When you mount a volume on a container by using
docker create -v, that volume remains mounted on the container until you remove the container. When you have removed the container you can mount the volume onto a new container.
- If you intend to create and mount a volume on one container, remove that container, and then mount the same volume on another container, use a named volume. It is possible to mount an anonymous volume on one container, remove that container, and then mount the anonymous volume on another container, but it is not recommended to do so.
docker create -v example below performs the following operations:
- Creates a container named
- Mounts the named volume
myDatafolder on that container, starts the container, and attaches to it.
- After performing operations in
volume1:/myData, stops and removes
- Creates a container named
container2from the Ubuntu image.
docker -H virtual_container_host_address:2376 --tls create --name container1 -v volume1:/myData busybox docker start container1 docker attach container1 [Perform container operations and detach] docker stop container1 docker rm container1 docker create -it --name container2 -v volume1:/myData ubuntu docker start container2 docker attach container2 [Perform container operations with the same volume that was previously mounted to container1]
If your volume store is in an NFS share point, sharing volumes between containers is not subject to any limitations. In vSphere Integrated Containers, the
local driver is the vSphere Integrated Containers Docker personality. Consequently, the way to create NFS volumes with vSphere Integrated Containers is slightly different to how you do it with regular Docker. All that you need to do to create an NFS volume for a container is provide the name of the appropriate volume store in the
docker volume create command.
docker volume create --opt volumestore=nfs_volumestore_name
NOTE: vSphere Integrated Containers mounts NFS volumes as
root. Consequently, if containers are to run as non-root users, the volume store must be configured with the correct permissions so that the non-root users can access it. For information about how to configure NFS volume stores for non-root users, see About NFS Volume Stores and Permissions in vSphere Integrated Containers for vSphere Administrators.
To get information about a volume, run
docker volume inspect and specify the name of the volume.
docker -H virtual_container_host_address:2376 --tls volume inspect volume_name
To delete a volume, run
docker volume rm and specify the name of the volume to delete.
docker -H virtual_container_host_address:2376 --tls volume rm volume_name
To remove a container and anonymous volumes joined to that container, run
docker rm -v. If an anonymous volume is in use by another container, it is not removed.
$ docker rm -v container1
To run a container that creates anonymous volumes and then removes those volumes at the end of its run, run
docker run --rm.
$ docker run --rm container1