Safely Change a Docker Cluster Volume's Availability

docker volume update moves a Docker Swarm cluster volume between active, pause and drain, and a careless drain can stop a running Task on the spot. This guide gets you through pausing or draining a cluster volume, checking the result, and putting it back to active once maintenance is done.

Allow about fifteen minutes for the command and your checks. You need a Docker Swarm manager, a CSI-backed cluster volume, and enough access to query and change the Docker daemon. The installed command comes from Docker CE CLI 29.8.1, package version 5:29.8.1-1~ubuntu.24.04~noble. This is an administrative operation: it does not apply to a normal local volume created for an ordinary container.

1. Confirm that the volume is a cluster volume

Start with a read-only inventory. The --cluster option asks Docker to show cluster-specific columns, including availability:

$ docker volume ls --cluster
VOLUME NAME   GROUP     DRIVER    AVAILABILITY   STATUS
DATA_VOLUME   storage   CSI_DRIVER active        in use (1 node)

Replace DATA_VOLUME with the exact name from your own output; the driver and status will differ on your cluster. If the volume does not appear, stop here. A conventional volume is outside this command's scope, and inventing an update workflow from its name would be a bad way to perform storage maintenance.

Checkpoint: record the current availability and status before changing anything. You will use the recorded availability as part of your recovery plan.

2. Choose pause or drain

pause is the gentler option. New Services stop selecting the volume, but existing Tasks keep running. Good for inspection or preparation.
drain is disruptive by design. Docker refuses the volume for new Services and stops Tasks using it, letting Swarm reschedule them where placement rules permit.

$ docker volume update --availability pause DATA_VOLUME

A successful update normally produces no command output, so verify the state instead:

$ docker volume ls --cluster
VOLUME NAME   GROUP     DRIVER    AVAILABILITY   STATUS
DATA_VOLUME   storage   CSI_DRIVER pause         in use (1 node)

The status can vary and the node count is not fixed; the useful check is that the availability column says pause. Existing Tasks are not stopped by this setting.

$ docker volume update --availability drain DATA_VOLUME

Warning: this can interrupt an application and can make its replicas unavailable if there is no suitable destination. Treat it like a service-disrupting maintenance action. Check the affected Services first, and arrange an application-level maintenance window where the workload needs one.

3. Verify rescheduling after a drain

Do not assume a successful update means the application is healthy. Inspect the Services that use the volume:

$ docker service ls
ID             NAME          MODE         REPLICAS   IMAGE
SERVICE_ID     SERVICE_NAME  replicated   2/2        IMAGE_NAME

Then inspect the relevant Service's tasks:

$ docker service ps SERVICE_NAME
ID             NAME             IMAGE       NODE       DESIRED STATE   CURRENT STATE
TASK_ID        SERVICE_NAME.1   IMAGE_NAME  NODE_NAME  Running         Running ... ago

Use the real service name, not the placeholder. The exact table columns and timestamps vary by Docker version. Look for the desired and current state settling on Running, and check that the required replica count has returned. If Tasks are stuck pending, rejected or failed, do not make more storage changes just to force convergence: read the task error and check whether the volume driver exposes the volume on a node that satisfies the Service.

Checkpoint: after a drain, record both docker volume ls --cluster and docker service ps SERVICE_NAME. These answer different questions: the first is the volume's cluster state, the second is the workload's placement.

4. Restore normal availability

When the maintenance or evacuation is complete, return the volume to active:

$ docker volume update --availability active DATA_VOLUME
$ docker volume ls --cluster
VOLUME NAME   GROUP     DRIVER    AVAILABILITY   STATUS
DATA_VOLUME   storage   CSI_DRIVER active        created

The example status is illustrative; an active volume may show a different status, such as being in use on one or more nodes. Confirm the availability value, then recheck the Services that should be able to use the volume.

This is the undo operation for the state change, but it does not resurrect a stopped application or restore data. If a drain stopped a Service Task, Swarm reconciles it according to the Service definition. If the Service was deliberately scaled down or removed during maintenance, restore it using the deployment procedure that created it.

5. Avoid the destructive shortcut

A drained volume can be removed from the cluster only after it has been fully unpublished from all nodes. That boundary exists to prevent removal while a storage plugin still considers the volume in use. Do not treat drain as preparation for an automatic delete, and do not add force flags that are not part of this command.

If your actual goal is deletion, first confirm the data is backed up and that the Service no longer needs the volume. The removal command is a separate operation with a different risk profile. Keep the volume in drain while investigating an in-use condition, and resolve the remaining publisher or workload rather than bypassing the safety check.

Common traps

Treating drain as a preview: an error saying the volume is not a cluster volume usually means it lacks the cluster-specific volume options, or uses a driver without the required cluster integration. Check the inventory and driver before retrying.
Blaming the wrong layer: an error from a non-manager or an inactive Swarm reflects the control-plane context, not a missing availability spelling. Check the local state:
```
$ docker info --format '{{.Swarm.LocalNodeState}} {{.Swarm.ControlAvailable}}'
active true
```
Do not copy that output as a claim about your host. On this machine the read-only check reports an inactive Swarm, so no real volume update was attempted here; a live cluster reports its own state.
Assuming privilege fixes scope: use elevated privileges only if your Docker socket policy requires them, for example by prefixing the command with sudo. Privilege does not turn an ordinary volume into a cluster volume.
Mixed-version Swarms: the installed manpage exposes one option, --availability, with the values active, pause and drain. Current Docker documentation describes it as available from API 1.42, so check daemon and client API compatibility before scheduling maintenance.

Done means

Cluster volume confirmed. The target appears in docker volume ls --cluster.
Baseline recorded. You noted its original availability before changing it.
Mode chosen deliberately. You picked pause or drain with the disruption understood.
Services checked. After a drain, the affected Services have been checked with docker service ps.
Restored or intentional. The volume is back to active when maintenance is complete, unless it is deliberately being kept offline.