Volumes, Named Volumes, Volume Drivers, Backup/Restore, Sharing, and Persistent Data Patterns: Diagnostics, Failure Modes, Security, and Performance

1. Evidence-first storage diagnostic sequence

1. Record host/platform and docker version, docker info, active context, Compose version.
2. Capture the exact image/container IDs and application logs before restart or replacement.
3. Capture docker volume inspect, driver/options, labels, and consuming-container mounts.
4. Inspect numeric UID/GID and modes from inside a safe helper/container.
5. Identify whether the failed path is the writable layer, named volume, bind mount, tmpfs, or driver/plugin storage.
6. Preserve backup artifact checksum, creation time, source data version, and consistency method.
7. For remote/plugin storage, capture provider/driver health without exposing credentials.
8. Apply the smallest correction and rerun only the affected verification.

2. Failure mode: confusing Compose teardown with data cleanup

Ordinary docker compose down removes project containers and networks but preserves named volumes. The --volumes option changes the data lifecycle and removes project-declared named volumes plus attached anonymous volumes. That is a destructive storage decision, not a normal application stop.

Before any teardown in a stateful project, render the normalized model, list project-labeled volumes, record whether each volume is project-managed or external, and decide retention explicitly.

docker compose config
# Read-only inventory example for a disposable project:
docker volume ls --filter label=com.docker.compose.project=myproject

# Safe default teardown preserves named volumes:
docker compose down

# Do not add the volume-deletion option unless data destruction is the explicit, verified intent.

3. Failure mode: blind volume pruning

An “unused” volume means Docker sees no current container reference. It does not mean the data has no business owner, retention requirement, backup dependency, or planned future reuse. Broad prune commands are therefore excluded from this academy's routine troubleshooting.

Prefer label-based inventory, exact dependency checks, and exact docker volume rm NAME only after backup/retention decisions are proven. Docker's refusal to remove an in-use volume is a helpful guard, but it cannot protect an unreferenced volume whose data still matters.

4. Intentionally broken example: restored data has the wrong owner

Create a disposable volume containing a file that only root may read. Then run a consumer as UID/GID 1001. Preserve the error and ownership evidence before fixing it.

docker volume create   --label devops-academy.lab=ch20-diag   da20-perm

docker run --rm --mount type=volume,src=da20-perm,dst=/data   busybox:1.36.1 sh -c '
    echo protected-state > /data/state.txt
    chmod 600 /data/state.txt
    chown 0:0 /data/state.txt
    ls -ln /data/state.txt
  '

# Preserve the first failure:
docker run --rm --user 1001:1001   --mount type=volume,src=da20-perm,dst=/data,readonly   busybox:1.36.1 cat /data/state.txt || true

# Evidence, still without changing the file:
docker run --rm --mount type=volume,src=da20-perm,dst=/data,readonly   busybox:1.36.1 ls -ln /data/state.txt

docker volume inspect da20-perm

The failure is not a network or image-pull problem: the process UID does not match the file authorization. In this synthetic lab, correct the intended owner explicitly, then rerun the same consumer.

docker run --rm --mount type=volume,src=da20-perm,dst=/data   busybox:1.36.1 chown 1001:1001 /data/state.txt

docker run --rm --user 1001:1001   --mount type=volume,src=da20-perm,dst=/data,readonly   busybox:1.36.1 cat /data/state.txt

docker rm -f da20-perm-consumer 2>/dev/null || true
docker volume rm da20-perm

In production, the correct ownership may instead be established at image startup, provisioning, restore tooling, or application initialization. Do not apply recursive ownership changes blindly to unknown data.

5. Failure mode: copying a live database directory

A tar command can read files while an application is modifying them. The resulting archive may contain a combination of moments that the database cannot recover as a coherent transaction state. A successful tar exit code only proves the archive command completed.

Use the database's documented dump/snapshot/checkpoint/backup mechanism, or deliberately quiesce/stop writes when that is the supported consistency method. Record the application checkpoint/LSN/transaction marker or backup job ID alongside the volume snapshot/archive.

6. Failure mode: assuming every driver behaves like local storage

Remote/plugin drivers may have their own mount lifecycle, snapshot capability, access modes, network requirements, credentials, capacity constraints, and failure recovery. A local-driver Mountpoint path is not a universal concept. Always inspect Driver/Options first and consult the selected driver's authoritative documentation.

7. Storage performance without superstition

Measure the application workload, filesystem/backend latency, host resource pressure, and driver path before blaming Docker. A remote driver adds network/storage latency; Docker Desktop introduces a managed VM/storage path; synchronous database durability can be intentionally slower than buffered writes. Performance tuning that weakens durability is a data-loss tradeoff and must be explicit.

Capture baseline operation latency, IOPS/throughput where available, host disk space, application fsync/checkpoint behavior, and backup duration. Optimize the measured bottleneck without disabling durability guarantees casually.

8. Failure matrix

9. Diagnostic cleanup rule

Remove only disposable diagnostic objects with exact names after verification. Never delete unknown Docker storage directories manually, never replace ownership analysis with indiscriminate world-writable permissions, and never force a volume removal merely to clear an error.

Knowledge check

Official references and version notes

• Docker Docs — Volumes — volume lifecycle, mount behavior, backup/restore examples, read-only mounts, volume-nocopy, subpaths, and removal.
• Docker CLI — docker volume — create, inspect, list, remove, prune, and update subcommands.
• Docker CLI — docker volume inspect — driver, labels, options, scope, creation timestamp, and mountpoint where the driver exposes one.
• Docker CLI — docker volume create — driver selection, driver options, labels, and cluster-volume options.
• Docker CLI — docker volume rm — exact volume removal and in-use protection.
• Compose Specification — top-level volumes — project-managed versus external volumes and driver/option declarations.
• Docker CLI — docker compose down — default retention, --volumes deletion semantics, and external-volume protection.
• Docker Docs — Volume plugins — driver boundaries and why remote/plugin semantics must be learned from the selected driver.
• Docker Engine 29 release notes — current Engine baseline.