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

177
docs/swarm-api.md
View File

@ -12,7 +12,10 @@ weight=99
# Docker Swarm API # 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 ## Missing endpoints
@ -24,70 +27,156 @@ POST "/images/create" : "docker import" flow not implement
## Endpoints which behave differently ## Endpoints which behave differently
* `GET "/containers/{name:.*}/json"`: New field `Node` added: <table>
<tr>
```json <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": { "Node": {
"Id": "ODAI:IC6Q:MSBL:TPB5:HIEE:6IKC:VCAM:QRNH:PRGX:ERZT:OK46:PMFX", "Id": "ODAI:IC6Q:MSBL:TPB5:HIEE:6IKC:VCAM:QRNH:PRGX:ERZT:OK46:PMFX",
"Ip": "0.0.0.0", "Ip": "0.0.0.0",
"Addr": "http://0.0.0.0:4243", "Addr": "http://0.0.0.0:4243",
"Name": "vagrant-ubuntu-saucy-64", "Name": "vagrant-ubuntu-saucy-64"
}, }
``` </pre>
* `GET "/containers/{name:.*}/json"`: `HostIP` replaced by the the actual Node's IP if `HostIP` is `0.0.0.0` </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` 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
* `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
to complete the create operation. 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 > **Note:** This example requires Docker Engine 1.10 with auth token support.
# Calculate the header > For older Engine versions, refer to [authenticate using username and
REPO_USER=yourusername > password](#authenticate-using-username-and-password)
read -s PASSWORD
HEADER=$(echo "{\"username\":\"${REPO_USER}\",\"password\":\"${PASSWORD}\"}"|base64 -w 0 )
unset PASSWORD
echo HEADER=$HEADER
# Then add the following to your ~/.docker/config.json This example uses the [`jq` command-line utility](https://stedolan.github.io/jq/).
"HttpHeaders": { To run this example, install `jq` using your package manager (`apt-get install jq` or `yum install jq`).
"X-Registry-Auth": "<HEADER string from above>"
}
# 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=yourrepo/yourimage
REPO_USER=yourusername REPO_USER=yourusername
read -s PASSWORD read -s PASSWORD
AUTH_URL=https://auth.docker.io/token 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 ) HEADER=$(echo "{\"registrytoken\":\"${TOKEN}\"}"|base64 -w 0 )
echo HEADER=$HEADER 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 ## Docker Swarm documentation index