Docker Swarm API
Estimated reading time: 3 minutesYou are viewing docs for legacy standalone Swarm. These topics describe standalone Docker Swarm. In Docker 1.12 and higher, Swarm mode is integrated with Docker Engine. Most users should use integrated Swarm mode — a good place to start is Getting started with swarm mode, Swarm mode CLI commands, and the Get started with Docker walkthrough). Standalone Docker Swarm is not integrated into the Docker Engine API and CLI commands.
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 Engine API.
Missing endpoints
Some endpoints have not yet been implemented and 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 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 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 optionally accepts 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 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