Browse code
bump api version to 1.20
Signed-off-by: Jessica Frazelle <princess@docker.com>
Jessica Frazelle authored on 2015/05/28 11:24:59Showing 4 changed files
- api/common.go
- docs/mkdocs.yml
- docs/sources/reference/api/docker_remote_api.md
- docs/sources/reference/api/docker_remote_api_v1.20.md
| ... | ... |
@@ -16,7 +16,7 @@ import ( |
| 16 | 16 |
|
| 17 | 17 |
// Common constants for daemon and client. |
| 18 | 18 |
const ( |
| 19 |
- APIVERSION version.Version = "1.19" // Current REST API version |
|
| 19 |
+ APIVERSION version.Version = "1.20" // Current REST API version |
|
| 20 | 20 |
DefaultDockerfileName string = "Dockerfile" // Default filename with Docker commands, read by docker build |
| 21 | 21 |
) |
| 22 | 22 |
|
| ... | ... |
@@ -170,6 +170,7 @@ pages: |
| 170 | 170 |
- ['reference/api/docker-io_api.md', 'Reference', 'Docker Hub API'] |
| 171 | 171 |
#- ['reference/image-spec-v1.md', 'Reference', 'Docker Image Specification v1.0.0'] |
| 172 | 172 |
- ['reference/api/docker_remote_api.md', 'Reference', 'Docker Remote API'] |
| 173 |
+- ['reference/api/docker_remote_api_v1.20.md', 'Reference', 'Docker Remote API v1.20'] |
|
| 173 | 174 |
- ['reference/api/docker_remote_api_v1.19.md', 'Reference', 'Docker Remote API v1.19'] |
| 174 | 175 |
- ['reference/api/docker_remote_api_v1.18.md', 'Reference', 'Docker Remote API v1.18'] |
| 175 | 176 |
- ['reference/api/docker_remote_api_v1.17.md', 'Reference', 'Docker Remote API v1.17'] |
| ... | ... |
@@ -30,13 +30,13 @@ page_keywords: API, Docker, rcli, REST, documentation |
| 30 | 30 |
Client applications need to take this into account to ensure |
| 31 | 31 |
they will not break when talking to newer Docker daemons. |
| 32 | 32 |
|
| 33 |
-The current version of the API is v1.19 |
|
| 33 |
+The current version of the API is v1.20 |
|
| 34 | 34 |
|
| 35 | 35 |
Calling `/info` is the same as calling |
| 36 |
-`/v1.19/info`. |
|
| 36 |
+`/v1.20/info`. |
|
| 37 | 37 |
|
| 38 | 38 |
You can still call an old version of the API using |
| 39 |
-`/v1.18/info`. |
|
| 39 |
+`/v1.19/info`. |
|
| 40 | 40 |
|
| 41 | 41 |
## Docker Events |
| 42 | 42 |
|
| ... | ... |
@@ -54,6 +54,14 @@ Running `docker rmi` emits an **untag** event when removing an image name. The |
| 54 | 54 |
|
| 55 | 55 |
> **Acknowledgement**: This diagram and the accompanying text were used with the permission of Matt Good and Gilder Labs. See Matt's original blog post [Docker Events Explained](http://gliderlabs.com/blog/2015/04/14/docker-events-explained/). |
| 56 | 56 |
|
| 57 |
+## v1.20 |
|
| 58 |
+ |
|
| 59 |
+### Full documentation |
|
| 60 |
+ |
|
| 61 |
+[*Docker Remote API v1.20*](/reference/api/docker_remote_api_v1.20/) |
|
| 62 |
+ |
|
| 63 |
+### What's new |
|
| 64 |
+ |
|
| 57 | 65 |
## v1.19 |
| 58 | 66 |
|
| 59 | 67 |
### Full documentation |
| 60 | 68 |
new file mode 100644 |
| ... | ... |
@@ -0,0 +1,2183 @@ |
| 0 |
+page_title: Remote API v1.20 |
|
| 1 |
+page_description: API Documentation for Docker |
|
| 2 |
+page_keywords: API, Docker, rcli, REST, documentation |
|
| 3 |
+ |
|
| 4 |
+# Docker Remote API v1.20 |
|
| 5 |
+ |
|
| 6 |
+## 1. Brief introduction |
|
| 7 |
+ |
|
| 8 |
+ - The Remote API has replaced `rcli`. |
|
| 9 |
+ - The daemon listens on `unix:///var/run/docker.sock` but you can |
|
| 10 |
+ [Bind Docker to another host/port or a Unix socket]( |
|
| 11 |
+ /articles/basics/#bind-docker-to-another-hostport-or-a-unix-socket). |
|
| 12 |
+ - The API tends to be REST. However, for some complex commands, like `attach` |
|
| 13 |
+ or `pull`, the HTTP connection is hijacked to transport `stdout`, |
|
| 14 |
+ `stdin` and `stderr`. |
|
| 15 |
+ - When the client API version is newer than the daemon's, these calls return an HTTP |
|
| 16 |
+ `400 Bad Request` error message. |
|
| 17 |
+ |
|
| 18 |
+# 2. Endpoints |
|
| 19 |
+ |
|
| 20 |
+## 2.1 Containers |
|
| 21 |
+ |
|
| 22 |
+### List containers |
|
| 23 |
+ |
|
| 24 |
+`GET /containers/json` |
|
| 25 |
+ |
|
| 26 |
+List containers |
|
| 27 |
+ |
|
| 28 |
+**Example request**: |
|
| 29 |
+ |
|
| 30 |
+ GET /containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1 |
|
| 31 |
+ |
|
| 32 |
+**Example response**: |
|
| 33 |
+ |
|
| 34 |
+ HTTP/1.1 200 OK |
|
| 35 |
+ Content-Type: application/json |
|
| 36 |
+ |
|
| 37 |
+ [ |
|
| 38 |
+ {
|
|
| 39 |
+ "Id": "8dfafdbc3a40", |
|
| 40 |
+ "Image": "ubuntu:latest", |
|
| 41 |
+ "Command": "echo 1", |
|
| 42 |
+ "Created": 1367854155, |
|
| 43 |
+ "Status": "Exit 0", |
|
| 44 |
+ "Ports": [{"PrivatePort": 2222, "PublicPort": 3333, "Type": "tcp"}],
|
|
| 45 |
+ "SizeRw": 12288, |
|
| 46 |
+ "SizeRootFs": 0 |
|
| 47 |
+ }, |
|
| 48 |
+ {
|
|
| 49 |
+ "Id": "9cd87474be90", |
|
| 50 |
+ "Image": "ubuntu:latest", |
|
| 51 |
+ "Command": "echo 222222", |
|
| 52 |
+ "Created": 1367854155, |
|
| 53 |
+ "Status": "Exit 0", |
|
| 54 |
+ "Ports": [], |
|
| 55 |
+ "SizeRw": 12288, |
|
| 56 |
+ "SizeRootFs": 0 |
|
| 57 |
+ }, |
|
| 58 |
+ {
|
|
| 59 |
+ "Id": "3176a2479c92", |
|
| 60 |
+ "Image": "ubuntu:latest", |
|
| 61 |
+ "Command": "echo 3333333333333333", |
|
| 62 |
+ "Created": 1367854154, |
|
| 63 |
+ "Status": "Exit 0", |
|
| 64 |
+ "Ports":[], |
|
| 65 |
+ "SizeRw":12288, |
|
| 66 |
+ "SizeRootFs":0 |
|
| 67 |
+ }, |
|
| 68 |
+ {
|
|
| 69 |
+ "Id": "4cb07b47f9fb", |
|
| 70 |
+ "Image": "ubuntu:latest", |
|
| 71 |
+ "Command": "echo 444444444444444444444444444444444", |
|
| 72 |
+ "Created": 1367854152, |
|
| 73 |
+ "Status": "Exit 0", |
|
| 74 |
+ "Ports": [], |
|
| 75 |
+ "SizeRw": 12288, |
|
| 76 |
+ "SizeRootFs": 0 |
|
| 77 |
+ } |
|
| 78 |
+ ] |
|
| 79 |
+ |
|
| 80 |
+Query Parameters: |
|
| 81 |
+ |
|
| 82 |
+- **all** – 1/True/true or 0/False/false, Show all containers. |
|
| 83 |
+ Only running containers are shown by default (i.e., this defaults to false) |
|
| 84 |
+- **limit** – Show `limit` last created |
|
| 85 |
+ containers, include non-running ones. |
|
| 86 |
+- **since** – Show only containers created since Id, include |
|
| 87 |
+ non-running ones. |
|
| 88 |
+- **before** – Show only containers created before Id, include |
|
| 89 |
+ non-running ones. |
|
| 90 |
+- **size** – 1/True/true or 0/False/false, Show the containers |
|
| 91 |
+ sizes |
|
| 92 |
+- **filters** - a JSON encoded value of the filters (a `map[string][]string`) to process on the containers list. Available filters: |
|
| 93 |
+ - `exited=<int>`; -- containers with exit code of `<int>` ; |
|
| 94 |
+ - `status=`(`restarting`|`running`|`paused`|`exited`) |
|
| 95 |
+ - `label=key` or `key=value` of a container label |
|
| 96 |
+ |
|
| 97 |
+Status Codes: |
|
| 98 |
+ |
|
| 99 |
+- **200** – no error |
|
| 100 |
+- **400** – bad parameter |
|
| 101 |
+- **500** – server error |
|
| 102 |
+ |
|
| 103 |
+### Create a container |
|
| 104 |
+ |
|
| 105 |
+`POST /containers/create` |
|
| 106 |
+ |
|
| 107 |
+Create a container |
|
| 108 |
+ |
|
| 109 |
+**Example request**: |
|
| 110 |
+ |
|
| 111 |
+ POST /containers/create HTTP/1.1 |
|
| 112 |
+ Content-Type: application/json |
|
| 113 |
+ |
|
| 114 |
+ {
|
|
| 115 |
+ "Hostname": "", |
|
| 116 |
+ "Domainname": "", |
|
| 117 |
+ "User": "", |
|
| 118 |
+ "AttachStdin": false, |
|
| 119 |
+ "AttachStdout": true, |
|
| 120 |
+ "AttachStderr": true, |
|
| 121 |
+ "Tty": false, |
|
| 122 |
+ "OpenStdin": false, |
|
| 123 |
+ "StdinOnce": false, |
|
| 124 |
+ "Env": null, |
|
| 125 |
+ "Cmd": [ |
|
| 126 |
+ "date" |
|
| 127 |
+ ], |
|
| 128 |
+ "Entrypoint": "", |
|
| 129 |
+ "Image": "ubuntu", |
|
| 130 |
+ "Labels": {
|
|
| 131 |
+ "com.example.vendor": "Acme", |
|
| 132 |
+ "com.example.license": "GPL", |
|
| 133 |
+ "com.example.version": "1.0" |
|
| 134 |
+ }, |
|
| 135 |
+ "Volumes": {
|
|
| 136 |
+ "/tmp": {}
|
|
| 137 |
+ }, |
|
| 138 |
+ "WorkingDir": "", |
|
| 139 |
+ "NetworkDisabled": false, |
|
| 140 |
+ "MacAddress": "12:34:56:78:9a:bc", |
|
| 141 |
+ "ExposedPorts": {
|
|
| 142 |
+ "22/tcp": {}
|
|
| 143 |
+ }, |
|
| 144 |
+ "HostConfig": {
|
|
| 145 |
+ "Binds": ["/tmp:/tmp"], |
|
| 146 |
+ "Links": ["redis3:redis"], |
|
| 147 |
+ "LxcConf": {"lxc.utsname":"docker"},
|
|
| 148 |
+ "Memory": 0, |
|
| 149 |
+ "MemorySwap": 0, |
|
| 150 |
+ "CpuShares": 512, |
|
| 151 |
+ "CpuPeriod": 100000, |
|
| 152 |
+ "CpusetCpus": "0,1", |
|
| 153 |
+ "CpusetMems": "0,1", |
|
| 154 |
+ "BlkioWeight": 300, |
|
| 155 |
+ "OomKillDisable": false, |
|
| 156 |
+ "PortBindings": { "22/tcp": [{ "HostPort": "11022" }] },
|
|
| 157 |
+ "PublishAllPorts": false, |
|
| 158 |
+ "Privileged": false, |
|
| 159 |
+ "ReadonlyRootfs": false, |
|
| 160 |
+ "Dns": ["8.8.8.8"], |
|
| 161 |
+ "DnsSearch": [""], |
|
| 162 |
+ "ExtraHosts": null, |
|
| 163 |
+ "VolumesFrom": ["parent", "other:ro"], |
|
| 164 |
+ "CapAdd": ["NET_ADMIN"], |
|
| 165 |
+ "CapDrop": ["MKNOD"], |
|
| 166 |
+ "RestartPolicy": { "Name": "", "MaximumRetryCount": 0 },
|
|
| 167 |
+ "NetworkMode": "bridge", |
|
| 168 |
+ "Devices": [], |
|
| 169 |
+ "Ulimits": [{}],
|
|
| 170 |
+ "LogConfig": { "Type": "json-file", "Config": {} },
|
|
| 171 |
+ "SecurityOpt": [""], |
|
| 172 |
+ "CgroupParent": "" |
|
| 173 |
+ } |
|
| 174 |
+ } |
|
| 175 |
+ |
|
| 176 |
+**Example response**: |
|
| 177 |
+ |
|
| 178 |
+ HTTP/1.1 201 Created |
|
| 179 |
+ Content-Type: application/json |
|
| 180 |
+ |
|
| 181 |
+ {
|
|
| 182 |
+ "Id":"e90e34656806" |
|
| 183 |
+ "Warnings":[] |
|
| 184 |
+ } |
|
| 185 |
+ |
|
| 186 |
+Json Parameters: |
|
| 187 |
+ |
|
| 188 |
+- **Hostname** - A string value containing the hostname to use for the |
|
| 189 |
+ container. |
|
| 190 |
+- **Domainname** - A string value containing the domain name to use |
|
| 191 |
+ for the container. |
|
| 192 |
+- **User** - A string value specifying the user inside the container. |
|
| 193 |
+- **Memory** - Memory limit in bytes. |
|
| 194 |
+- **MemorySwap**- Total memory limit (memory + swap); set `-1` to disable swap |
|
| 195 |
+ You must use this with `memory` and make the swap value larger than `memory`. |
|
| 196 |
+- **CpuShares** - An integer value containing the container's CPU Shares |
|
| 197 |
+ (ie. the relative weight vs other containers). |
|
| 198 |
+- **CpuPeriod** - The length of a CPU period in microseconds. |
|
| 199 |
+- **Cpuset** - Deprecated please don't use. Use `CpusetCpus` instead. |
|
| 200 |
+- **CpusetCpus** - String value containing the `cgroups CpusetCpus` to use. |
|
| 201 |
+- **CpusetMems** - Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems. |
|
| 202 |
+- **BlkioWeight** - Block IO weight (relative weight) accepts a weight value between 10 and 1000. |
|
| 203 |
+- **OomKillDisable** - Boolean value, whether to disable OOM Killer for the container or not. |
|
| 204 |
+- **AttachStdin** - Boolean value, attaches to `stdin`. |
|
| 205 |
+- **AttachStdout** - Boolean value, attaches to `stdout`. |
|
| 206 |
+- **AttachStderr** - Boolean value, attaches to `stderr`. |
|
| 207 |
+- **Tty** - Boolean value, Attach standard streams to a `tty`, including `stdin` if it is not closed. |
|
| 208 |
+- **OpenStdin** - Boolean value, opens stdin, |
|
| 209 |
+- **StdinOnce** - Boolean value, close `stdin` after the 1 attached client disconnects. |
|
| 210 |
+- **Env** - A list of environment variables in the form of `VAR=value` |
|
| 211 |
+- **Labels** - Adds a map of labels to a container. To specify a map: `{"key":"value"[,"key2":"value2"]}`
|
|
| 212 |
+- **Cmd** - Command to run specified as a string or an array of strings. |
|
| 213 |
+- **Entrypoint** - Set the entry point for the container as a string or an array |
|
| 214 |
+ of strings. |
|
| 215 |
+- **Image** - A string specifying the image name to use for the container. |
|
| 216 |
+- **Volumes** – An object mapping mount point paths (strings) inside the |
|
| 217 |
+ container to empty objects. |
|
| 218 |
+- **WorkingDir** - A string specifying the working directory for commands to |
|
| 219 |
+ run in. |
|
| 220 |
+- **NetworkDisabled** - Boolean value, when true disables networking for the |
|
| 221 |
+ container |
|
| 222 |
+- **ExposedPorts** - An object mapping ports to an empty object in the form of: |
|
| 223 |
+ `"ExposedPorts": { "<port>/<tcp|udp>: {}" }`
|
|
| 224 |
+- **HostConfig** |
|
| 225 |
+ - **Binds** – A list of volume bindings for this container. Each volume binding is a string in one of these forms: |
|
| 226 |
+ + `container_path` to create a new volume for the container |
|
| 227 |
+ + `host_path:container_path` to bind-mount a host path into the container |
|
| 228 |
+ + `host_path:container_path:ro` to make the bind-mount read-only inside the container. |
|
| 229 |
+ - **Links** - A list of links for the container. Each link entry should be |
|
| 230 |
+ in the form of `container_name:alias`. |
|
| 231 |
+ - **LxcConf** - LXC specific configurations. These configurations only |
|
| 232 |
+ work when using the `lxc` execution driver. |
|
| 233 |
+ - **PortBindings** - A map of exposed container ports and the host port they |
|
| 234 |
+ should map to. A JSON object in the form |
|
| 235 |
+ `{ <port>/<protocol>: [{ "HostPort": "<port>" }] }`
|
|
| 236 |
+ Take note that `port` is specified as a string and not an integer value. |
|
| 237 |
+ - **PublishAllPorts** - Allocates a random host port for all of a container's |
|
| 238 |
+ exposed ports. Specified as a boolean value. |
|
| 239 |
+ - **Privileged** - Gives the container full access to the host. Specified as |
|
| 240 |
+ a boolean value. |
|
| 241 |
+ - **ReadonlyRootfs** - Mount the container's root filesystem as read only. |
|
| 242 |
+ Specified as a boolean value. |
|
| 243 |
+ - **Dns** - A list of DNS servers for the container to use. |
|
| 244 |
+ - **DnsSearch** - A list of DNS search domains |
|
| 245 |
+ - **ExtraHosts** - A list of hostnames/IP mappings to add to the |
|
| 246 |
+ container's `/etc/hosts` file. Specified in the form `["hostname:IP"]`. |
|
| 247 |
+ - **VolumesFrom** - A list of volumes to inherit from another container. |
|
| 248 |
+ Specified in the form `<container name>[:<ro|rw>]` |
|
| 249 |
+ - **CapAdd** - A list of kernel capabilities to add to the container. |
|
| 250 |
+ - **Capdrop** - A list of kernel capabilities to drop from the container. |
|
| 251 |
+ - **RestartPolicy** – The behavior to apply when the container exits. The |
|
| 252 |
+ value is an object with a `Name` property of either `"always"` to |
|
| 253 |
+ always restart or `"on-failure"` to restart only when the container |
|
| 254 |
+ exit code is non-zero. If `on-failure` is used, `MaximumRetryCount` |
|
| 255 |
+ controls the number of times to retry before giving up. |
|
| 256 |
+ The default is not to restart. (optional) |
|
| 257 |
+ An ever increasing delay (double the previous delay, starting at 100mS) |
|
| 258 |
+ is added before each restart to prevent flooding the server. |
|
| 259 |
+ - **NetworkMode** - Sets the networking mode for the container. Supported |
|
| 260 |
+ values are: `bridge`, `host`, and `container:<name|id>` |
|
| 261 |
+ - **Devices** - A list of devices to add to the container specified as a JSON object in the |
|
| 262 |
+ form |
|
| 263 |
+ `{ "PathOnHost": "/dev/deviceName", "PathInContainer": "/dev/deviceName", "CgroupPermissions": "mrw"}`
|
|
| 264 |
+ - **Ulimits** - A list of ulimits to set in the container, specified as |
|
| 265 |
+ `{ "Name": <name>, "Soft": <soft limit>, "Hard": <hard limit> }`, for example:
|
|
| 266 |
+ `Ulimits: { "Name": "nofile", "Soft": 1024, "Hard", 2048 }}`
|
|
| 267 |
+ - **SecurityOpt**: A list of string values to customize labels for MLS |
|
| 268 |
+ systems, such as SELinux. |
|
| 269 |
+ - **LogConfig** - Log configuration for the container, specified as a JSON object in the form |
|
| 270 |
+ `{ "Type": "<driver_name>", "Config": {"key1": "val1"}}`.
|
|
| 271 |
+ Available types: `json-file`, `syslog`, `journald`, `none`. |
|
| 272 |
+ `json-file` logging driver. |
|
| 273 |
+ - **CgroupParent** - Path to `cgroups` under which the container's `cgroup` is created. If the path is not absolute, the path is considered to be relative to the `cgroups` path of the init process. Cgroups are created if they do not already exist. |
|
| 274 |
+ |
|
| 275 |
+Query Parameters: |
|
| 276 |
+ |
|
| 277 |
+- **name** – Assign the specified name to the container. Must |
|
| 278 |
+ match `/?[a-zA-Z0-9_-]+`. |
|
| 279 |
+ |
|
| 280 |
+Status Codes: |
|
| 281 |
+ |
|
| 282 |
+- **201** – no error |
|
| 283 |
+- **404** – no such container |
|
| 284 |
+- **406** – impossible to attach (container not running) |
|
| 285 |
+- **500** – server error |
|
| 286 |
+ |
|
| 287 |
+### Inspect a container |
|
| 288 |
+ |
|
| 289 |
+`GET /containers/(id)/json` |
|
| 290 |
+ |
|
| 291 |
+Return low-level information on the container `id` |
|
| 292 |
+ |
|
| 293 |
+ |
|
| 294 |
+**Example request**: |
|
| 295 |
+ |
|
| 296 |
+ GET /containers/4fa6e0f0c678/json HTTP/1.1 |
|
| 297 |
+ |
|
| 298 |
+**Example response**: |
|
| 299 |
+ |
|
| 300 |
+ HTTP/1.1 200 OK |
|
| 301 |
+ Content-Type: application/json |
|
| 302 |
+ |
|
| 303 |
+ {
|
|
| 304 |
+ "AppArmorProfile": "", |
|
| 305 |
+ "Args": [ |
|
| 306 |
+ "-c", |
|
| 307 |
+ "exit 9" |
|
| 308 |
+ ], |
|
| 309 |
+ "Config": {
|
|
| 310 |
+ "AttachStderr": true, |
|
| 311 |
+ "AttachStdin": false, |
|
| 312 |
+ "AttachStdout": true, |
|
| 313 |
+ "Cmd": [ |
|
| 314 |
+ "/bin/sh", |
|
| 315 |
+ "-c", |
|
| 316 |
+ "exit 9" |
|
| 317 |
+ ], |
|
| 318 |
+ "Domainname": "", |
|
| 319 |
+ "Entrypoint": null, |
|
| 320 |
+ "Env": [ |
|
| 321 |
+ "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" |
|
| 322 |
+ ], |
|
| 323 |
+ "ExposedPorts": null, |
|
| 324 |
+ "Hostname": "ba033ac44011", |
|
| 325 |
+ "Image": "ubuntu", |
|
| 326 |
+ "Labels": {
|
|
| 327 |
+ "com.example.vendor": "Acme", |
|
| 328 |
+ "com.example.license": "GPL", |
|
| 329 |
+ "com.example.version": "1.0" |
|
| 330 |
+ }, |
|
| 331 |
+ "MacAddress": "", |
|
| 332 |
+ "NetworkDisabled": false, |
|
| 333 |
+ "OnBuild": null, |
|
| 334 |
+ "OpenStdin": false, |
|
| 335 |
+ "PortSpecs": null, |
|
| 336 |
+ "StdinOnce": false, |
|
| 337 |
+ "Tty": false, |
|
| 338 |
+ "User": "", |
|
| 339 |
+ "Volumes": null, |
|
| 340 |
+ "WorkingDir": "" |
|
| 341 |
+ }, |
|
| 342 |
+ "Created": "2015-01-06T15:47:31.485331387Z", |
|
| 343 |
+ "Driver": "devicemapper", |
|
| 344 |
+ "ExecDriver": "native-0.2", |
|
| 345 |
+ "ExecIDs": null, |
|
| 346 |
+ "HostConfig": {
|
|
| 347 |
+ "Binds": null, |
|
| 348 |
+ "BlkioWeight": 0, |
|
| 349 |
+ "CapAdd": null, |
|
| 350 |
+ "CapDrop": null, |
|
| 351 |
+ "ContainerIDFile": "", |
|
| 352 |
+ "CpusetCpus": "", |
|
| 353 |
+ "CpusetMems": "", |
|
| 354 |
+ "CpuShares": 0, |
|
| 355 |
+ "CpuPeriod": 100000, |
|
| 356 |
+ "Devices": [], |
|
| 357 |
+ "Dns": null, |
|
| 358 |
+ "DnsSearch": null, |
|
| 359 |
+ "ExtraHosts": null, |
|
| 360 |
+ "IpcMode": "", |
|
| 361 |
+ "Links": null, |
|
| 362 |
+ "LxcConf": [], |
|
| 363 |
+ "Memory": 0, |
|
| 364 |
+ "MemorySwap": 0, |
|
| 365 |
+ "OomKillDisable": false, |
|
| 366 |
+ "NetworkMode": "bridge", |
|
| 367 |
+ "PortBindings": {},
|
|
| 368 |
+ "Privileged": false, |
|
| 369 |
+ "ReadonlyRootfs": false, |
|
| 370 |
+ "PublishAllPorts": false, |
|
| 371 |
+ "RestartPolicy": {
|
|
| 372 |
+ "MaximumRetryCount": 2, |
|
| 373 |
+ "Name": "on-failure" |
|
| 374 |
+ }, |
|
| 375 |
+ "LogConfig": {
|
|
| 376 |
+ "Config": null, |
|
| 377 |
+ "Type": "json-file" |
|
| 378 |
+ }, |
|
| 379 |
+ "SecurityOpt": null, |
|
| 380 |
+ "VolumesFrom": null, |
|
| 381 |
+ "Ulimits": [{}]
|
|
| 382 |
+ }, |
|
| 383 |
+ "HostnamePath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hostname", |
|
| 384 |
+ "HostsPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hosts", |
|
| 385 |
+ "LogPath": "/var/lib/docker/containers/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b-json.log", |
|
| 386 |
+ "Id": "ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39", |
|
| 387 |
+ "Image": "04c5d3b7b0656168630d3ba35d8889bd0e9caafcaeb3004d2bfbc47e7c5d35d2", |
|
| 388 |
+ "MountLabel": "", |
|
| 389 |
+ "Name": "/boring_euclid", |
|
| 390 |
+ "NetworkSettings": {
|
|
| 391 |
+ "Bridge": "", |
|
| 392 |
+ "Gateway": "", |
|
| 393 |
+ "IPAddress": "", |
|
| 394 |
+ "IPPrefixLen": 0, |
|
| 395 |
+ "MacAddress": "", |
|
| 396 |
+ "PortMapping": null, |
|
| 397 |
+ "Ports": null |
|
| 398 |
+ }, |
|
| 399 |
+ "Path": "/bin/sh", |
|
| 400 |
+ "ProcessLabel": "", |
|
| 401 |
+ "ResolvConfPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/resolv.conf", |
|
| 402 |
+ "RestartCount": 1, |
|
| 403 |
+ "State": {
|
|
| 404 |
+ "Error": "", |
|
| 405 |
+ "ExitCode": 9, |
|
| 406 |
+ "FinishedAt": "2015-01-06T15:47:32.080254511Z", |
|
| 407 |
+ "OOMKilled": false, |
|
| 408 |
+ "Paused": false, |
|
| 409 |
+ "Pid": 0, |
|
| 410 |
+ "Restarting": false, |
|
| 411 |
+ "Running": false, |
|
| 412 |
+ "StartedAt": "2015-01-06T15:47:32.072697474Z" |
|
| 413 |
+ }, |
|
| 414 |
+ "Volumes": {},
|
|
| 415 |
+ "VolumesRW": {}
|
|
| 416 |
+ } |
|
| 417 |
+ |
|
| 418 |
+Status Codes: |
|
| 419 |
+ |
|
| 420 |
+- **200** – no error |
|
| 421 |
+- **404** – no such container |
|
| 422 |
+- **500** – server error |
|
| 423 |
+ |
|
| 424 |
+### List processes running inside a container |
|
| 425 |
+ |
|
| 426 |
+`GET /containers/(id)/top` |
|
| 427 |
+ |
|
| 428 |
+List processes running inside the container `id` |
|
| 429 |
+ |
|
| 430 |
+**Example request**: |
|
| 431 |
+ |
|
| 432 |
+ GET /containers/4fa6e0f0c678/top HTTP/1.1 |
|
| 433 |
+ |
|
| 434 |
+**Example response**: |
|
| 435 |
+ |
|
| 436 |
+ HTTP/1.1 200 OK |
|
| 437 |
+ Content-Type: application/json |
|
| 438 |
+ |
|
| 439 |
+ {
|
|
| 440 |
+ "Titles": [ |
|
| 441 |
+ "USER", |
|
| 442 |
+ "PID", |
|
| 443 |
+ "%CPU", |
|
| 444 |
+ "%MEM", |
|
| 445 |
+ "VSZ", |
|
| 446 |
+ "RSS", |
|
| 447 |
+ "TTY", |
|
| 448 |
+ "STAT", |
|
| 449 |
+ "START", |
|
| 450 |
+ "TIME", |
|
| 451 |
+ "COMMAND" |
|
| 452 |
+ ], |
|
| 453 |
+ "Processes": [ |
|
| 454 |
+ ["root","20147","0.0","0.1","18060","1864","pts/4","S","10:06","0:00","bash"], |
|
| 455 |
+ ["root","20271","0.0","0.0","4312","352","pts/4","S+","10:07","0:00","sleep","10"] |
|
| 456 |
+ ] |
|
| 457 |
+ } |
|
| 458 |
+ |
|
| 459 |
+Query Parameters: |
|
| 460 |
+ |
|
| 461 |
+- **ps_args** – ps arguments to use (e.g., aux) |
|
| 462 |
+ |
|
| 463 |
+Status Codes: |
|
| 464 |
+ |
|
| 465 |
+- **200** – no error |
|
| 466 |
+- **404** – no such container |
|
| 467 |
+- **500** – server error |
|
| 468 |
+ |
|
| 469 |
+### Get container logs |
|
| 470 |
+ |
|
| 471 |
+`GET /containers/(id)/logs` |
|
| 472 |
+ |
|
| 473 |
+Get `stdout` and `stderr` logs from the container ``id`` |
|
| 474 |
+ |
|
| 475 |
+> **Note**: |
|
| 476 |
+> This endpoint works only for containers with `json-file` logging driver. |
|
| 477 |
+ |
|
| 478 |
+**Example request**: |
|
| 479 |
+ |
|
| 480 |
+ GET /containers/4fa6e0f0c678/logs?stderr=1&stdout=1×tamps=1&follow=1&tail=10&since=1428990821 HTTP/1.1 |
|
| 481 |
+ |
|
| 482 |
+**Example response**: |
|
| 483 |
+ |
|
| 484 |
+ HTTP/1.1 101 UPGRADED |
|
| 485 |
+ Content-Type: application/vnd.docker.raw-stream |
|
| 486 |
+ Connection: Upgrade |
|
| 487 |
+ Upgrade: tcp |
|
| 488 |
+ |
|
| 489 |
+ {{ STREAM }}
|
|
| 490 |
+ |
|
| 491 |
+Query Parameters: |
|
| 492 |
+ |
|
| 493 |
+- **follow** – 1/True/true or 0/False/false, return stream. Default `false`. |
|
| 494 |
+- **stdout** – 1/True/true or 0/False/false, show `stdout` log. Default `false`. |
|
| 495 |
+- **stderr** – 1/True/true or 0/False/false, show `stderr` log. Default `false`. |
|
| 496 |
+- **since** – UNIX timestamp (integer) to filter logs. Specifying a timestamp |
|
| 497 |
+ will only output log-entries since that timestamp. Default: 0 (unfiltered) |
|
| 498 |
+- **timestamps** – 1/True/true or 0/False/false, print timestamps for |
|
| 499 |
+ every log line. Default `false`. |
|
| 500 |
+- **tail** – Output specified number of lines at the end of logs: `all` or `<number>`. Default all. |
|
| 501 |
+ |
|
| 502 |
+Status Codes: |
|
| 503 |
+ |
|
| 504 |
+- **101** – no error, hints proxy about hijacking |
|
| 505 |
+- **200** – no error, no upgrade header found |
|
| 506 |
+- **404** – no such container |
|
| 507 |
+- **500** – server error |
|
| 508 |
+ |
|
| 509 |
+### Inspect changes on a container's filesystem |
|
| 510 |
+ |
|
| 511 |
+`GET /containers/(id)/changes` |
|
| 512 |
+ |
|
| 513 |
+Inspect changes on container `id`'s filesystem |
|
| 514 |
+ |
|
| 515 |
+**Example request**: |
|
| 516 |
+ |
|
| 517 |
+ GET /containers/4fa6e0f0c678/changes HTTP/1.1 |
|
| 518 |
+ |
|
| 519 |
+**Example response**: |
|
| 520 |
+ |
|
| 521 |
+ HTTP/1.1 200 OK |
|
| 522 |
+ Content-Type: application/json |
|
| 523 |
+ |
|
| 524 |
+ [ |
|
| 525 |
+ {
|
|
| 526 |
+ "Path": "/dev", |
|
| 527 |
+ "Kind": 0 |
|
| 528 |
+ }, |
|
| 529 |
+ {
|
|
| 530 |
+ "Path": "/dev/kmsg", |
|
| 531 |
+ "Kind": 1 |
|
| 532 |
+ }, |
|
| 533 |
+ {
|
|
| 534 |
+ "Path": "/test", |
|
| 535 |
+ "Kind": 1 |
|
| 536 |
+ } |
|
| 537 |
+ ] |
|
| 538 |
+ |
|
| 539 |
+Values for `Kind`: |
|
| 540 |
+ |
|
| 541 |
+- `0`: Modify |
|
| 542 |
+- `1`: Add |
|
| 543 |
+- `2`: Delete |
|
| 544 |
+ |
|
| 545 |
+Status Codes: |
|
| 546 |
+ |
|
| 547 |
+- **200** – no error |
|
| 548 |
+- **404** – no such container |
|
| 549 |
+- **500** – server error |
|
| 550 |
+ |
|
| 551 |
+### Export a container |
|
| 552 |
+ |
|
| 553 |
+`GET /containers/(id)/export` |
|
| 554 |
+ |
|
| 555 |
+Export the contents of container `id` |
|
| 556 |
+ |
|
| 557 |
+**Example request**: |
|
| 558 |
+ |
|
| 559 |
+ GET /containers/4fa6e0f0c678/export HTTP/1.1 |
|
| 560 |
+ |
|
| 561 |
+**Example response**: |
|
| 562 |
+ |
|
| 563 |
+ HTTP/1.1 200 OK |
|
| 564 |
+ Content-Type: application/octet-stream |
|
| 565 |
+ |
|
| 566 |
+ {{ TAR STREAM }}
|
|
| 567 |
+ |
|
| 568 |
+Status Codes: |
|
| 569 |
+ |
|
| 570 |
+- **200** – no error |
|
| 571 |
+- **404** – no such container |
|
| 572 |
+- **500** – server error |
|
| 573 |
+ |
|
| 574 |
+### Get container stats based on resource usage |
|
| 575 |
+ |
|
| 576 |
+`GET /containers/(id)/stats` |
|
| 577 |
+ |
|
| 578 |
+This endpoint returns a live stream of a container's resource usage statistics. |
|
| 579 |
+ |
|
| 580 |
+> **Note**: this functionality currently only works when using the *libcontainer* exec-driver. |
|
| 581 |
+ |
|
| 582 |
+**Example request**: |
|
| 583 |
+ |
|
| 584 |
+ GET /containers/redis1/stats HTTP/1.1 |
|
| 585 |
+ |
|
| 586 |
+**Example response**: |
|
| 587 |
+ |
|
| 588 |
+ HTTP/1.1 200 OK |
|
| 589 |
+ Content-Type: application/json |
|
| 590 |
+ |
|
| 591 |
+ {
|
|
| 592 |
+ "read" : "2015-01-08T22:57:31.547920715Z", |
|
| 593 |
+ "network" : {
|
|
| 594 |
+ "rx_dropped" : 0, |
|
| 595 |
+ "rx_bytes" : 648, |
|
| 596 |
+ "rx_errors" : 0, |
|
| 597 |
+ "tx_packets" : 8, |
|
| 598 |
+ "tx_dropped" : 0, |
|
| 599 |
+ "rx_packets" : 8, |
|
| 600 |
+ "tx_errors" : 0, |
|
| 601 |
+ "tx_bytes" : 648 |
|
| 602 |
+ }, |
|
| 603 |
+ "memory_stats" : {
|
|
| 604 |
+ "stats" : {
|
|
| 605 |
+ "total_pgmajfault" : 0, |
|
| 606 |
+ "cache" : 0, |
|
| 607 |
+ "mapped_file" : 0, |
|
| 608 |
+ "total_inactive_file" : 0, |
|
| 609 |
+ "pgpgout" : 414, |
|
| 610 |
+ "rss" : 6537216, |
|
| 611 |
+ "total_mapped_file" : 0, |
|
| 612 |
+ "writeback" : 0, |
|
| 613 |
+ "unevictable" : 0, |
|
| 614 |
+ "pgpgin" : 477, |
|
| 615 |
+ "total_unevictable" : 0, |
|
| 616 |
+ "pgmajfault" : 0, |
|
| 617 |
+ "total_rss" : 6537216, |
|
| 618 |
+ "total_rss_huge" : 6291456, |
|
| 619 |
+ "total_writeback" : 0, |
|
| 620 |
+ "total_inactive_anon" : 0, |
|
| 621 |
+ "rss_huge" : 6291456, |
|
| 622 |
+ "hierarchical_memory_limit" : 67108864, |
|
| 623 |
+ "total_pgfault" : 964, |
|
| 624 |
+ "total_active_file" : 0, |
|
| 625 |
+ "active_anon" : 6537216, |
|
| 626 |
+ "total_active_anon" : 6537216, |
|
| 627 |
+ "total_pgpgout" : 414, |
|
| 628 |
+ "total_cache" : 0, |
|
| 629 |
+ "inactive_anon" : 0, |
|
| 630 |
+ "active_file" : 0, |
|
| 631 |
+ "pgfault" : 964, |
|
| 632 |
+ "inactive_file" : 0, |
|
| 633 |
+ "total_pgpgin" : 477 |
|
| 634 |
+ }, |
|
| 635 |
+ "max_usage" : 6651904, |
|
| 636 |
+ "usage" : 6537216, |
|
| 637 |
+ "failcnt" : 0, |
|
| 638 |
+ "limit" : 67108864 |
|
| 639 |
+ }, |
|
| 640 |
+ "blkio_stats" : {},
|
|
| 641 |
+ "cpu_stats" : {
|
|
| 642 |
+ "cpu_usage" : {
|
|
| 643 |
+ "percpu_usage" : [ |
|
| 644 |
+ 16970827, |
|
| 645 |
+ 1839451, |
|
| 646 |
+ 7107380, |
|
| 647 |
+ 10571290 |
|
| 648 |
+ ], |
|
| 649 |
+ "usage_in_usermode" : 10000000, |
|
| 650 |
+ "total_usage" : 36488948, |
|
| 651 |
+ "usage_in_kernelmode" : 20000000 |
|
| 652 |
+ }, |
|
| 653 |
+ "system_cpu_usage" : 20091722000000000, |
|
| 654 |
+ "throttling_data" : {}
|
|
| 655 |
+ } |
|
| 656 |
+ } |
|
| 657 |
+ |
|
| 658 |
+Query Parameters: |
|
| 659 |
+ |
|
| 660 |
+- **stream** – 1/True/true or 0/False/false, pull stats once then disconnect. Default `true`. |
|
| 661 |
+ |
|
| 662 |
+Status Codes: |
|
| 663 |
+ |
|
| 664 |
+- **200** – no error |
|
| 665 |
+- **404** – no such container |
|
| 666 |
+- **500** – server error |
|
| 667 |
+ |
|
| 668 |
+### Resize a container TTY |
|
| 669 |
+ |
|
| 670 |
+`POST /containers/(id)/resize?h=<height>&w=<width>` |
|
| 671 |
+ |
|
| 672 |
+Resize the TTY for container with `id`. You must restart the container for the resize to take effect. |
|
| 673 |
+ |
|
| 674 |
+**Example request**: |
|
| 675 |
+ |
|
| 676 |
+ POST /containers/4fa6e0f0c678/resize?h=40&w=80 HTTP/1.1 |
|
| 677 |
+ |
|
| 678 |
+**Example response**: |
|
| 679 |
+ |
|
| 680 |
+ HTTP/1.1 200 OK |
|
| 681 |
+ Content-Length: 0 |
|
| 682 |
+ Content-Type: text/plain; charset=utf-8 |
|
| 683 |
+ |
|
| 684 |
+Status Codes: |
|
| 685 |
+ |
|
| 686 |
+- **200** – no error |
|
| 687 |
+- **404** – No such container |
|
| 688 |
+- **500** – Cannot resize container |
|
| 689 |
+ |
|
| 690 |
+### Start a container |
|
| 691 |
+ |
|
| 692 |
+`POST /containers/(id)/start` |
|
| 693 |
+ |
|
| 694 |
+Start the container `id` |
|
| 695 |
+ |
|
| 696 |
+**Example request**: |
|
| 697 |
+ |
|
| 698 |
+ POST /containers/(id)/start HTTP/1.1 |
|
| 699 |
+ Content-Type: application/json |
|
| 700 |
+ |
|
| 701 |
+ {
|
|
| 702 |
+ "Binds": ["/tmp:/tmp"], |
|
| 703 |
+ "Links": ["redis3:redis"], |
|
| 704 |
+ "LxcConf": {"lxc.utsname":"docker"},
|
|
| 705 |
+ "Memory": 0, |
|
| 706 |
+ "MemorySwap": 0, |
|
| 707 |
+ "CpuShares": 512, |
|
| 708 |
+ "CpusetCpus": "0,1", |
|
| 709 |
+ "PortBindings": { "22/tcp": [{ "HostPort": "11022" }] },
|
|
| 710 |
+ "PublishAllPorts": false, |
|
| 711 |
+ "Privileged": false, |
|
| 712 |
+ "ReadonlyRootfs": false, |
|
| 713 |
+ "Dns": ["8.8.8.8"], |
|
| 714 |
+ "DnsSearch": [""], |
|
| 715 |
+ "ExtraHosts": null, |
|
| 716 |
+ "VolumesFrom": ["parent", "other:ro"], |
|
| 717 |
+ "CapAdd": ["NET_ADMIN"], |
|
| 718 |
+ "CapDrop": ["MKNOD"], |
|
| 719 |
+ "RestartPolicy": { "Name": "", "MaximumRetryCount": 0 },
|
|
| 720 |
+ "NetworkMode": "bridge", |
|
| 721 |
+ "Devices": [], |
|
| 722 |
+ "Ulimits": [{}],
|
|
| 723 |
+ "LogConfig": { "Type": "json-file", "Config": {} },
|
|
| 724 |
+ "SecurityOpt": [""], |
|
| 725 |
+ "CgroupParent": "" |
|
| 726 |
+ } |
|
| 727 |
+ |
|
| 728 |
+**Example response**: |
|
| 729 |
+ |
|
| 730 |
+ HTTP/1.1 204 No Content |
|
| 731 |
+ |
|
| 732 |
+Json Parameters: |
|
| 733 |
+ |
|
| 734 |
+- **Binds** – A list of volume bindings for this container. Each volume binding is a string in one of these forms: |
|
| 735 |
+ + `container_path` to create a new volume for the container |
|
| 736 |
+ + `host_path:container_path` to bind-mount a host path into the container |
|
| 737 |
+ + `host_path:container_path:ro` to make the bind-mount read-only inside the container. |
|
| 738 |
+- **Links** - A list of links for the container. Each link entry should be of |
|
| 739 |
+ of the form `container_name:alias`. |
|
| 740 |
+- **LxcConf** - LXC specific configurations. These configurations only |
|
| 741 |
+ work when using the `lxc` execution driver. |
|
| 742 |
+- **PortBindings** - A map of exposed container ports and the host port they |
|
| 743 |
+ should map to. A JSON object in the form |
|
| 744 |
+ `{ <port>/<protocol>: [{ "HostPort": "<port>" }] }`
|
|
| 745 |
+ Take note that `port` is specified as a string and not an integer value. |
|
| 746 |
+- **PublishAllPorts** - Allocates a random host port for all of a container's |
|
| 747 |
+ exposed ports. Specified as a boolean value. |
|
| 748 |
+- **Privileged** - Gives the container full access to the host. Specified as |
|
| 749 |
+ a boolean value. |
|
| 750 |
+- **ReadonlyRootfs** - Mount the container's root filesystem as read only. |
|
| 751 |
+ Specified as a boolean value. |
|
| 752 |
+- **Dns** - A list of dns servers for the container to use. |
|
| 753 |
+- **DnsSearch** - A list of DNS search domains. |
|
| 754 |
+- **ExtraHosts** - A list of hostnames/IP mappings to add to the |
|
| 755 |
+ container's `/etc/hosts` file. Specified in the form `["hostname:IP"]`. |
|
| 756 |
+- **VolumesFrom** - A list of volumes to inherit from another container. |
|
| 757 |
+ Specified in the form `<container name>[:<ro|rw>]` |
|
| 758 |
+- **CapAdd** - A list of kernel capabilities to add to the container. |
|
| 759 |
+- **Capdrop** - A list of kernel capabilities to drop from the container. |
|
| 760 |
+- **RestartPolicy** – The behavior to apply when the container exits. The |
|
| 761 |
+ value is an object with a `Name` property of either `"always"` to |
|
| 762 |
+ always restart or `"on-failure"` to restart only when the container |
|
| 763 |
+ exit code is non-zero. If `on-failure` is used, `MaximumRetryCount` |
|
| 764 |
+ controls the number of times to retry before giving up. |
|
| 765 |
+ The default is not to restart. (optional) |
|
| 766 |
+ An ever increasing delay (double the previous delay, starting at 100mS) |
|
| 767 |
+ is added before each restart to prevent flooding the server. |
|
| 768 |
+- **NetworkMode** - Sets the networking mode for the container. Supported |
|
| 769 |
+ values are: `bridge`, `host`, and `container:<name|id>` |
|
| 770 |
+- **Devices** - A list of devices to add to the container specified as a JSON object in the |
|
| 771 |
+ form |
|
| 772 |
+ `{ "PathOnHost": "/dev/deviceName", "PathInContainer": "/dev/deviceName", "CgroupPermissions": "mrw"}`
|
|
| 773 |
+- **Ulimits** - A list of ulimits to set in the container, specified as |
|
| 774 |
+ `{ "Name": <name>, "Soft": <soft limit>, "Hard": <hard limit> }`, for example:
|
|
| 775 |
+ `Ulimits: { "Name": "nofile", "Soft": 1024, "Hard", 2048 }}`
|
|
| 776 |
+- **SecurityOpt**: A list of string values to customize labels for MLS |
|
| 777 |
+ systems, such as SELinux. |
|
| 778 |
+- **LogConfig** - Log configuration for the container, specified as |
|
| 779 |
+ `{ "Type": "<driver_name>", "Config": {"key1": "val1"}}`.
|
|
| 780 |
+ Available types: `json-file`, `syslog`, `journald`, `none`. |
|
| 781 |
+ `json-file` logging driver. |
|
| 782 |
+ - **CgroupParent** - Path to `cgroups` under which the container's `cgroup` is created. If the path is not absolute, the path is considered to be relative to the `cgroups` path of the init process. Cgroups are created if they do not already exist. |
|
| 783 |
+ |
|
| 784 |
+Status Codes: |
|
| 785 |
+ |
|
| 786 |
+- **204** – no error |
|
| 787 |
+- **304** – container already started |
|
| 788 |
+- **404** – no such container |
|
| 789 |
+- **500** – server error |
|
| 790 |
+ |
|
| 791 |
+### Stop a container |
|
| 792 |
+ |
|
| 793 |
+`POST /containers/(id)/stop` |
|
| 794 |
+ |
|
| 795 |
+Stop the container `id` |
|
| 796 |
+ |
|
| 797 |
+**Example request**: |
|
| 798 |
+ |
|
| 799 |
+ POST /containers/e90e34656806/stop?t=5 HTTP/1.1 |
|
| 800 |
+ |
|
| 801 |
+**Example response**: |
|
| 802 |
+ |
|
| 803 |
+ HTTP/1.1 204 No Content |
|
| 804 |
+ |
|
| 805 |
+Query Parameters: |
|
| 806 |
+ |
|
| 807 |
+- **t** – number of seconds to wait before killing the container |
|
| 808 |
+ |
|
| 809 |
+Status Codes: |
|
| 810 |
+ |
|
| 811 |
+- **204** – no error |
|
| 812 |
+- **304** – container already stopped |
|
| 813 |
+- **404** – no such container |
|
| 814 |
+- **500** – server error |
|
| 815 |
+ |
|
| 816 |
+### Restart a container |
|
| 817 |
+ |
|
| 818 |
+`POST /containers/(id)/restart` |
|
| 819 |
+ |
|
| 820 |
+Restart the container `id` |
|
| 821 |
+ |
|
| 822 |
+**Example request**: |
|
| 823 |
+ |
|
| 824 |
+ POST /containers/e90e34656806/restart?t=5 HTTP/1.1 |
|
| 825 |
+ |
|
| 826 |
+**Example response**: |
|
| 827 |
+ |
|
| 828 |
+ HTTP/1.1 204 No Content |
|
| 829 |
+ |
|
| 830 |
+Query Parameters: |
|
| 831 |
+ |
|
| 832 |
+- **t** – number of seconds to wait before killing the container |
|
| 833 |
+ |
|
| 834 |
+Status Codes: |
|
| 835 |
+ |
|
| 836 |
+- **204** – no error |
|
| 837 |
+- **404** – no such container |
|
| 838 |
+- **500** – server error |
|
| 839 |
+ |
|
| 840 |
+### Kill a container |
|
| 841 |
+ |
|
| 842 |
+`POST /containers/(id)/kill` |
|
| 843 |
+ |
|
| 844 |
+Kill the container `id` |
|
| 845 |
+ |
|
| 846 |
+**Example request**: |
|
| 847 |
+ |
|
| 848 |
+ POST /containers/e90e34656806/kill HTTP/1.1 |
|
| 849 |
+ |
|
| 850 |
+**Example response**: |
|
| 851 |
+ |
|
| 852 |
+ HTTP/1.1 204 No Content |
|
| 853 |
+ |
|
| 854 |
+Query Parameters |
|
| 855 |
+ |
|
| 856 |
+- **signal** - Signal to send to the container: integer or string like `SIGINT`. |
|
| 857 |
+ When not set, `SIGKILL` is assumed and the call waits for the container to exit. |
|
| 858 |
+ |
|
| 859 |
+Status Codes: |
|
| 860 |
+ |
|
| 861 |
+- **204** – no error |
|
| 862 |
+- **404** – no such container |
|
| 863 |
+- **500** – server error |
|
| 864 |
+ |
|
| 865 |
+### Rename a container |
|
| 866 |
+ |
|
| 867 |
+`POST /containers/(id)/rename` |
|
| 868 |
+ |
|
| 869 |
+Rename the container `id` to a `new_name` |
|
| 870 |
+ |
|
| 871 |
+**Example request**: |
|
| 872 |
+ |
|
| 873 |
+ POST /containers/e90e34656806/rename?name=new_name HTTP/1.1 |
|
| 874 |
+ |
|
| 875 |
+**Example response**: |
|
| 876 |
+ |
|
| 877 |
+ HTTP/1.1 204 No Content |
|
| 878 |
+ |
|
| 879 |
+Query Parameters: |
|
| 880 |
+ |
|
| 881 |
+- **name** – new name for the container |
|
| 882 |
+ |
|
| 883 |
+Status Codes: |
|
| 884 |
+ |
|
| 885 |
+- **204** – no error |
|
| 886 |
+- **404** – no such container |
|
| 887 |
+- **409** - conflict name already assigned |
|
| 888 |
+- **500** – server error |
|
| 889 |
+ |
|
| 890 |
+### Pause a container |
|
| 891 |
+ |
|
| 892 |
+`POST /containers/(id)/pause` |
|
| 893 |
+ |
|
| 894 |
+Pause the container `id` |
|
| 895 |
+ |
|
| 896 |
+**Example request**: |
|
| 897 |
+ |
|
| 898 |
+ POST /containers/e90e34656806/pause HTTP/1.1 |
|
| 899 |
+ |
|
| 900 |
+**Example response**: |
|
| 901 |
+ |
|
| 902 |
+ HTTP/1.1 204 No Content |
|
| 903 |
+ |
|
| 904 |
+Status Codes: |
|
| 905 |
+ |
|
| 906 |
+- **204** – no error |
|
| 907 |
+- **404** – no such container |
|
| 908 |
+- **500** – server error |
|
| 909 |
+ |
|
| 910 |
+### Unpause a container |
|
| 911 |
+ |
|
| 912 |
+`POST /containers/(id)/unpause` |
|
| 913 |
+ |
|
| 914 |
+Unpause the container `id` |
|
| 915 |
+ |
|
| 916 |
+**Example request**: |
|
| 917 |
+ |
|
| 918 |
+ POST /containers/e90e34656806/unpause HTTP/1.1 |
|
| 919 |
+ |
|
| 920 |
+**Example response**: |
|
| 921 |
+ |
|
| 922 |
+ HTTP/1.1 204 No Content |
|
| 923 |
+ |
|
| 924 |
+Status Codes: |
|
| 925 |
+ |
|
| 926 |
+- **204** – no error |
|
| 927 |
+- **404** – no such container |
|
| 928 |
+- **500** – server error |
|
| 929 |
+ |
|
| 930 |
+### Attach to a container |
|
| 931 |
+ |
|
| 932 |
+`POST /containers/(id)/attach` |
|
| 933 |
+ |
|
| 934 |
+Attach to the container `id` |
|
| 935 |
+ |
|
| 936 |
+**Example request**: |
|
| 937 |
+ |
|
| 938 |
+ POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1 |
|
| 939 |
+ |
|
| 940 |
+**Example response**: |
|
| 941 |
+ |
|
| 942 |
+ HTTP/1.1 101 UPGRADED |
|
| 943 |
+ Content-Type: application/vnd.docker.raw-stream |
|
| 944 |
+ Connection: Upgrade |
|
| 945 |
+ Upgrade: tcp |
|
| 946 |
+ |
|
| 947 |
+ {{ STREAM }}
|
|
| 948 |
+ |
|
| 949 |
+Query Parameters: |
|
| 950 |
+ |
|
| 951 |
+- **logs** – 1/True/true or 0/False/false, return logs. Default `false`. |
|
| 952 |
+- **stream** – 1/True/true or 0/False/false, return stream. |
|
| 953 |
+ Default `false`. |
|
| 954 |
+- **stdin** – 1/True/true or 0/False/false, if `stream=true`, attach |
|
| 955 |
+ to `stdin`. Default `false`. |
|
| 956 |
+- **stdout** – 1/True/true or 0/False/false, if `logs=true`, return |
|
| 957 |
+ `stdout` log, if `stream=true`, attach to `stdout`. Default `false`. |
|
| 958 |
+- **stderr** – 1/True/true or 0/False/false, if `logs=true`, return |
|
| 959 |
+ `stderr` log, if `stream=true`, attach to `stderr`. Default `false`. |
|
| 960 |
+ |
|
| 961 |
+Status Codes: |
|
| 962 |
+ |
|
| 963 |
+- **101** – no error, hints proxy about hijacking |
|
| 964 |
+- **200** – no error, no upgrade header found |
|
| 965 |
+- **400** – bad parameter |
|
| 966 |
+- **404** – no such container |
|
| 967 |
+- **500** – server error |
|
| 968 |
+ |
|
| 969 |
+ **Stream details**: |
|
| 970 |
+ |
|
| 971 |
+ When using the TTY setting is enabled in |
|
| 972 |
+ [`POST /containers/create` |
|
| 973 |
+ ](/reference/api/docker_remote_api_v1.9/#create-a-container "POST /containers/create"), |
|
| 974 |
+ the stream is the raw data from the process PTY and client's `stdin`. |
|
| 975 |
+ When the TTY is disabled, then the stream is multiplexed to separate |
|
| 976 |
+ `stdout` and `stderr`. |
|
| 977 |
+ |
|
| 978 |
+ The format is a **Header** and a **Payload** (frame). |
|
| 979 |
+ |
|
| 980 |
+ **HEADER** |
|
| 981 |
+ |
|
| 982 |
+ The header contains the information which the stream writes (`stdout` or |
|
| 983 |
+ `stderr`). It also contains the size of the associated frame encoded in the |
|
| 984 |
+ last four bytes (`uint32`). |
|
| 985 |
+ |
|
| 986 |
+ It is encoded on the first eight bytes like this: |
|
| 987 |
+ |
|
| 988 |
+ header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4}
|
|
| 989 |
+ |
|
| 990 |
+ `STREAM_TYPE` can be: |
|
| 991 |
+ |
|
| 992 |
+- 0: `stdin` (is written on `stdout`) |
|
| 993 |
+- 1: `stdout` |
|
| 994 |
+- 2: `stderr` |
|
| 995 |
+ |
|
| 996 |
+ `SIZE1, SIZE2, SIZE3, SIZE4` are the four bytes of |
|
| 997 |
+ the `uint32` size encoded as big endian. |
|
| 998 |
+ |
|
| 999 |
+ **PAYLOAD** |
|
| 1000 |
+ |
|
| 1001 |
+ The payload is the raw stream. |
|
| 1002 |
+ |
|
| 1003 |
+ **IMPLEMENTATION** |
|
| 1004 |
+ |
|
| 1005 |
+ The simplest way to implement the Attach protocol is the following: |
|
| 1006 |
+ |
|
| 1007 |
+ 1. Read eight bytes. |
|
| 1008 |
+ 2. Choose `stdout` or `stderr` depending on the first byte. |
|
| 1009 |
+ 3. Extract the frame size from the last four bytes. |
|
| 1010 |
+ 4. Read the extracted size and output it on the correct output. |
|
| 1011 |
+ 5. Goto 1. |
|
| 1012 |
+ |
|
| 1013 |
+### Attach to a container (websocket) |
|
| 1014 |
+ |
|
| 1015 |
+`GET /containers/(id)/attach/ws` |
|
| 1016 |
+ |
|
| 1017 |
+Attach to the container `id` via websocket |
|
| 1018 |
+ |
|
| 1019 |
+Implements websocket protocol handshake according to [RFC 6455](http://tools.ietf.org/html/rfc6455) |
|
| 1020 |
+ |
|
| 1021 |
+**Example request** |
|
| 1022 |
+ |
|
| 1023 |
+ GET /containers/e90e34656806/attach/ws?logs=0&stream=1&stdin=1&stdout=1&stderr=1 HTTP/1.1 |
|
| 1024 |
+ |
|
| 1025 |
+**Example response** |
|
| 1026 |
+ |
|
| 1027 |
+ {{ STREAM }}
|
|
| 1028 |
+ |
|
| 1029 |
+Query Parameters: |
|
| 1030 |
+ |
|
| 1031 |
+- **logs** – 1/True/true or 0/False/false, return logs. Default `false`. |
|
| 1032 |
+- **stream** – 1/True/true or 0/False/false, return stream. |
|
| 1033 |
+ Default `false`. |
|
| 1034 |
+- **stdin** – 1/True/true or 0/False/false, if `stream=true`, attach |
|
| 1035 |
+ to `stdin`. Default `false`. |
|
| 1036 |
+- **stdout** – 1/True/true or 0/False/false, if `logs=true`, return |
|
| 1037 |
+ `stdout` log, if `stream=true`, attach to `stdout`. Default `false`. |
|
| 1038 |
+- **stderr** – 1/True/true or 0/False/false, if `logs=true`, return |
|
| 1039 |
+ `stderr` log, if `stream=true`, attach to `stderr`. Default `false`. |
|
| 1040 |
+ |
|
| 1041 |
+Status Codes: |
|
| 1042 |
+ |
|
| 1043 |
+- **200** – no error |
|
| 1044 |
+- **400** – bad parameter |
|
| 1045 |
+- **404** – no such container |
|
| 1046 |
+- **500** – server error |
|
| 1047 |
+ |
|
| 1048 |
+### Wait a container |
|
| 1049 |
+ |
|
| 1050 |
+`POST /containers/(id)/wait` |
|
| 1051 |
+ |
|
| 1052 |
+Block until container `id` stops, then returns the exit code |
|
| 1053 |
+ |
|
| 1054 |
+**Example request**: |
|
| 1055 |
+ |
|
| 1056 |
+ POST /containers/16253994b7c4/wait HTTP/1.1 |
|
| 1057 |
+ |
|
| 1058 |
+**Example response**: |
|
| 1059 |
+ |
|
| 1060 |
+ HTTP/1.1 200 OK |
|
| 1061 |
+ Content-Type: application/json |
|
| 1062 |
+ |
|
| 1063 |
+ {"StatusCode": 0}
|
|
| 1064 |
+ |
|
| 1065 |
+Status Codes: |
|
| 1066 |
+ |
|
| 1067 |
+- **200** – no error |
|
| 1068 |
+- **404** – no such container |
|
| 1069 |
+- **500** – server error |
|
| 1070 |
+ |
|
| 1071 |
+### Remove a container |
|
| 1072 |
+ |
|
| 1073 |
+`DELETE /containers/(id)` |
|
| 1074 |
+ |
|
| 1075 |
+Remove the container `id` from the filesystem |
|
| 1076 |
+ |
|
| 1077 |
+**Example request**: |
|
| 1078 |
+ |
|
| 1079 |
+ DELETE /containers/16253994b7c4?v=1 HTTP/1.1 |
|
| 1080 |
+ |
|
| 1081 |
+**Example response**: |
|
| 1082 |
+ |
|
| 1083 |
+ HTTP/1.1 204 No Content |
|
| 1084 |
+ |
|
| 1085 |
+Query Parameters: |
|
| 1086 |
+ |
|
| 1087 |
+- **v** – 1/True/true or 0/False/false, Remove the volumes |
|
| 1088 |
+ associated to the container. Default `false`. |
|
| 1089 |
+- **force** - 1/True/true or 0/False/false, Kill then remove the container. |
|
| 1090 |
+ Default `false`. |
|
| 1091 |
+ |
|
| 1092 |
+Status Codes: |
|
| 1093 |
+ |
|
| 1094 |
+- **204** – no error |
|
| 1095 |
+- **400** – bad parameter |
|
| 1096 |
+- **404** – no such container |
|
| 1097 |
+- **500** – server error |
|
| 1098 |
+ |
|
| 1099 |
+### Copy files or folders from a container |
|
| 1100 |
+ |
|
| 1101 |
+`POST /containers/(id)/copy` |
|
| 1102 |
+ |
|
| 1103 |
+Copy files or folders of container `id` |
|
| 1104 |
+ |
|
| 1105 |
+**Example request**: |
|
| 1106 |
+ |
|
| 1107 |
+ POST /containers/4fa6e0f0c678/copy HTTP/1.1 |
|
| 1108 |
+ Content-Type: application/json |
|
| 1109 |
+ |
|
| 1110 |
+ {
|
|
| 1111 |
+ "Resource": "test.txt" |
|
| 1112 |
+ } |
|
| 1113 |
+ |
|
| 1114 |
+**Example response**: |
|
| 1115 |
+ |
|
| 1116 |
+ HTTP/1.1 200 OK |
|
| 1117 |
+ Content-Type: application/x-tar |
|
| 1118 |
+ |
|
| 1119 |
+ {{ TAR STREAM }}
|
|
| 1120 |
+ |
|
| 1121 |
+Status Codes: |
|
| 1122 |
+ |
|
| 1123 |
+- **200** – no error |
|
| 1124 |
+- **404** – no such container |
|
| 1125 |
+- **500** – server error |
|
| 1126 |
+ |
|
| 1127 |
+## 2.2 Images |
|
| 1128 |
+ |
|
| 1129 |
+### List Images |
|
| 1130 |
+ |
|
| 1131 |
+`GET /images/json` |
|
| 1132 |
+ |
|
| 1133 |
+**Example request**: |
|
| 1134 |
+ |
|
| 1135 |
+ GET /images/json?all=0 HTTP/1.1 |
|
| 1136 |
+ |
|
| 1137 |
+**Example response**: |
|
| 1138 |
+ |
|
| 1139 |
+ HTTP/1.1 200 OK |
|
| 1140 |
+ Content-Type: application/json |
|
| 1141 |
+ |
|
| 1142 |
+ [ |
|
| 1143 |
+ {
|
|
| 1144 |
+ "RepoTags": [ |
|
| 1145 |
+ "ubuntu:12.04", |
|
| 1146 |
+ "ubuntu:precise", |
|
| 1147 |
+ "ubuntu:latest" |
|
| 1148 |
+ ], |
|
| 1149 |
+ "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c", |
|
| 1150 |
+ "Created": 1365714795, |
|
| 1151 |
+ "Size": 131506275, |
|
| 1152 |
+ "VirtualSize": 131506275 |
|
| 1153 |
+ }, |
|
| 1154 |
+ {
|
|
| 1155 |
+ "RepoTags": [ |
|
| 1156 |
+ "ubuntu:12.10", |
|
| 1157 |
+ "ubuntu:quantal" |
|
| 1158 |
+ ], |
|
| 1159 |
+ "ParentId": "27cf784147099545", |
|
| 1160 |
+ "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", |
|
| 1161 |
+ "Created": 1364102658, |
|
| 1162 |
+ "Size": 24653, |
|
| 1163 |
+ "VirtualSize": 180116135 |
|
| 1164 |
+ } |
|
| 1165 |
+ ] |
|
| 1166 |
+ |
|
| 1167 |
+**Example request, with digest information**: |
|
| 1168 |
+ |
|
| 1169 |
+ GET /images/json?digests=1 HTTP/1.1 |
|
| 1170 |
+ |
|
| 1171 |
+**Example response, with digest information**: |
|
| 1172 |
+ |
|
| 1173 |
+ HTTP/1.1 200 OK |
|
| 1174 |
+ Content-Type: application/json |
|
| 1175 |
+ |
|
| 1176 |
+ [ |
|
| 1177 |
+ {
|
|
| 1178 |
+ "Created": 1420064636, |
|
| 1179 |
+ "Id": "4986bf8c15363d1c5d15512d5266f8777bfba4974ac56e3270e7760f6f0a8125", |
|
| 1180 |
+ "ParentId": "ea13149945cb6b1e746bf28032f02e9b5a793523481a0a18645fc77ad53c4ea2", |
|
| 1181 |
+ "RepoDigests": [ |
|
| 1182 |
+ "localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf" |
|
| 1183 |
+ ], |
|
| 1184 |
+ "RepoTags": [ |
|
| 1185 |
+ "localhost:5000/test/busybox:latest", |
|
| 1186 |
+ "playdate:latest" |
|
| 1187 |
+ ], |
|
| 1188 |
+ "Size": 0, |
|
| 1189 |
+ "VirtualSize": 2429728 |
|
| 1190 |
+ } |
|
| 1191 |
+ ] |
|
| 1192 |
+ |
|
| 1193 |
+The response shows a single image `Id` associated with two repositories |
|
| 1194 |
+(`RepoTags`): `localhost:5000/test/busybox`: and `playdate`. A caller can use |
|
| 1195 |
+either of the `RepoTags` values `localhost:5000/test/busybox:latest` or |
|
| 1196 |
+`playdate:latest` to reference the image. |
|
| 1197 |
+ |
|
| 1198 |
+You can also use `RepoDigests` values to reference an image. In this response, |
|
| 1199 |
+the array has only one reference and that is to the |
|
| 1200 |
+`localhost:5000/test/busybox` repository; the `playdate` repository has no |
|
| 1201 |
+digest. You can reference this digest using the value: |
|
| 1202 |
+`localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d...` |
|
| 1203 |
+ |
|
| 1204 |
+See the `docker run` and `docker build` commands for examples of digest and tag |
|
| 1205 |
+references on the command line. |
|
| 1206 |
+ |
|
| 1207 |
+Query Parameters: |
|
| 1208 |
+ |
|
| 1209 |
+- **all** – 1/True/true or 0/False/false, default false |
|
| 1210 |
+- **filters** – a JSON encoded value of the filters (a map[string][]string) to process on the images list. Available filters: |
|
| 1211 |
+ - `dangling=true` |
|
| 1212 |
+ - `label=key` or `key=value` of an image label |
|
| 1213 |
+ |
|
| 1214 |
+### Build image from a Dockerfile |
|
| 1215 |
+ |
|
| 1216 |
+`POST /build` |
|
| 1217 |
+ |
|
| 1218 |
+Build an image from a Dockerfile |
|
| 1219 |
+ |
|
| 1220 |
+**Example request**: |
|
| 1221 |
+ |
|
| 1222 |
+ POST /build HTTP/1.1 |
|
| 1223 |
+ |
|
| 1224 |
+ {{ TAR STREAM }}
|
|
| 1225 |
+ |
|
| 1226 |
+**Example response**: |
|
| 1227 |
+ |
|
| 1228 |
+ HTTP/1.1 200 OK |
|
| 1229 |
+ Content-Type: application/json |
|
| 1230 |
+ |
|
| 1231 |
+ {"stream": "Step 1..."}
|
|
| 1232 |
+ {"stream": "..."}
|
|
| 1233 |
+ {"error": "Error...", "errorDetail": {"code": 123, "message": "Error..."}}
|
|
| 1234 |
+ |
|
| 1235 |
+The input stream must be a `tar` archive compressed with one of the |
|
| 1236 |
+following algorithms: `identity` (no compression), `gzip`, `bzip2`, `xz`. |
|
| 1237 |
+ |
|
| 1238 |
+The archive must include a build instructions file, typically called |
|
| 1239 |
+`Dockerfile` at the archive's root. The `dockerfile` parameter may be |
|
| 1240 |
+used to specify a different build instructions file. To do this, its value must be |
|
| 1241 |
+the path to the alternate build instructions file to use. |
|
| 1242 |
+ |
|
| 1243 |
+The archive may include any number of other files, |
|
| 1244 |
+which are accessible in the build context (See the [*ADD build |
|
| 1245 |
+command*](/reference/builder/#dockerbuilder)). |
|
| 1246 |
+ |
|
| 1247 |
+The build is canceled if the client drops the connection by quitting |
|
| 1248 |
+or being killed. |
|
| 1249 |
+ |
|
| 1250 |
+Query Parameters: |
|
| 1251 |
+ |
|
| 1252 |
+- **dockerfile** - Path within the build context to the Dockerfile. This is |
|
| 1253 |
+ ignored if `remote` is specified and points to an individual filename. |
|
| 1254 |
+- **t** – A repository name (and optionally a tag) to apply to |
|
| 1255 |
+ the resulting image in case of success. |
|
| 1256 |
+- **remote** – A Git repository URI or HTTP/HTTPS URI build source. If the |
|
| 1257 |
+ URI specifies a filename, the file's contents are placed into a file |
|
| 1258 |
+ called `Dockerfile`. |
|
| 1259 |
+- **q** – Suppress verbose build output. |
|
| 1260 |
+- **nocache** – Do not use the cache when building the image. |
|
| 1261 |
+- **pull** - Attempt to pull the image even if an older image exists locally. |
|
| 1262 |
+- **rm** - Remove intermediate containers after a successful build (default behavior). |
|
| 1263 |
+- **forcerm** - Always remove intermediate containers (includes `rm`). |
|
| 1264 |
+- **memory** - Set memory limit for build. |
|
| 1265 |
+- **memswap** - Total memory (memory + swap), `-1` to disable swap. |
|
| 1266 |
+- **cpushares** - CPU shares (relative weight). |
|
| 1267 |
+- **cpusetcpus** - CPUs in which to allow execution (e.g., `0-3`, `0,1`). |
|
| 1268 |
+ |
|
| 1269 |
+ Request Headers: |
|
| 1270 |
+ |
|
| 1271 |
+- **Content-type** – Set to `"application/tar"`. |
|
| 1272 |
+- **X-Registry-Config** – base64-encoded ConfigFile object |
|
| 1273 |
+ |
|
| 1274 |
+Status Codes: |
|
| 1275 |
+ |
|
| 1276 |
+- **200** – no error |
|
| 1277 |
+- **500** – server error |
|
| 1278 |
+ |
|
| 1279 |
+### Create an image |
|
| 1280 |
+ |
|
| 1281 |
+`POST /images/create` |
|
| 1282 |
+ |
|
| 1283 |
+Create an image either by pulling it from the registry or by importing it |
|
| 1284 |
+ |
|
| 1285 |
+**Example request**: |
|
| 1286 |
+ |
|
| 1287 |
+ POST /images/create?fromImage=ubuntu HTTP/1.1 |
|
| 1288 |
+ |
|
| 1289 |
+**Example response**: |
|
| 1290 |
+ |
|
| 1291 |
+ HTTP/1.1 200 OK |
|
| 1292 |
+ Content-Type: application/json |
|
| 1293 |
+ |
|
| 1294 |
+ {"status": "Pulling..."}
|
|
| 1295 |
+ {"status": "Pulling", "progress": "1 B/ 100 B", "progressDetail": {"current": 1, "total": 100}}
|
|
| 1296 |
+ {"error": "Invalid..."}
|
|
| 1297 |
+ ... |
|
| 1298 |
+ |
|
| 1299 |
+When using this endpoint to pull an image from the registry, the |
|
| 1300 |
+`X-Registry-Auth` header can be used to include |
|
| 1301 |
+a base64-encoded AuthConfig object. |
|
| 1302 |
+ |
|
| 1303 |
+Query Parameters: |
|
| 1304 |
+ |
|
| 1305 |
+- **fromImage** – Name of the image to pull. |
|
| 1306 |
+- **fromSrc** – Source to import. The value may be a URL from which the image |
|
| 1307 |
+ can be retrieved or `-` to read the image from the request body. |
|
| 1308 |
+- **repo** – Repository name. |
|
| 1309 |
+- **tag** – Tag. |
|
| 1310 |
+- **registry** – The registry to pull from. |
|
| 1311 |
+ |
|
| 1312 |
+ Request Headers: |
|
| 1313 |
+ |
|
| 1314 |
+- **X-Registry-Auth** – base64-encoded AuthConfig object |
|
| 1315 |
+ |
|
| 1316 |
+Status Codes: |
|
| 1317 |
+ |
|
| 1318 |
+- **200** – no error |
|
| 1319 |
+- **500** – server error |
|
| 1320 |
+ |
|
| 1321 |
+ |
|
| 1322 |
+ |
|
| 1323 |
+### Inspect an image |
|
| 1324 |
+ |
|
| 1325 |
+`GET /images/(name)/json` |
|
| 1326 |
+ |
|
| 1327 |
+Return low-level information on the image `name` |
|
| 1328 |
+ |
|
| 1329 |
+**Example request**: |
|
| 1330 |
+ |
|
| 1331 |
+ GET /images/ubuntu/json HTTP/1.1 |
|
| 1332 |
+ |
|
| 1333 |
+**Example response**: |
|
| 1334 |
+ |
|
| 1335 |
+ HTTP/1.1 200 OK |
|
| 1336 |
+ Content-Type: application/json |
|
| 1337 |
+ |
|
| 1338 |
+ {
|
|
| 1339 |
+ "Created": "2013-03-23T22:24:18.818426-07:00", |
|
| 1340 |
+ "Container": "3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0", |
|
| 1341 |
+ "ContainerConfig": |
|
| 1342 |
+ {
|
|
| 1343 |
+ "Hostname": "", |
|
| 1344 |
+ "User": "", |
|
| 1345 |
+ "AttachStdin": false, |
|
| 1346 |
+ "AttachStdout": false, |
|
| 1347 |
+ "AttachStderr": false, |
|
| 1348 |
+ "PortSpecs": null, |
|
| 1349 |
+ "Tty": true, |
|
| 1350 |
+ "OpenStdin": true, |
|
| 1351 |
+ "StdinOnce": false, |
|
| 1352 |
+ "Env": null, |
|
| 1353 |
+ "Cmd": ["/bin/bash"], |
|
| 1354 |
+ "Dns": null, |
|
| 1355 |
+ "Image": "ubuntu", |
|
| 1356 |
+ "Labels": {
|
|
| 1357 |
+ "com.example.vendor": "Acme", |
|
| 1358 |
+ "com.example.license": "GPL", |
|
| 1359 |
+ "com.example.version": "1.0" |
|
| 1360 |
+ }, |
|
| 1361 |
+ "Volumes": null, |
|
| 1362 |
+ "VolumesFrom": "", |
|
| 1363 |
+ "WorkingDir": "" |
|
| 1364 |
+ }, |
|
| 1365 |
+ "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", |
|
| 1366 |
+ "Parent": "27cf784147099545", |
|
| 1367 |
+ "Size": 6824592 |
|
| 1368 |
+ } |
|
| 1369 |
+ |
|
| 1370 |
+Status Codes: |
|
| 1371 |
+ |
|
| 1372 |
+- **200** – no error |
|
| 1373 |
+- **404** – no such image |
|
| 1374 |
+- **500** – server error |
|
| 1375 |
+ |
|
| 1376 |
+### Get the history of an image |
|
| 1377 |
+ |
|
| 1378 |
+`GET /images/(name)/history` |
|
| 1379 |
+ |
|
| 1380 |
+Return the history of the image `name` |
|
| 1381 |
+ |
|
| 1382 |
+**Example request**: |
|
| 1383 |
+ |
|
| 1384 |
+ GET /images/ubuntu/history HTTP/1.1 |
|
| 1385 |
+ |
|
| 1386 |
+**Example response**: |
|
| 1387 |
+ |
|
| 1388 |
+ HTTP/1.1 200 OK |
|
| 1389 |
+ Content-Type: application/json |
|
| 1390 |
+ |
|
| 1391 |
+ [ |
|
| 1392 |
+ {
|
|
| 1393 |
+ "Id": "b750fe79269d", |
|
| 1394 |
+ "Created": 1364102658, |
|
| 1395 |
+ "CreatedBy": "/bin/bash" |
|
| 1396 |
+ }, |
|
| 1397 |
+ {
|
|
| 1398 |
+ "Id": "27cf78414709", |
|
| 1399 |
+ "Created": 1364068391, |
|
| 1400 |
+ "CreatedBy": "" |
|
| 1401 |
+ } |
|
| 1402 |
+ ] |
|
| 1403 |
+ |
|
| 1404 |
+Status Codes: |
|
| 1405 |
+ |
|
| 1406 |
+- **200** – no error |
|
| 1407 |
+- **404** – no such image |
|
| 1408 |
+- **500** – server error |
|
| 1409 |
+ |
|
| 1410 |
+### Push an image on the registry |
|
| 1411 |
+ |
|
| 1412 |
+`POST /images/(name)/push` |
|
| 1413 |
+ |
|
| 1414 |
+Push the image `name` on the registry |
|
| 1415 |
+ |
|
| 1416 |
+**Example request**: |
|
| 1417 |
+ |
|
| 1418 |
+ POST /images/test/push HTTP/1.1 |
|
| 1419 |
+ |
|
| 1420 |
+**Example response**: |
|
| 1421 |
+ |
|
| 1422 |
+ HTTP/1.1 200 OK |
|
| 1423 |
+ Content-Type: application/json |
|
| 1424 |
+ |
|
| 1425 |
+ {"status": "Pushing..."}
|
|
| 1426 |
+ {"status": "Pushing", "progress": "1/? (n/a)", "progressDetail": {"current": 1}}}
|
|
| 1427 |
+ {"error": "Invalid..."}
|
|
| 1428 |
+ ... |
|
| 1429 |
+ |
|
| 1430 |
+If you wish to push an image on to a private registry, that image must already have a tag |
|
| 1431 |
+into a repository which references that registry `hostname` and `port`. This repository name should |
|
| 1432 |
+then be used in the URL. This duplicates the command line's flow. |
|
| 1433 |
+ |
|
| 1434 |
+**Example request**: |
|
| 1435 |
+ |
|
| 1436 |
+ POST /images/registry.acme.com:5000/test/push HTTP/1.1 |
|
| 1437 |
+ |
|
| 1438 |
+ |
|
| 1439 |
+Query Parameters: |
|
| 1440 |
+ |
|
| 1441 |
+- **tag** – The tag to associate with the image on the registry. This is optional. |
|
| 1442 |
+ |
|
| 1443 |
+Request Headers: |
|
| 1444 |
+ |
|
| 1445 |
+- **X-Registry-Auth** – Include a base64-encoded AuthConfig. |
|
| 1446 |
+ object. |
|
| 1447 |
+ |
|
| 1448 |
+Status Codes: |
|
| 1449 |
+ |
|
| 1450 |
+- **200** – no error |
|
| 1451 |
+- **404** – no such image |
|
| 1452 |
+- **500** – server error |
|
| 1453 |
+ |
|
| 1454 |
+### Tag an image into a repository |
|
| 1455 |
+ |
|
| 1456 |
+`POST /images/(name)/tag` |
|
| 1457 |
+ |
|
| 1458 |
+Tag the image `name` into a repository |
|
| 1459 |
+ |
|
| 1460 |
+**Example request**: |
|
| 1461 |
+ |
|
| 1462 |
+ POST /images/test/tag?repo=myrepo&force=0&tag=v42 HTTP/1.1 |
|
| 1463 |
+ |
|
| 1464 |
+**Example response**: |
|
| 1465 |
+ |
|
| 1466 |
+ HTTP/1.1 201 OK |
|
| 1467 |
+ |
|
| 1468 |
+Query Parameters: |
|
| 1469 |
+ |
|
| 1470 |
+- **repo** – The repository to tag in |
|
| 1471 |
+- **force** – 1/True/true or 0/False/false, default false |
|
| 1472 |
+- **tag** - The new tag name |
|
| 1473 |
+ |
|
| 1474 |
+Status Codes: |
|
| 1475 |
+ |
|
| 1476 |
+- **201** – no error |
|
| 1477 |
+- **400** – bad parameter |
|
| 1478 |
+- **404** – no such image |
|
| 1479 |
+- **409** – conflict |
|
| 1480 |
+- **500** – server error |
|
| 1481 |
+ |
|
| 1482 |
+### Remove an image |
|
| 1483 |
+ |
|
| 1484 |
+`DELETE /images/(name)` |
|
| 1485 |
+ |
|
| 1486 |
+Remove the image `name` from the filesystem |
|
| 1487 |
+ |
|
| 1488 |
+**Example request**: |
|
| 1489 |
+ |
|
| 1490 |
+ DELETE /images/test HTTP/1.1 |
|
| 1491 |
+ |
|
| 1492 |
+**Example response**: |
|
| 1493 |
+ |
|
| 1494 |
+ HTTP/1.1 200 OK |
|
| 1495 |
+ Content-type: application/json |
|
| 1496 |
+ |
|
| 1497 |
+ [ |
|
| 1498 |
+ {"Untagged": "3e2f21a89f"},
|
|
| 1499 |
+ {"Deleted": "3e2f21a89f"},
|
|
| 1500 |
+ {"Deleted": "53b4f83ac9"}
|
|
| 1501 |
+ ] |
|
| 1502 |
+ |
|
| 1503 |
+Query Parameters: |
|
| 1504 |
+ |
|
| 1505 |
+- **force** – 1/True/true or 0/False/false, default false |
|
| 1506 |
+- **noprune** – 1/True/true or 0/False/false, default false |
|
| 1507 |
+ |
|
| 1508 |
+Status Codes: |
|
| 1509 |
+ |
|
| 1510 |
+- **200** – no error |
|
| 1511 |
+- **404** – no such image |
|
| 1512 |
+- **409** – conflict |
|
| 1513 |
+- **500** – server error |
|
| 1514 |
+ |
|
| 1515 |
+### Search images |
|
| 1516 |
+ |
|
| 1517 |
+`GET /images/search` |
|
| 1518 |
+ |
|
| 1519 |
+Search for an image on [Docker Hub](https://hub.docker.com). |
|
| 1520 |
+ |
|
| 1521 |
+> **Note**: |
|
| 1522 |
+> The response keys have changed from API v1.6 to reflect the JSON |
|
| 1523 |
+> sent by the registry server to the docker daemon's request. |
|
| 1524 |
+ |
|
| 1525 |
+**Example request**: |
|
| 1526 |
+ |
|
| 1527 |
+ GET /images/search?term=sshd HTTP/1.1 |
|
| 1528 |
+ |
|
| 1529 |
+**Example response**: |
|
| 1530 |
+ |
|
| 1531 |
+ HTTP/1.1 200 OK |
|
| 1532 |
+ Content-Type: application/json |
|
| 1533 |
+ |
|
| 1534 |
+ [ |
|
| 1535 |
+ {
|
|
| 1536 |
+ "description": "", |
|
| 1537 |
+ "is_official": false, |
|
| 1538 |
+ "is_automated": false, |
|
| 1539 |
+ "name": "wma55/u1210sshd", |
|
| 1540 |
+ "star_count": 0 |
|
| 1541 |
+ }, |
|
| 1542 |
+ {
|
|
| 1543 |
+ "description": "", |
|
| 1544 |
+ "is_official": false, |
|
| 1545 |
+ "is_automated": false, |
|
| 1546 |
+ "name": "jdswinbank/sshd", |
|
| 1547 |
+ "star_count": 0 |
|
| 1548 |
+ }, |
|
| 1549 |
+ {
|
|
| 1550 |
+ "description": "", |
|
| 1551 |
+ "is_official": false, |
|
| 1552 |
+ "is_automated": false, |
|
| 1553 |
+ "name": "vgauthier/sshd", |
|
| 1554 |
+ "star_count": 0 |
|
| 1555 |
+ } |
|
| 1556 |
+ ... |
|
| 1557 |
+ ] |
|
| 1558 |
+ |
|
| 1559 |
+Query Parameters: |
|
| 1560 |
+ |
|
| 1561 |
+- **term** – term to search |
|
| 1562 |
+ |
|
| 1563 |
+Status Codes: |
|
| 1564 |
+ |
|
| 1565 |
+- **200** – no error |
|
| 1566 |
+- **500** – server error |
|
| 1567 |
+ |
|
| 1568 |
+## 2.3 Misc |
|
| 1569 |
+ |
|
| 1570 |
+### Check auth configuration |
|
| 1571 |
+ |
|
| 1572 |
+`POST /auth` |
|
| 1573 |
+ |
|
| 1574 |
+Get the default username and email |
|
| 1575 |
+ |
|
| 1576 |
+**Example request**: |
|
| 1577 |
+ |
|
| 1578 |
+ POST /auth HTTP/1.1 |
|
| 1579 |
+ Content-Type: application/json |
|
| 1580 |
+ |
|
| 1581 |
+ {
|
|
| 1582 |
+ "username":" hannibal", |
|
| 1583 |
+ "password: "xxxx", |
|
| 1584 |
+ "email": "hannibal@a-team.com", |
|
| 1585 |
+ "serveraddress": "https://index.docker.io/v1/" |
|
| 1586 |
+ } |
|
| 1587 |
+ |
|
| 1588 |
+**Example response**: |
|
| 1589 |
+ |
|
| 1590 |
+ HTTP/1.1 200 OK |
|
| 1591 |
+ |
|
| 1592 |
+Status Codes: |
|
| 1593 |
+ |
|
| 1594 |
+- **200** – no error |
|
| 1595 |
+- **204** – no error |
|
| 1596 |
+- **500** – server error |
|
| 1597 |
+ |
|
| 1598 |
+### Display system-wide information |
|
| 1599 |
+ |
|
| 1600 |
+`GET /info` |
|
| 1601 |
+ |
|
| 1602 |
+Display system-wide information |
|
| 1603 |
+ |
|
| 1604 |
+**Example request**: |
|
| 1605 |
+ |
|
| 1606 |
+ GET /info HTTP/1.1 |
|
| 1607 |
+ |
|
| 1608 |
+**Example response**: |
|
| 1609 |
+ |
|
| 1610 |
+ HTTP/1.1 200 OK |
|
| 1611 |
+ Content-Type: application/json |
|
| 1612 |
+ |
|
| 1613 |
+ {
|
|
| 1614 |
+ "Containers": 11, |
|
| 1615 |
+ "CpuCfsPeriod": true, |
|
| 1616 |
+ "CpuCfsQuota": true, |
|
| 1617 |
+ "Debug": false, |
|
| 1618 |
+ "DockerRootDir": "/var/lib/docker", |
|
| 1619 |
+ "Driver": "btrfs", |
|
| 1620 |
+ "DriverStatus": [[""]], |
|
| 1621 |
+ "ExecutionDriver": "native-0.1", |
|
| 1622 |
+ "ExperimentalBuild": false, |
|
| 1623 |
+ "HttpProxy": "http://test:test@localhost:8080", |
|
| 1624 |
+ "HttpsProxy": "https://test:test@localhost:8080", |
|
| 1625 |
+ "ID": "7TRN:IPZB:QYBB:VPBQ:UMPP:KARE:6ZNR:XE6T:7EWV:PKF4:ZOJD:TPYS", |
|
| 1626 |
+ "IPv4Forwarding": true, |
|
| 1627 |
+ "Images": 16, |
|
| 1628 |
+ "IndexServerAddress": "https://index.docker.io/v1/", |
|
| 1629 |
+ "InitPath": "/usr/bin/docker", |
|
| 1630 |
+ "InitSha1": "", |
|
| 1631 |
+ "KernelVersion": "3.12.0-1-amd64", |
|
| 1632 |
+ "Labels": [ |
|
| 1633 |
+ "storage=ssd" |
|
| 1634 |
+ ], |
|
| 1635 |
+ "MemTotal": 2099236864, |
|
| 1636 |
+ "MemoryLimit": true, |
|
| 1637 |
+ "NCPU": 1, |
|
| 1638 |
+ "NEventsListener": 0, |
|
| 1639 |
+ "NFd": 11, |
|
| 1640 |
+ "NGoroutines": 21, |
|
| 1641 |
+ "Name": "prod-server-42", |
|
| 1642 |
+ "NoProxy": "9.81.1.160", |
|
| 1643 |
+ "OomKillDisable": true, |
|
| 1644 |
+ "OperatingSystem": "Boot2Docker", |
|
| 1645 |
+ "RegistryConfig": {
|
|
| 1646 |
+ "IndexConfigs": {
|
|
| 1647 |
+ "docker.io": {
|
|
| 1648 |
+ "Mirrors": null, |
|
| 1649 |
+ "Name": "docker.io", |
|
| 1650 |
+ "Official": true, |
|
| 1651 |
+ "Secure": true |
|
| 1652 |
+ } |
|
| 1653 |
+ }, |
|
| 1654 |
+ "InsecureRegistryCIDRs": [ |
|
| 1655 |
+ "127.0.0.0/8" |
|
| 1656 |
+ ] |
|
| 1657 |
+ }, |
|
| 1658 |
+ "SwapLimit": false, |
|
| 1659 |
+ "SystemTime": "2015-03-10T11:11:23.730591467-07:00" |
|
| 1660 |
+ } |
|
| 1661 |
+ |
|
| 1662 |
+Status Codes: |
|
| 1663 |
+ |
|
| 1664 |
+- **200** – no error |
|
| 1665 |
+- **500** – server error |
|
| 1666 |
+ |
|
| 1667 |
+### Show the docker version information |
|
| 1668 |
+ |
|
| 1669 |
+`GET /version` |
|
| 1670 |
+ |
|
| 1671 |
+Show the docker version information |
|
| 1672 |
+ |
|
| 1673 |
+**Example request**: |
|
| 1674 |
+ |
|
| 1675 |
+ GET /version HTTP/1.1 |
|
| 1676 |
+ |
|
| 1677 |
+**Example response**: |
|
| 1678 |
+ |
|
| 1679 |
+ HTTP/1.1 200 OK |
|
| 1680 |
+ Content-Type: application/json |
|
| 1681 |
+ |
|
| 1682 |
+ {
|
|
| 1683 |
+ "Version": "1.5.0", |
|
| 1684 |
+ "Os": "linux", |
|
| 1685 |
+ "KernelVersion": "3.18.5-tinycore64", |
|
| 1686 |
+ "GoVersion": "go1.4.1", |
|
| 1687 |
+ "GitCommit": "a8a31ef", |
|
| 1688 |
+ "Arch": "amd64", |
|
| 1689 |
+ "ApiVersion": "1.19" |
|
| 1690 |
+ } |
|
| 1691 |
+ |
|
| 1692 |
+Status Codes: |
|
| 1693 |
+ |
|
| 1694 |
+- **200** – no error |
|
| 1695 |
+- **500** – server error |
|
| 1696 |
+ |
|
| 1697 |
+### Ping the docker server |
|
| 1698 |
+ |
|
| 1699 |
+`GET /_ping` |
|
| 1700 |
+ |
|
| 1701 |
+Ping the docker server |
|
| 1702 |
+ |
|
| 1703 |
+**Example request**: |
|
| 1704 |
+ |
|
| 1705 |
+ GET /_ping HTTP/1.1 |
|
| 1706 |
+ |
|
| 1707 |
+**Example response**: |
|
| 1708 |
+ |
|
| 1709 |
+ HTTP/1.1 200 OK |
|
| 1710 |
+ Content-Type: text/plain |
|
| 1711 |
+ |
|
| 1712 |
+ OK |
|
| 1713 |
+ |
|
| 1714 |
+Status Codes: |
|
| 1715 |
+ |
|
| 1716 |
+- **200** - no error |
|
| 1717 |
+- **500** - server error |
|
| 1718 |
+ |
|
| 1719 |
+### Create a new image from a container's changes |
|
| 1720 |
+ |
|
| 1721 |
+`POST /commit` |
|
| 1722 |
+ |
|
| 1723 |
+Create a new image from a container's changes |
|
| 1724 |
+ |
|
| 1725 |
+**Example request**: |
|
| 1726 |
+ |
|
| 1727 |
+ POST /commit?container=44c004db4b17&comment=message&repo=myrepo HTTP/1.1 |
|
| 1728 |
+ Content-Type: application/json |
|
| 1729 |
+ |
|
| 1730 |
+ {
|
|
| 1731 |
+ "Hostname": "", |
|
| 1732 |
+ "Domainname": "", |
|
| 1733 |
+ "User": "", |
|
| 1734 |
+ "AttachStdin": false, |
|
| 1735 |
+ "AttachStdout": true, |
|
| 1736 |
+ "AttachStderr": true, |
|
| 1737 |
+ "PortSpecs": null, |
|
| 1738 |
+ "Tty": false, |
|
| 1739 |
+ "OpenStdin": false, |
|
| 1740 |
+ "StdinOnce": false, |
|
| 1741 |
+ "Env": null, |
|
| 1742 |
+ "Cmd": [ |
|
| 1743 |
+ "date" |
|
| 1744 |
+ ], |
|
| 1745 |
+ "Volumes": {
|
|
| 1746 |
+ "/tmp": {}
|
|
| 1747 |
+ }, |
|
| 1748 |
+ "WorkingDir": "", |
|
| 1749 |
+ "NetworkDisabled": false, |
|
| 1750 |
+ "ExposedPorts": {
|
|
| 1751 |
+ "22/tcp": {}
|
|
| 1752 |
+ } |
|
| 1753 |
+ } |
|
| 1754 |
+ |
|
| 1755 |
+**Example response**: |
|
| 1756 |
+ |
|
| 1757 |
+ HTTP/1.1 201 Created |
|
| 1758 |
+ Content-Type: application/vnd.docker.raw-stream |
|
| 1759 |
+ |
|
| 1760 |
+ {"Id": "596069db4bf5"}
|
|
| 1761 |
+ |
|
| 1762 |
+Json Parameters: |
|
| 1763 |
+ |
|
| 1764 |
+- **config** - the container's configuration |
|
| 1765 |
+ |
|
| 1766 |
+Query Parameters: |
|
| 1767 |
+ |
|
| 1768 |
+- **container** – source container |
|
| 1769 |
+- **repo** – repository |
|
| 1770 |
+- **tag** – tag |
|
| 1771 |
+- **comment** – commit message |
|
| 1772 |
+- **author** – author (e.g., "John Hannibal Smith |
|
| 1773 |
+ <[hannibal@a-team.com](mailto:hannibal%40a-team.com)>") |
|
| 1774 |
+ |
|
| 1775 |
+Status Codes: |
|
| 1776 |
+ |
|
| 1777 |
+- **201** – no error |
|
| 1778 |
+- **404** – no such container |
|
| 1779 |
+- **500** – server error |
|
| 1780 |
+ |
|
| 1781 |
+### Monitor Docker's events |
|
| 1782 |
+ |
|
| 1783 |
+`GET /events` |
|
| 1784 |
+ |
|
| 1785 |
+Get container events from docker, either in real time via streaming, or via |
|
| 1786 |
+polling (using since). |
|
| 1787 |
+ |
|
| 1788 |
+Docker containers report the following events: |
|
| 1789 |
+ |
|
| 1790 |
+ create, destroy, die, exec_create, exec_start, export, kill, oom, pause, restart, start, stop, unpause |
|
| 1791 |
+ |
|
| 1792 |
+and Docker images report: |
|
| 1793 |
+ |
|
| 1794 |
+ untag, delete |
|
| 1795 |
+ |
|
| 1796 |
+**Example request**: |
|
| 1797 |
+ |
|
| 1798 |
+ GET /events?since=1374067924 |
|
| 1799 |
+ |
|
| 1800 |
+**Example response**: |
|
| 1801 |
+ |
|
| 1802 |
+ HTTP/1.1 200 OK |
|
| 1803 |
+ Content-Type: application/json |
|
| 1804 |
+ |
|
| 1805 |
+ {"status": "create", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924}
|
|
| 1806 |
+ {"status": "start", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924}
|
|
| 1807 |
+ {"status": "stop", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067966}
|
|
| 1808 |
+ {"status": "destroy", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067970}
|
|
| 1809 |
+ |
|
| 1810 |
+Query Parameters: |
|
| 1811 |
+ |
|
| 1812 |
+- **since** – Timestamp used for polling |
|
| 1813 |
+- **until** – Timestamp used for polling |
|
| 1814 |
+- **filters** – A json encoded value of the filters (a map[string][]string) to process on the event list. Available filters: |
|
| 1815 |
+ - `event=<string>`; -- event to filter |
|
| 1816 |
+ - `image=<string>`; -- image to filter |
|
| 1817 |
+ - `container=<string>`; -- container to filter |
|
| 1818 |
+ |
|
| 1819 |
+Status Codes: |
|
| 1820 |
+ |
|
| 1821 |
+- **200** – no error |
|
| 1822 |
+- **500** – server error |
|
| 1823 |
+ |
|
| 1824 |
+### Get a tarball containing all images in a repository |
|
| 1825 |
+ |
|
| 1826 |
+`GET /images/(name)/get` |
|
| 1827 |
+ |
|
| 1828 |
+Get a tarball containing all images and metadata for the repository specified |
|
| 1829 |
+by `name`. |
|
| 1830 |
+ |
|
| 1831 |
+If `name` is a specific name and tag (e.g. ubuntu:latest), then only that image |
|
| 1832 |
+(and its parents) are returned. If `name` is an image ID, similarly only that |
|
| 1833 |
+image (and its parents) are returned, but with the exclusion of the |
|
| 1834 |
+'repositories' file in the tarball, as there were no image names referenced. |
|
| 1835 |
+ |
|
| 1836 |
+See the [image tarball format](#image-tarball-format) for more details. |
|
| 1837 |
+ |
|
| 1838 |
+**Example request** |
|
| 1839 |
+ |
|
| 1840 |
+ GET /images/ubuntu/get |
|
| 1841 |
+ |
|
| 1842 |
+**Example response**: |
|
| 1843 |
+ |
|
| 1844 |
+ HTTP/1.1 200 OK |
|
| 1845 |
+ Content-Type: application/x-tar |
|
| 1846 |
+ |
|
| 1847 |
+ Binary data stream |
|
| 1848 |
+ |
|
| 1849 |
+Status Codes: |
|
| 1850 |
+ |
|
| 1851 |
+- **200** – no error |
|
| 1852 |
+- **500** – server error |
|
| 1853 |
+ |
|
| 1854 |
+### Get a tarball containing all images. |
|
| 1855 |
+ |
|
| 1856 |
+`GET /images/get` |
|
| 1857 |
+ |
|
| 1858 |
+Get a tarball containing all images and metadata for one or more repositories. |
|
| 1859 |
+ |
|
| 1860 |
+For each value of the `names` parameter: if it is a specific name and tag (e.g. |
|
| 1861 |
+`ubuntu:latest`), then only that image (and its parents) are returned; if it is |
|
| 1862 |
+an image ID, similarly only that image (and its parents) are returned and there |
|
| 1863 |
+would be no names referenced in the 'repositories' file for this image ID. |
|
| 1864 |
+ |
|
| 1865 |
+See the [image tarball format](#image-tarball-format) for more details. |
|
| 1866 |
+ |
|
| 1867 |
+**Example request** |
|
| 1868 |
+ |
|
| 1869 |
+ GET /images/get?names=myname%2Fmyapp%3Alatest&names=busybox |
|
| 1870 |
+ |
|
| 1871 |
+**Example response**: |
|
| 1872 |
+ |
|
| 1873 |
+ HTTP/1.1 200 OK |
|
| 1874 |
+ Content-Type: application/x-tar |
|
| 1875 |
+ |
|
| 1876 |
+ Binary data stream |
|
| 1877 |
+ |
|
| 1878 |
+Status Codes: |
|
| 1879 |
+ |
|
| 1880 |
+- **200** – no error |
|
| 1881 |
+- **500** – server error |
|
| 1882 |
+ |
|
| 1883 |
+### Load a tarball with a set of images and tags into docker |
|
| 1884 |
+ |
|
| 1885 |
+`POST /images/load` |
|
| 1886 |
+ |
|
| 1887 |
+Load a set of images and tags into a Docker repository. |
|
| 1888 |
+See the [image tarball format](#image-tarball-format) for more details. |
|
| 1889 |
+ |
|
| 1890 |
+**Example request** |
|
| 1891 |
+ |
|
| 1892 |
+ POST /images/load |
|
| 1893 |
+ |
|
| 1894 |
+ Tarball in body |
|
| 1895 |
+ |
|
| 1896 |
+**Example response**: |
|
| 1897 |
+ |
|
| 1898 |
+ HTTP/1.1 200 OK |
|
| 1899 |
+ |
|
| 1900 |
+Status Codes: |
|
| 1901 |
+ |
|
| 1902 |
+- **200** – no error |
|
| 1903 |
+- **500** – server error |
|
| 1904 |
+ |
|
| 1905 |
+### Image tarball format |
|
| 1906 |
+ |
|
| 1907 |
+An image tarball contains one directory per image layer (named using its long ID), |
|
| 1908 |
+each containing these files: |
|
| 1909 |
+ |
|
| 1910 |
+- `VERSION`: currently `1.0` - the file format version |
|
| 1911 |
+- `json`: detailed layer information, similar to `docker inspect layer_id` |
|
| 1912 |
+- `layer.tar`: A tarfile containing the filesystem changes in this layer |
|
| 1913 |
+ |
|
| 1914 |
+The `layer.tar` file contains `aufs` style `.wh..wh.aufs` files and directories |
|
| 1915 |
+for storing attribute changes and deletions. |
|
| 1916 |
+ |
|
| 1917 |
+If the tarball defines a repository, the tarball should also include a `repositories` file at |
|
| 1918 |
+the root that contains a list of repository and tag names mapped to layer IDs. |
|
| 1919 |
+ |
|
| 1920 |
+``` |
|
| 1921 |
+{"hello-world":
|
|
| 1922 |
+ {"latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"}
|
|
| 1923 |
+} |
|
| 1924 |
+``` |
|
| 1925 |
+ |
|
| 1926 |
+### Exec Create |
|
| 1927 |
+ |
|
| 1928 |
+`POST /containers/(id)/exec` |
|
| 1929 |
+ |
|
| 1930 |
+Sets up an exec instance in a running container `id` |
|
| 1931 |
+ |
|
| 1932 |
+**Example request**: |
|
| 1933 |
+ |
|
| 1934 |
+ POST /containers/e90e34656806/exec HTTP/1.1 |
|
| 1935 |
+ Content-Type: application/json |
|
| 1936 |
+ |
|
| 1937 |
+ {
|
|
| 1938 |
+ "AttachStdin": false, |
|
| 1939 |
+ "AttachStdout": true, |
|
| 1940 |
+ "AttachStderr": true, |
|
| 1941 |
+ "Tty": false, |
|
| 1942 |
+ "Cmd": [ |
|
| 1943 |
+ "date" |
|
| 1944 |
+ ], |
|
| 1945 |
+ } |
|
| 1946 |
+ |
|
| 1947 |
+**Example response**: |
|
| 1948 |
+ |
|
| 1949 |
+ HTTP/1.1 201 OK |
|
| 1950 |
+ Content-Type: application/json |
|
| 1951 |
+ |
|
| 1952 |
+ {
|
|
| 1953 |
+ "Id": "f90e34656806" |
|
| 1954 |
+ "Warnings":[] |
|
| 1955 |
+ } |
|
| 1956 |
+ |
|
| 1957 |
+Json Parameters: |
|
| 1958 |
+ |
|
| 1959 |
+- **AttachStdin** - Boolean value, attaches to `stdin` of the `exec` command. |
|
| 1960 |
+- **AttachStdout** - Boolean value, attaches to `stdout` of the `exec` command. |
|
| 1961 |
+- **AttachStderr** - Boolean value, attaches to `stderr` of the `exec` command. |
|
| 1962 |
+- **Tty** - Boolean value to allocate a pseudo-TTY. |
|
| 1963 |
+- **Cmd** - Command to run specified as a string or an array of strings. |
|
| 1964 |
+ |
|
| 1965 |
+ |
|
| 1966 |
+Status Codes: |
|
| 1967 |
+ |
|
| 1968 |
+- **201** – no error |
|
| 1969 |
+- **404** – no such container |
|
| 1970 |
+ |
|
| 1971 |
+### Exec Start |
|
| 1972 |
+ |
|
| 1973 |
+`POST /exec/(id)/start` |
|
| 1974 |
+ |
|
| 1975 |
+Starts a previously set up `exec` instance `id`. If `detach` is true, this API |
|
| 1976 |
+returns after starting the `exec` command. Otherwise, this API sets up an |
|
| 1977 |
+interactive session with the `exec` command. |
|
| 1978 |
+ |
|
| 1979 |
+**Example request**: |
|
| 1980 |
+ |
|
| 1981 |
+ POST /exec/e90e34656806/start HTTP/1.1 |
|
| 1982 |
+ Content-Type: application/json |
|
| 1983 |
+ |
|
| 1984 |
+ {
|
|
| 1985 |
+ "Detach": false, |
|
| 1986 |
+ "Tty": false, |
|
| 1987 |
+ } |
|
| 1988 |
+ |
|
| 1989 |
+**Example response**: |
|
| 1990 |
+ |
|
| 1991 |
+ HTTP/1.1 201 OK |
|
| 1992 |
+ Content-Type: application/json |
|
| 1993 |
+ |
|
| 1994 |
+ {{ STREAM }}
|
|
| 1995 |
+ |
|
| 1996 |
+Json Parameters: |
|
| 1997 |
+ |
|
| 1998 |
+- **Detach** - Detach from the `exec` command. |
|
| 1999 |
+- **Tty** - Boolean value to allocate a pseudo-TTY. |
|
| 2000 |
+ |
|
| 2001 |
+Status Codes: |
|
| 2002 |
+ |
|
| 2003 |
+- **201** – no error |
|
| 2004 |
+- **404** – no such exec instance |
|
| 2005 |
+ |
|
| 2006 |
+ **Stream details**: |
|
| 2007 |
+ Similar to the stream behavior of `POST /container/(id)/attach` API |
|
| 2008 |
+ |
|
| 2009 |
+### Exec Resize |
|
| 2010 |
+ |
|
| 2011 |
+`POST /exec/(id)/resize` |
|
| 2012 |
+ |
|
| 2013 |
+Resizes the `tty` session used by the `exec` command `id`. |
|
| 2014 |
+This API is valid only if `tty` was specified as part of creating and starting the `exec` command. |
|
| 2015 |
+ |
|
| 2016 |
+**Example request**: |
|
| 2017 |
+ |
|
| 2018 |
+ POST /exec/e90e34656806/resize HTTP/1.1 |
|
| 2019 |
+ Content-Type: text/plain |
|
| 2020 |
+ |
|
| 2021 |
+**Example response**: |
|
| 2022 |
+ |
|
| 2023 |
+ HTTP/1.1 201 OK |
|
| 2024 |
+ Content-Type: text/plain |
|
| 2025 |
+ |
|
| 2026 |
+Query Parameters: |
|
| 2027 |
+ |
|
| 2028 |
+- **h** – height of `tty` session |
|
| 2029 |
+- **w** – width |
|
| 2030 |
+ |
|
| 2031 |
+Status Codes: |
|
| 2032 |
+ |
|
| 2033 |
+- **201** – no error |
|
| 2034 |
+- **404** – no such exec instance |
|
| 2035 |
+ |
|
| 2036 |
+### Exec Inspect |
|
| 2037 |
+ |
|
| 2038 |
+`GET /exec/(id)/json` |
|
| 2039 |
+ |
|
| 2040 |
+Return low-level information about the `exec` command `id`. |
|
| 2041 |
+ |
|
| 2042 |
+**Example request**: |
|
| 2043 |
+ |
|
| 2044 |
+ GET /exec/11fb006128e8ceb3942e7c58d77750f24210e35f879dd204ac975c184b820b39/json HTTP/1.1 |
|
| 2045 |
+ |
|
| 2046 |
+**Example response**: |
|
| 2047 |
+ |
|
| 2048 |
+ HTTP/1.1 200 OK |
|
| 2049 |
+ Content-Type: plain/text |
|
| 2050 |
+ |
|
| 2051 |
+ {
|
|
| 2052 |
+ "ID" : "11fb006128e8ceb3942e7c58d77750f24210e35f879dd204ac975c184b820b39", |
|
| 2053 |
+ "Running" : false, |
|
| 2054 |
+ "ExitCode" : 2, |
|
| 2055 |
+ "ProcessConfig" : {
|
|
| 2056 |
+ "privileged" : false, |
|
| 2057 |
+ "user" : "", |
|
| 2058 |
+ "tty" : false, |
|
| 2059 |
+ "entrypoint" : "sh", |
|
| 2060 |
+ "arguments" : [ |
|
| 2061 |
+ "-c", |
|
| 2062 |
+ "exit 2" |
|
| 2063 |
+ ] |
|
| 2064 |
+ }, |
|
| 2065 |
+ "OpenStdin" : false, |
|
| 2066 |
+ "OpenStderr" : false, |
|
| 2067 |
+ "OpenStdout" : false, |
|
| 2068 |
+ "Container" : {
|
|
| 2069 |
+ "State" : {
|
|
| 2070 |
+ "Running" : true, |
|
| 2071 |
+ "Paused" : false, |
|
| 2072 |
+ "Restarting" : false, |
|
| 2073 |
+ "OOMKilled" : false, |
|
| 2074 |
+ "Pid" : 3650, |
|
| 2075 |
+ "ExitCode" : 0, |
|
| 2076 |
+ "Error" : "", |
|
| 2077 |
+ "StartedAt" : "2014-11-17T22:26:03.717657531Z", |
|
| 2078 |
+ "FinishedAt" : "0001-01-01T00:00:00Z" |
|
| 2079 |
+ }, |
|
| 2080 |
+ "ID" : "8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c", |
|
| 2081 |
+ "Created" : "2014-11-17T22:26:03.626304998Z", |
|
| 2082 |
+ "Path" : "date", |
|
| 2083 |
+ "Args" : [], |
|
| 2084 |
+ "Config" : {
|
|
| 2085 |
+ "Hostname" : "8f177a186b97", |
|
| 2086 |
+ "Domainname" : "", |
|
| 2087 |
+ "User" : "", |
|
| 2088 |
+ "AttachStdin" : false, |
|
| 2089 |
+ "AttachStdout" : false, |
|
| 2090 |
+ "AttachStderr" : false, |
|
| 2091 |
+ "PortSpecs" : null, |
|
| 2092 |
+ "ExposedPorts" : null, |
|
| 2093 |
+ "Tty" : false, |
|
| 2094 |
+ "OpenStdin" : false, |
|
| 2095 |
+ "StdinOnce" : false, |
|
| 2096 |
+ "Env" : [ "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" ], |
|
| 2097 |
+ "Cmd" : [ |
|
| 2098 |
+ "date" |
|
| 2099 |
+ ], |
|
| 2100 |
+ "Image" : "ubuntu", |
|
| 2101 |
+ "Volumes" : null, |
|
| 2102 |
+ "WorkingDir" : "", |
|
| 2103 |
+ "Entrypoint" : null, |
|
| 2104 |
+ "NetworkDisabled" : false, |
|
| 2105 |
+ "MacAddress" : "", |
|
| 2106 |
+ "OnBuild" : null, |
|
| 2107 |
+ "SecurityOpt" : null |
|
| 2108 |
+ }, |
|
| 2109 |
+ "Image" : "5506de2b643be1e6febbf3b8a240760c6843244c41e12aa2f60ccbb7153d17f5", |
|
| 2110 |
+ "NetworkSettings" : {
|
|
| 2111 |
+ "IPAddress" : "172.17.0.2", |
|
| 2112 |
+ "IPPrefixLen" : 16, |
|
| 2113 |
+ "MacAddress" : "02:42:ac:11:00:02", |
|
| 2114 |
+ "Gateway" : "172.17.42.1", |
|
| 2115 |
+ "Bridge" : "docker0", |
|
| 2116 |
+ "PortMapping" : null, |
|
| 2117 |
+ "Ports" : {}
|
|
| 2118 |
+ }, |
|
| 2119 |
+ "ResolvConfPath" : "/var/lib/docker/containers/8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c/resolv.conf", |
|
| 2120 |
+ "HostnamePath" : "/var/lib/docker/containers/8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c/hostname", |
|
| 2121 |
+ "HostsPath" : "/var/lib/docker/containers/8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c/hosts", |
|
| 2122 |
+ "LogPath": "/var/lib/docker/containers/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b-json.log", |
|
| 2123 |
+ "Name" : "/test", |
|
| 2124 |
+ "Driver" : "aufs", |
|
| 2125 |
+ "ExecDriver" : "native-0.2", |
|
| 2126 |
+ "MountLabel" : "", |
|
| 2127 |
+ "ProcessLabel" : "", |
|
| 2128 |
+ "AppArmorProfile" : "", |
|
| 2129 |
+ "RestartCount" : 0, |
|
| 2130 |
+ "Volumes" : {},
|
|
| 2131 |
+ "VolumesRW" : {}
|
|
| 2132 |
+ } |
|
| 2133 |
+ } |
|
| 2134 |
+ |
|
| 2135 |
+Status Codes: |
|
| 2136 |
+ |
|
| 2137 |
+- **200** – no error |
|
| 2138 |
+- **404** – no such exec instance |
|
| 2139 |
+- **500** - server error |
|
| 2140 |
+ |
|
| 2141 |
+# 3. Going further |
|
| 2142 |
+ |
|
| 2143 |
+## 3.1 Inside `docker run` |
|
| 2144 |
+ |
|
| 2145 |
+As an example, the `docker run` command line makes the following API calls: |
|
| 2146 |
+ |
|
| 2147 |
+- Create the container |
|
| 2148 |
+ |
|
| 2149 |
+- If the status code is 404, it means the image doesn't exist: |
|
| 2150 |
+ - Try to pull it. |
|
| 2151 |
+ - Then, retry to create the container. |
|
| 2152 |
+ |
|
| 2153 |
+- Start the container. |
|
| 2154 |
+ |
|
| 2155 |
+- If you are not in detached mode: |
|
| 2156 |
+- Attach to the container, using `logs=1` (to have `stdout` and |
|
| 2157 |
+ `stderr` from the container's start) and `stream=1` |
|
| 2158 |
+ |
|
| 2159 |
+- If in detached mode or only `stdin` is attached, display the container's id. |
|
| 2160 |
+ |
|
| 2161 |
+## 3.2 Hijacking |
|
| 2162 |
+ |
|
| 2163 |
+In this version of the API, `/attach`, uses hijacking to transport `stdin`, |
|
| 2164 |
+`stdout`, and `stderr` on the same socket. |
|
| 2165 |
+ |
|
| 2166 |
+To hint potential proxies about connection hijacking, Docker client sends |
|
| 2167 |
+connection upgrade headers similarly to websocket. |
|
| 2168 |
+ |
|
| 2169 |
+ Upgrade: tcp |
|
| 2170 |
+ Connection: Upgrade |
|
| 2171 |
+ |
|
| 2172 |
+When Docker daemon detects the `Upgrade` header, it switches its status code |
|
| 2173 |
+from **200 OK** to **101 UPGRADED** and resends the same headers. |
|
| 2174 |
+ |
|
| 2175 |
+ |
|
| 2176 |
+## 3.3 CORS Requests |
|
| 2177 |
+ |
|
| 2178 |
+To set cross origin requests to the remote api please give values to |
|
| 2179 |
+`--api-cors-header` when running Docker in daemon mode. Set * (asterisk) allows all, |
|
| 2180 |
+default or blank means CORS disabled |
|
| 2181 |
+ |
|
| 2182 |
+ $ docker -d -H="192.168.1.9:2375" --api-cors-header="http://foo.bar" |