docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1845 from thaJeztah/fix-api-markdown 

Update Swarm API documentation
This commit is contained in:
Alexandre Beslic 2016-03-02 11:23:04 -08:00
parent 5ce850f0f4 f9aca81b67
commit 045bfe93d1
1 changed files with 137 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

185
docs/swarm-api.md
View File

@ -12,7 +12,10 @@ weight=99
# Docker Swarm API
The Docker Swarm API is mostly compatible with the [Docker Remote API](https://docs.docker.com/reference/api/docker_remote_api/). This document is an overview of the differences between the Swarm API and the Docker Remote API.
The Docker Swarm API is mostly compatible with the [Docker Remote
API](https://docs.docker.com/engine/reference/api/docker_remote_api/). This
document is an overview of the differences between the Swarm API and the Docker
Remote API.
## Missing endpoints
@ -24,70 +27,156 @@ POST "/images/create" : "docker import" flow not implement
## Endpoints which behave differently
* `GET "/containers/{name:.*}/json"`: New field `Node` added:
```json
<table>
<tr>
<th>Endpoint</th>
<th>Differences</th>
</tr>
<tr>
<td>
<code>GET "/containers/{name:.*}/json"</code>
</td>
<td>
New field <code>Node</code> added:<br />
<pre>
"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`
"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"
}
</pre>
</td>
</tr>
<tr>
<td>
<code>GET "/containers/{name:.*}/json"</code>
</td>
<td>
<code>HostIP</code> replaced by the the actual Node's IP if <code>HostIP</code> is <code>0.0.0.0</code>
</td>
</tr>
<tr>
<td>
<code>GET "/containers/json"</code>
</td>
<td>
Node's name prepended to the container name.
</td>
</tr>
<tr>
<td>
<code>GET "/containers/json"</code>
</td>
<td>
<code>HostIP</code> replaced by the the actual Node's IP if <code>HostIP</code> is <code>0.0.0.0</code>
</td>
</tr>
<tr>
<td>
<code>GET "/containers/json"</code>
</td>
<td>
Containers started from the <code>swarm</code> official image are hidden by default, use <code>all=1</code> to display them.
</td>
</tr>
<tr>
<td>
<code>GET "/images/json"</code>
</td>
<td>
Use <code>--filter node=&lt;Node name&gt;</code> to show images of the specific node.
</td>
</tr>
<tr>
<td>
<code>POST "/containers/create"</code>
</td>
<td>
<code>CpuShares</code> in <code>HostConfig</code> sets the number of CPU cores allocated to the container.
</td>
</tr>
</table>
* `GET "/containers/json"`: Node's name prepended to the container name.
## Registry Authentication
* `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 a X-Registry-Config header.
If provided, this header will be passed down to the engine if the image must be pulled
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
The following two examples demonstrate how to utilize this using the existing Docker CLI
* CLI usage example using username/password:
### Authenticate using registry tokens
```bash
# Calculate the header
REPO_USER=yourusername
read -s PASSWORD
HEADER=$(echo "{\"username\":\"${REPO_USER}\",\"password\":\"${PASSWORD}\"}"|base64 -w 0 )
unset PASSWORD
echo HEADER=$HEADER
> **Note:** This example requires Docker Engine 1.10 with auth token support.
> For older Engine versions, refer to [authenticate using username and
> password](#authenticate-using-username-and-password)
# Then add the following to your ~/.docker/config.json
"HttpHeaders": {
"X-Registry-Auth": "<HEADER string from above>"
}
This example uses the [`jq` command-line utility](https://stedolan.github.io/jq/).
To run this example, install `jq` using your package manager (`apt-get install jq` or `yum install jq`).
# Now run a private image against swarm:
docker run --rm -it yourprivateimage:latest
```
* CLI usage example using registry tokens: (Requires engine 1.10 with new auth token support)
```bash
```bash
REPO=yourrepo/yourimage
REPO_USER=yourusername
read -s PASSWORD
AUTH_URL=https://auth.docker.io/token
TOKEN=$(curl -s -u "${REPO_USER}:${PASSWORD}" "${AUTH_URL}?scope=repository:${REPO}:pull&service=registry.docker.io" |
jq -r ".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
# Update the docker config as above, but the token will expire quickly...
```
Add the header you've calculated to your `~/.docker/config.json`:
```json
"HttpHeaders": {
"X-Registry-Auth": "<HEADER string from above>"
}
```
You can now authenticate to the registry, and run private images on Swarm:
```bash
$ 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](#authenticate-using-registry-tokens)
> for a more secure approach.
First, calculate the header
```bash
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`:
```json
"HttpHeaders": {
"X-Registry-Auth": "<HEADER string from above>"
}
```
You can now authenticate to the registry, and run private images on Swarm:
```bash
$ docker run --rm -it yourprivateimage:latest
```
## Docker Swarm documentation index