diff --git a/docs/swarm-api.md b/docs/swarm-api.md index d571a95cee..ff5f3ac937 100644 --- a/docs/swarm-api.md +++ b/docs/swarm-api.md @@ -12,7 +12,10 @@ weight=99 # Docker Swarm API -The Docker Swarm API is mostly compatible with the [Docker Remote API](https://docs.docker.com/reference/api/docker_remote_api/). This document is an overview of the differences between the Swarm API and the Docker Remote API. +The Docker Swarm API is mostly compatible with the [Docker Remote +API](https://docs.docker.com/engine/reference/api/docker_remote_api/). This +document is an overview of the differences between the Swarm API and the Docker +Remote API. ## Missing endpoints @@ -24,70 +27,156 @@ POST "/images/create" : "docker import" flow not implement ## Endpoints which behave differently -* `GET "/containers/{name:.*}/json"`: New field `Node` added: - -```json + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EndpointDifferences
+ GET "/containers/{name:.*}/json" + + New field Node added:
+
 "Node": {
-	"Id": "ODAI:IC6Q:MSBL:TPB5:HIEE:6IKC:VCAM:QRNH:PRGX:ERZT:OK46:PMFX",
-	"Ip": "0.0.0.0",
-	"Addr": "http://0.0.0.0:4243",
-	"Name": "vagrant-ubuntu-saucy-64",
-    },
-```
-* `GET "/containers/{name:.*}/json"`: `HostIP` replaced by the the actual Node's IP if `HostIP` is `0.0.0.0`
+    "Id": "ODAI:IC6Q:MSBL:TPB5:HIEE:6IKC:VCAM:QRNH:PRGX:ERZT:OK46:PMFX",
+    "Ip": "0.0.0.0",
+    "Addr": "http://0.0.0.0:4243",
+    "Name": "vagrant-ubuntu-saucy-64"
+}
+
+
+ GET "/containers/{name:.*}/json" + + HostIP replaced by the the actual Node's IP if HostIP is 0.0.0.0 +
+ GET "/containers/json" + + Node's name prepended to the container name. +
+ GET "/containers/json" + + HostIP replaced by the the actual Node's IP if HostIP is 0.0.0.0 +
+ GET "/containers/json" + + Containers started from the swarm official image are hidden by default, use all=1 to display them. +
+ GET "/images/json" + + Use --filter node=<Node name> to show images of the specific node. +
+ POST "/containers/create" + + CpuShares in HostConfig sets the number of CPU cores allocated to the container. +
-* `GET "/containers/json"`: Node's name prepended to the container name. +## Registry Authentication -* `GET "/containers/json"`: `HostIP` replaced by the the actual Node's IP if `HostIP` is `0.0.0.0` - -* `GET "/containers/json"` : Containers started from the `swarm` official image are hidden by default, use `all=1` to display them. - -* `GET "/images/json"` : Use '--filter node=\' to show images of the specific node. - -* `POST "/containers/create"`: `CpuShares` in `HostConfig` sets the number of CPU cores allocated to the container. - -# Registry Authentication - -During container create calls, the swarm API will optionally accept a X-Registry-Config header. -If provided, this header will be passed down to the engine if the image must be pulled +During container create calls, the swarm API will optionally accept an `X-Registry-Auth` header. +If provided, this header is passed down to the engine if the image must be pulled to complete the create operation. -The following two examples demonstrate how to utilize this using the existing docker CLI +The following two examples demonstrate how to utilize this using the existing Docker CLI -* CLI usage example using username/password: +### Authenticate using registry tokens - ```bash -# Calculate the header -REPO_USER=yourusername -read -s PASSWORD -HEADER=$(echo "{\"username\":\"${REPO_USER}\",\"password\":\"${PASSWORD}\"}"|base64 -w 0 ) -unset PASSWORD -echo HEADER=$HEADER +> **Note:** This example requires Docker Engine 1.10 with auth token support. +> For older Engine versions, refer to [authenticate using username and +> password](#authenticate-using-username-and-password) -# Then add the following to your ~/.docker/config.json -"HttpHeaders": { - "X-Registry-Auth": "
" -} +This example uses the [`jq` command-line utility](https://stedolan.github.io/jq/). +To run this example, install `jq` using your package manager (`apt-get install jq` or `yum install jq`). -# Now run a private image against swarm: -docker run --rm -it yourprivateimage:latest -``` - -* CLI usage example using registry tokens: (Requires engine 1.10 with new auth token support) - - ```bash +```bash REPO=yourrepo/yourimage REPO_USER=yourusername read -s PASSWORD AUTH_URL=https://auth.docker.io/token -TOKEN=$(curl -s -u "${REPO_USER}:${PASSWORD}" "${AUTH_URL}?scope=repository:${REPO}:pull&service=registry.docker.io" | - jq -r ".token") + +# obtain a JSON token, and extract the "token" value using 'jq' +TOKEN=$(curl -s -u "${REPO_USER}:${PASSWORD}" "${AUTH_URL}?scope=repository:${REPO}:pull&service=registry.docker.io" | jq -r ".token") HEADER=$(echo "{\"registrytoken\":\"${TOKEN}\"}"|base64 -w 0 ) echo HEADER=$HEADER - -# Update the docker config as above, but the token will expire quickly... ``` +Add the header you've calculated to your `~/.docker/config.json`: + +```json +"HttpHeaders": { + "X-Registry-Auth": "
" +} +``` + +You can now authenticate to the registry, and run private images on Swarm: + +```bash +$ docker run --rm -it yourprivateimage:latest +``` + + +Be aware that tokens are short-lived and will expire quickly. + + +### Authenticate using username and password + +> **Note:** this authentication method stores your credentials unencrypted +> on the filesystem. Refer to [Authenticate using registry tokens](#authenticate-using-registry-tokens) +> for a more secure approach. + + +First, calculate the header + +```bash +REPO_USER=yourusername +read -s PASSWORD +HEADER=$(echo "{\"username\":\"${REPO_USER}\",\"password\":\"${PASSWORD}\"}" | base64 -w 0 ) +unset PASSWORD +echo HEADER=$HEADER +``` + +Add the header you've calculated to your `~/.docker/config.json`: + +```json +"HttpHeaders": { + "X-Registry-Auth": "
" +} +``` + +You can now authenticate to the registry, and run private images on Swarm: + +```bash +$ docker run --rm -it yourprivateimage:latest +``` + + ## Docker Swarm documentation index