Add new `HostConfig` field, `Mounts`. #22373

cpuguy83 · 2016-04-27T19:46:47Z

- What I did
Add capability to /containers/create API to specify mounts in a more granular and safer way

Mounts allows users to specify in a much safer way the volumes they
want to use in the container.

- How I did it
Add new field Mounts to HostConfig as well as new MountConfig

This replaces Binds and Volumes, which both still exist, but
Mounts and Binds/Volumes are exclusive.
The CLI will continue to use Binds and Volumes due to concerns with
parsing the volume specs on the client side and cross-platform support.

- How to verify it
Example usage of Mounts:

$ curl -XPOST localhost:2375/containers/create -d '{
  "Image": "alpine:latest",
  "HostConfig": {
    "Mounts": [{
      "Type": "Volume",
      "Destination": "/foo"
      },{
      "Type": "bind",
      "Source": "/var/run/docker.sock",
      "Destination": "/var/run/docker.sock",
      },{
      "Type": "volume",
      "Name": "important_data",
      "Target": "/var/data",
      "Mode": "ro"
      "Volume": {
    "Driver": "awesomeStorage",
    "DriverOpts": { "Size": "10G" }
    }
      }]
    }
}'

There are currently 2 types of mounts:

bind: Paths on the host that get mounted into the
container. Paths must exist prior to creating the container.
volume: Volumes that persist after the
container is removed.

Not all fields are available in each type, and validation is done to
ensure these fields aren't mixed up between types.

- Description for the changelog

Add capability to /containers/create API to specify mounts in a more granular and safer way

- A picture of a cute animal (not mandatory but encouraged)

cpuguy83 · 2016-04-27T20:23:56Z

Have some cleanup on windows and probably some reconciliation on validations between the string spec (-v /foo:/bar:baz) and the new MountConfig style... they should be the same, but there is duplicated logic that is likely best not to duplicate.

stevvooe · 2016-04-27T21:22:32Z

docs/reference/api/docker_remote_api_v1.24.md

+    -   **Mounts** - List of mount configurations to create the container with. This replaces `Binds` and `Volumes`. If `Mounts` is specified along with either `Binds` or `Volumes`, the request will be rejected. Fields for a mount configuration:
+          + **Type** - String specifying the type of mount, e.g. `hostbind`, `ephemeral`, or `persistent` (required)
+          + **Source** - String specifying the host path to use for the mount. Path must exist. (required, `hostbind` only)
+          + **Destination** - String specifying the container destination path for the mount (required)


Target, only because it is shorter.

The reason I used "Destination" is because we already use this term in container.MountPoints

stevvooe · 2016-04-27T21:32:25Z

@cpuguy83 Overall, design LGTM. I have a few naming concerns, but those are easy to work out.

I would like to see a mapping for the current "volume syntax" to these types, as part of this effort. It should be straightforward to work out.

cpuguy83 · 2016-04-28T21:08:44Z

Ok, this is updated, more tests, reconciled some of the validation/parsing between the string spec parser and the new config type... though I did not address @stevvooe's concerns yet

thaJeztah · 2016-09-13T09:47:12Z

docs/reference/api/docker_remote_api_v1.25.md

+        - **VolumeOptions** – Optional configuration for the `volume` type.
+            - **NoCopy** – A boolean indicating if volume should be
+              populated with the data from the target. (Default false)
+            - **Labels** – User-defined name and labels for the volume.


I think we should have some more information about the format used for "labels" (is it a list? a map?)

thaJeztah · 2016-09-13T10:04:44Z

One comment w.r.t. docs; @cpuguy83 let me know if you want to address that in this PR or a follow up

`Mounts` allows users to specify in a much safer way the volumes they want to use in the container. This replaces `Binds` and `Volumes`, which both still exist, but `Mounts` and `Binds`/`Volumes` are exclussive. The CLI will continue to use `Binds` and `Volumes` due to concerns with parsing the volume specs on the client side and cross-platform support (for now). The new API follows exactly the services mount API. Example usage of `Mounts`: ``` $ curl -XPOST localhost:2375/containers/create -d '{ "Image": "alpine:latest", "HostConfig": { "Mounts": [{ "Type": "Volume", "Target": "/foo" },{ "Type": "bind", "Source": "/var/run/docker.sock", "Target": "/var/run/docker.sock", },{ "Type": "volume", "Name": "important_data", "Target": "/var/data", "ReadOnly": true, "VolumeOptions": { "DriverConfig": { Name: "awesomeStorage", Options: {"size": "10m"}, Labels: {"some":"label"} } }] } }' ``` There are currently 2 types of mounts: - **bind**: Paths on the host that get mounted into the container. Paths must exist prior to creating the container. - **volume**: Volumes that persist after the container is removed. Not all fields are available in each type, and validation is done to ensure these fields aren't mixed up between types. Signed-off-by: Brian Goff <cpuguy83@gmail.com>

Signed-off-by: Brian Goff <cpuguy83@gmail.com>

thaJeztah · 2016-09-13T13:59:10Z

LGTM!

cpuguy83 · 2016-09-13T18:40:00Z

🎉

AkihiroSuda · 2016-09-22T14:24:24Z

Is there a PR or a plan to support this new Mount in Swarmkit?

I'd like to use it in #26331
(CC @justincormack )

justincormack · 2016-09-22T14:32:01Z

@AkihiroSuda it is used in swarmkit, it is not yet supported on docker run cli, but with this PR it is in API.

cpuguy83 · 2016-09-22T14:33:16Z

Well, swarmkit is still using the Binds API.

justincormack · 2016-09-22T14:34:25Z

oh, sorry.

AkihiroSuda · 2016-09-22T18:42:07Z

Thank you, and while looking into the implementation, I got surprised that Swarmkit defines MountTypeTmpfs but the engine API not.
Is there plan to migrate tmpfs to the new mount api as well?
If so, can I open PR?

https://github.com/docker/docker/blob/master/api/types/mount/mount.go#L7-L10
https://github.com/docker/swarmkit/blob/master/api/types.proto#L140-L142

cpuguy83 · 2016-09-22T18:43:35Z

@AkihiroSuda Yes, tmpfs needs to be implemented as well, thanks!

AkihiroSuda · 2016-09-22T22:10:32Z

Implemented MountTypeTmpfs in #26837
Please look into this? @cpuguy83

GordonTheTurtle added platform/windows status/0-triage labels Apr 27, 2016

cpuguy83 force-pushed the add_mounts_api_on_create branch from b8223b6 to ba06fec Compare April 27, 2016 19:51

cpuguy83 added status/1-design-review and removed status/0-triage labels Apr 27, 2016

icecrime added status/failing-ci Indicates that the PR in its current state fails the test suite and removed platform/windows labels Apr 27, 2016

cpuguy83 changed the title ~~Add new HostConfig field, Mounts.~~ [WIP] Add new HostConfig field, Mounts. Apr 27, 2016

stevvooe reviewed Apr 27, 2016
View reviewed changes

cpuguy83 force-pushed the add_mounts_api_on_create branch from ba06fec to 44e31b8 Compare April 28, 2016 21:07

cpuguy83 changed the title ~~[WIP] Add new HostConfig field, Mounts.~~ Add new HostConfig field, Mounts. Apr 28, 2016

cpuguy83 force-pushed the add_mounts_api_on_create branch 8 times, most recently from 4851f95 to fc1538a Compare May 2, 2016 19:20

cpuguy83 mentioned this pull request May 2, 2016

Volume mounts moby/swarmkit#489

Closed

cpuguy83 force-pushed the add_mounts_api_on_create branch 4 times, most recently from 0b8f1b5 to 241412f Compare May 3, 2016 16:07

thaJeztah reviewed Sep 13, 2016
View reviewed changes

cpuguy83 added 2 commits September 13, 2016 09:55

Migrate old mount format to use mount specs

29b1c1d

Signed-off-by: Brian Goff <cpuguy83@gmail.com>

cpuguy83 force-pushed the add_mounts_api_on_create branch from d182d62 to 29b1c1d Compare September 13, 2016 13:55

thaJeztah added status/4-merge impact/api impact/changelog and removed status/3-docs-review labels Sep 13, 2016

cpuguy83 merged commit b4c1645 into moby:master Sep 13, 2016

cpuguy83 deleted the add_mounts_api_on_create branch September 13, 2016 18:39

justincormack mentioned this pull request Sep 14, 2016

[EXPERIMENTAL] new mount type: introspection #26331

Closed

7 tasks

thaJeztah mentioned this pull request Sep 17, 2016

Move HostConfig.Mounts to correct API version #26653

Merged

AkihiroSuda mentioned this pull request Sep 22, 2016

cli: add --mount to docker run #26825

Merged

pacoxu mentioned this pull request Oct 31, 2016

"invalid volume mount source, must not be an absolute path" occurred when using docker service create --mount type=volume #25912

Closed

piascikj mentioned this pull request Oct 4, 2017

This is probably not necessary once #22373 is merged piascikj/moby#680

Open

thaJeztah mentioned this pull request Nov 22, 2017

Docker CLI should use mount API for --tmpfs docker/cli#710

Open

piascikj mentioned this pull request Jan 9, 2018

This is probably not necessary once #22373 is merged imdone/moby#64

Open

silviot mentioned this pull request May 20, 2019

Support mounting directories with a : (colon) in their path containers/buildah#1597

Closed

thaJeztah mentioned this pull request Mar 8, 2021

Schema of Swagger/OpenAPI specification contains invalid property #42120

Closed

thaJeztah mentioned this pull request Mar 13, 2023

Fix pruning anon volume created from image config #45147

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add new `HostConfig` field, `Mounts`. #22373

Add new `HostConfig` field, `Mounts`. #22373

cpuguy83 commented Apr 27, 2016 •

edited

Loading

cpuguy83 commented Apr 27, 2016

stevvooe Apr 27, 2016

cpuguy83 Apr 28, 2016

stevvooe commented Apr 27, 2016

cpuguy83 commented Apr 28, 2016

thaJeztah Sep 13, 2016

cpuguy83 Sep 13, 2016

thaJeztah Sep 13, 2016

thaJeztah commented Sep 13, 2016

thaJeztah commented Sep 13, 2016

cpuguy83 commented Sep 13, 2016

AkihiroSuda commented Sep 22, 2016

justincormack commented Sep 22, 2016

cpuguy83 commented Sep 22, 2016

justincormack commented Sep 22, 2016

AkihiroSuda commented Sep 22, 2016 •

edited

Loading

cpuguy83 commented Sep 22, 2016

AkihiroSuda commented Sep 22, 2016

Add new HostConfig field, Mounts. #22373

Add new HostConfig field, Mounts. #22373

Conversation

cpuguy83 commented Apr 27, 2016 • edited Loading

cpuguy83 commented Apr 27, 2016

stevvooe Apr 27, 2016

Choose a reason for hiding this comment

cpuguy83 Apr 28, 2016

Choose a reason for hiding this comment

stevvooe commented Apr 27, 2016

cpuguy83 commented Apr 28, 2016

thaJeztah Sep 13, 2016

Choose a reason for hiding this comment

cpuguy83 Sep 13, 2016

Choose a reason for hiding this comment

thaJeztah Sep 13, 2016

Choose a reason for hiding this comment

thaJeztah commented Sep 13, 2016

thaJeztah commented Sep 13, 2016

cpuguy83 commented Sep 13, 2016

AkihiroSuda commented Sep 22, 2016

justincormack commented Sep 22, 2016

cpuguy83 commented Sep 22, 2016

justincormack commented Sep 22, 2016

AkihiroSuda commented Sep 22, 2016 • edited Loading

cpuguy83 commented Sep 22, 2016

AkihiroSuda commented Sep 22, 2016

Add new `HostConfig` field, `Mounts`. #22373

Add new `HostConfig` field, `Mounts`. #22373

cpuguy83 commented Apr 27, 2016 •

edited

Loading

AkihiroSuda commented Sep 22, 2016 •

edited

Loading