4.8 KiB
| advisory | hide_from_sitemap | description | keywords | redirect_from | title | ||
|---|---|---|---|---|---|---|---|
| swarm-standalone | true | Swarm API | docker, swarm, clustering, 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 Engine API.
Missing endpoints
Some endpoints have not yet been implemented and returns 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