From 62fef18d69be7d8c5338fe5a471966dc1e6d68f7 Mon Sep 17 00:00:00 2001
From: Shane da Silva <shane@dasilva.io>
Date: Mon, 7 Mar 2016 01:03:28 +0000
Subject: [PATCH] Fix documentation for creating containers with data volumes

The documentation for Docker 1.10.2 (API version 1.22) mentions under
the "Create a container"[1] section that `HostConfig.Binds` can be given
a "container path" which will automatically "create a new volume for the
container."

I interpreted this to mean it that the following two commands should
have the same net result:

    # Create container with data volume via REST API
    curl --unix-socket /var/run/docker.sock -XPOST \
         http://localhost/containers/create \
         -H"Content-Type: application/json" \
         -d'{
           "Image": "<image-id>",
           ...
           "HostConfig": {
             "Binds": [
               "/some/data/volume"
             ]
           }
         }'

    # Create container with data volume via CLI
    docker create -v /some/data/volume <image-id> <command>

However, this turned out not the be the case, as the former would create
a mount with no source and no corresponding volume:

    ...
    "Mounts": [
      {
        "Source": "",
        "Destination": "/some/data/volume",
        "Driver": "local",
        "Mode": "",
        "RW": true,
        "Propagation": "rprivate"
      }
    ],
    ...
    "Config": {
      ...
      "Volumes": null,
      ...
    }

...whereas the latter would create a volume and mount it:

    ...
    "Mounts": [
      {
        "Name": "9b38af46d6..."
        "Source": "/var/lib/docker/volumes/9b38af46d6.../_data",
        "Destination": "/some/data/volume",
        "Driver": "local",
        "Mode": "",
        "RW": true,
        "Propagation": ""
      }
    ],
    ...
    "Config": {
      ...
      "Volumes": {
        "/some/data/volume": {}
      },
      ...
    }

However, if you instead specify the data volume via the `Volumes` key,
then it works as expected, e.g.

    curl --unix-socket /var/run/docker.sock -XPOST \
         http://localhost/containers/create \
         -H"Content-Type: application/json" \
         -d'{
           "Image": "...",
           ...
           "Volumes": {"/some/data/volume": {}}
          }'

...will create a data volume and mount it.

Thus the documentation is either incorrect, or this is a bug and the
ability to create a data volume via `HostConfig.Binds` does not
work as advertised for API version 1.22 (and likely others).

I concluded that the documentation was incorrect. Since I've only
verified this behavior for Docker 1.10.2, I updated the docs for
API versions 1.22 and 1.23, but this may apply to other versions as
well.

[1] https://docs.docker.com/engine/reference/api/docker_remote_api_v1.22/#create-a-container

Signed-off-by: Shane da Silva <shane@dasilva.io>
---
 docs/reference/api/docker_remote_api_v1.22.md | 8 ++++++--
 docs/reference/api/docker_remote_api_v1.23.md | 8 ++++++--
 2 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/docs/reference/api/docker_remote_api_v1.22.md b/docs/reference/api/docker_remote_api_v1.22.md
index 2965943868..ecd7015ea3 100644
--- a/docs/reference/api/docker_remote_api_v1.22.md
+++ b/docs/reference/api/docker_remote_api_v1.22.md
@@ -233,6 +233,9 @@ Create a container
                "Propagation": ""
              }
            ],
+           "Volumes": {
+             "/volumes/data": {}
+           }
            "WorkingDir": "",
            "NetworkDisabled": false,
            "MacAddress": "12:34:56:78:9a:bc",
@@ -349,7 +352,6 @@ Json Parameters:
 -   **StopSignal** - Signal to stop a container as a string or unsigned integer. `SIGTERM` by default.
 -   **HostConfig**
     -   **Binds** – A list of volume bindings for this container. Each volume binding is a string in one of these forms:
-           + `container_path` to create a new volume for the container
            + `host_path:container_path` to bind-mount a host path into the container
            + `host_path:container_path:ro` to make the bind-mount read-only inside the container.
            + `volume_name:container_path` to bind-mount a volume managed by a volume plugin into the container.
@@ -467,7 +469,9 @@ Return low-level information on the container `id`
 			"StdinOnce": false,
 			"Tty": false,
 			"User": "",
-			"Volumes": null,
+			"Volumes": {
+                          "/volumes/data": {}
+                        },
 			"WorkingDir": "",
 			"StopSignal": "SIGTERM"
 		},
diff --git a/docs/reference/api/docker_remote_api_v1.23.md b/docs/reference/api/docker_remote_api_v1.23.md
index 2f4a66a0fb..95fa21c433 100644
--- a/docs/reference/api/docker_remote_api_v1.23.md
+++ b/docs/reference/api/docker_remote_api_v1.23.md
@@ -252,6 +252,9 @@ Create a container
                "Propagation": ""
              }
            ],
+           "Volumes": {
+             "/volumes/data": {}
+           }
            "WorkingDir": "",
            "NetworkDisabled": false,
            "MacAddress": "12:34:56:78:9a:bc",
@@ -368,7 +371,6 @@ Json Parameters:
 -   **StopSignal** - Signal to stop a container as a string or unsigned integer. `SIGTERM` by default.
 -   **HostConfig**
     -   **Binds** – A list of volume bindings for this container. Each volume binding is a string in one of these forms:
-           + `container_path` to create a new volume for the container
            + `host_path:container_path` to bind-mount a host path into the container
            + `host_path:container_path:ro` to make the bind-mount read-only inside the container.
            + `volume_name:container_path` to bind-mount a volume managed by a volume plugin into the container.
@@ -486,7 +488,9 @@ Return low-level information on the container `id`
 			"StdinOnce": false,
 			"Tty": false,
 			"User": "",
-			"Volumes": null,
+			"Volumes": {
+                          "/volumes/data": {}
+                        },
 			"WorkingDir": "",
 			"StopSignal": "SIGTERM"
 		},