Docker Swarm API
The Docker Swarm API is mostly compatible with the Docker Remote API. This document is an overview of the differences between the Swarm API and the Docker Remote API.
Missing endpoints
Some endpoints have not yet been implemented and will return a 404 error.
POST "/images/create" : "docker import" flow not implement
Endpoints which behave differently
Endpoint | Differences |
---|---|
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 |
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. |
Registry Authentication
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
Authenticate using registry tokens
Note: This example requires Docker Engine 1.10 with auth token support. For older Engine versions, refer to authenticate using username and password
This example uses the jq
command-line utility. To run this example, install jq
using your package manager (apt-get install jq
or yum install jq
).
REPO=yourrepo/yourimage REPO_USER=yourusername read -s PASSWORD AUTH_URL=https://auth.docker.io/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
Add the header you’ve calculated to your ~/.docker/config.json
:
"HttpHeaders": { "X-Registry-Auth": "<HEADER string from above>" }
You can now authenticate to the registry, and run private images on Swarm:
$ 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 for a more secure approach.
First, calculate the header
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
:
"HttpHeaders": { "X-Registry-Auth": "<HEADER string from above>" }
You can now authenticate to the registry, and run private images on Swarm:
$ docker run --rm -it yourprivateimage:latest
Please login to continue.