Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

engine: volume subpath mount #20577

Merged
merged 1 commit into from
Aug 12, 2024
Merged

engine: volume subpath mount #20577

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 41 additions & 0 deletions content/engine/storage/volumes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,10 @@ If you need to specify volume driver options, you must use `--mount`.
- The `destination` takes as its value the path where the file or directory
is mounted in the container. Can be specified as `destination`, `dst`,
or `target`.
- The `volume-subpath` option takes a path to a subdirectory within the
volume to mount into the container. The subdirectory must exist in the
volume before the volume is mounted to a container.
See [Mount a volume subdirectory](#mount-a-volume-subdirectory).
- The `readonly` option, if present, causes the bind mount to be [mounted into
the container as read-only](#use-a-read-only-volume). Can be specified as `readonly` or `ro`.
- The `volume-opt` option, which can be specified more than once, takes a
Expand Down Expand Up @@ -404,6 +408,43 @@ $ docker container rm nginxtest
$ docker volume rm nginx-vol
```

## Mount a volume subdirectory

When you mount a volume to a container, you can specify a subdirectory of the
volume to use, with the `volume-subpath` parameter for the `--mount` flag. The
subdirectory that you specify must exist in the volume before you attempt to
mount it into a container; if it doesn't exist, the mount fails.

Specifying `volume-subpath` is useful if you only want to share a specific
portion of a volume with a container. Say for example that you have multiple
containers running and you want to store logs from each container in a shared
volume. You can create a subdirectory for each container in the shared volume,
and mount the subdirectory to the container.

The following example creates a `logs` volume and initiates the subdirectories
`app1` and `app2` in the volume. It then starts two containers and mounts one
of the subdirectories of the `logs` volume to each container. This example
assumes that the processes in the containers write their logs to
`/var/log/app1` and `/var/log/app2`.

```console
$ docker volume create logs
$ docker run --rm \
--mount src=logs,dst=/logs \
alpine mkdir -p /logs/app1 /logs/app2
$ docker run -d \
--name=app1 \
--mount src=logs,dst=/var/log/app1/,volume-subpath=app1 \
app1:latest
$ docker run -d \
--name=app2 \
--mount src=logs,dst=/var/log/app2,volume-subpath=app2 \
app2:latest
```

With this setup, the containers write their logs to separate subdirectories of
the `logs` volume. The containers can't access the other container's logs.

## Share data between machines

When building fault-tolerant applications, you may need to configure multiple
Expand Down