Docker Swarm API

You 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.

Estimated reading time: 3 minutes

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

Docker Swarm documentation index

Rate this page:

 
8
 
5