Docker Swarm API

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

"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"
}

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

Docker Swarm documentation index

• Docker Swarm overview
• Discovery options
• Scheduler strategies
• Scheduler filters