mirror of
https://github.com/genuinetools/reg.git
synced 2024-09-12 06:11:03 -04:00
3344 lines
96 KiB
Markdown
3344 lines
96 KiB
Markdown
![]() |
---
|
|||
|
title: "Engine API v1.22"
|
|||
|
description: "API Documentation for Docker"
|
|||
|
keywords: "API, Docker, rcli, REST, documentation"
|
|||
|
redirect_from:
|
|||
|
- /engine/reference/api/docker_remote_api_v1.22/
|
|||
|
- /reference/api/docker_remote_api_v1.22/
|
|||
|
---
|
|||
|
|
|||
|
<!-- This file is maintained within the moby/moby GitHub
|
|||
|
repository at https://github.com/moby/moby/. Make all
|
|||
|
pull requests against that repo. If you see this file in
|
|||
|
another repository, consider it read-only there, as it will
|
|||
|
periodically be overwritten by the definitive file. Pull
|
|||
|
requests which include edits to this file in other repositories
|
|||
|
will be rejected.
|
|||
|
-->
|
|||
|
|
|||
|
## 1. Brief introduction
|
|||
|
|
|||
|
- The daemon listens on `unix:///var/run/docker.sock` but you can
|
|||
|
[Bind Docker to another host/port or a Unix socket](../reference/commandline/dockerd.md#bind-docker-to-another-host-port-or-a-unix-socket).
|
|||
|
- The API tends to be REST. However, for some complex commands, like `attach`
|
|||
|
or `pull`, the HTTP connection is hijacked to transport `stdout`,
|
|||
|
`stdin` and `stderr`.
|
|||
|
- A `Content-Length` header should be present in `POST` requests to endpoints
|
|||
|
that expect a body.
|
|||
|
- To lock to a specific version of the API, you prefix the URL with the version
|
|||
|
of the API to use. For example, `/v1.18/info`. If no version is included in
|
|||
|
the URL, the maximum supported API version is used.
|
|||
|
- If the API version specified in the URL is not supported by the daemon, a HTTP
|
|||
|
`400 Bad Request` error message is returned.
|
|||
|
|
|||
|
## 2. Endpoints
|
|||
|
|
|||
|
### 2.1 Containers
|
|||
|
|
|||
|
#### List containers
|
|||
|
|
|||
|
`GET /containers/json`
|
|||
|
|
|||
|
List containers
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
GET /v1.22/containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 200 OK
|
|||
|
Content-Type: application/json
|
|||
|
|
|||
|
[
|
|||
|
{
|
|||
|
"Id": "8dfafdbc3a40",
|
|||
|
"Names":["/boring_feynman"],
|
|||
|
"Image": "ubuntu:latest",
|
|||
|
"ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82",
|
|||
|
"Command": "echo 1",
|
|||
|
"Created": 1367854155,
|
|||
|
"Status": "Exit 0",
|
|||
|
"Ports": [{"PrivatePort": 2222, "PublicPort": 3333, "Type": "tcp"}],
|
|||
|
"Labels": {
|
|||
|
"com.example.vendor": "Acme",
|
|||
|
"com.example.license": "GPL",
|
|||
|
"com.example.version": "1.0"
|
|||
|
},
|
|||
|
"SizeRw": 12288,
|
|||
|
"SizeRootFs": 0,
|
|||
|
"HostConfig": {
|
|||
|
"NetworkMode": "default"
|
|||
|
},
|
|||
|
"NetworkSettings": {
|
|||
|
"Networks": {
|
|||
|
"bridge": {
|
|||
|
"IPAMConfig": null,
|
|||
|
"Links": null,
|
|||
|
"Aliases": null,
|
|||
|
"NetworkID": "7ea29fc1412292a2d7bba362f9253545fecdfa8ce9a6e37dd10ba8bee7129812",
|
|||
|
"EndpointID": "2cdc4edb1ded3631c81f57966563e5c8525b81121bb3706a9a9a3ae102711f3f",
|
|||
|
"Gateway": "172.17.0.1",
|
|||
|
"IPAddress": "172.17.0.2",
|
|||
|
"IPPrefixLen": 16,
|
|||
|
"IPv6Gateway": "",
|
|||
|
"GlobalIPv6Address": "",
|
|||
|
"GlobalIPv6PrefixLen": 0,
|
|||
|
"MacAddress": "02:42:ac:11:00:02"
|
|||
|
}
|
|||
|
}
|
|||
|
}
|
|||
|
},
|
|||
|
{
|
|||
|
"Id": "9cd87474be90",
|
|||
|
"Names":["/coolName"],
|
|||
|
"Image": "ubuntu:latest",
|
|||
|
"ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82",
|
|||
|
"Command": "echo 222222",
|
|||
|
"Created": 1367854155,
|
|||
|
"Status": "Exit 0",
|
|||
|
"Ports": [],
|
|||
|
"Labels": {},
|
|||
|
"SizeRw": 12288,
|
|||
|
"SizeRootFs": 0,
|
|||
|
"HostConfig": {
|
|||
|
"NetworkMode": "default"
|
|||
|
},
|
|||
|
"NetworkSettings": {
|
|||
|
"Networks": {
|
|||
|
"bridge": {
|
|||
|
"IPAMConfig": null,
|
|||
|
"Links": null,
|
|||
|
"Aliases": null,
|
|||
|
"NetworkID": "7ea29fc1412292a2d7bba362f9253545fecdfa8ce9a6e37dd10ba8bee7129812",
|
|||
|
"EndpointID": "88eaed7b37b38c2a3f0c4bc796494fdf51b270c2d22656412a2ca5d559a64d7a",
|
|||
|
"Gateway": "172.17.0.1",
|
|||
|
"IPAddress": "172.17.0.8",
|
|||
|
"IPPrefixLen": 16,
|
|||
|
"IPv6Gateway": "",
|
|||
|
"GlobalIPv6Address": "",
|
|||
|
"GlobalIPv6PrefixLen": 0,
|
|||
|
"MacAddress": "02:42:ac:11:00:08"
|
|||
|
}
|
|||
|
}
|
|||
|
}
|
|||
|
},
|
|||
|
{
|
|||
|
"Id": "3176a2479c92",
|
|||
|
"Names":["/sleepy_dog"],
|
|||
|
"Image": "ubuntu:latest",
|
|||
|
"ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82",
|
|||
|
"Command": "echo 3333333333333333",
|
|||
|
"Created": 1367854154,
|
|||
|
"Status": "Exit 0",
|
|||
|
"Ports":[],
|
|||
|
"Labels": {},
|
|||
|
"SizeRw":12288,
|
|||
|
"SizeRootFs":0,
|
|||
|
"HostConfig": {
|
|||
|
"NetworkMode": "default"
|
|||
|
},
|
|||
|
"NetworkSettings": {
|
|||
|
"Networks": {
|
|||
|
"bridge": {
|
|||
|
"IPAMConfig": null,
|
|||
|
"Links": null,
|
|||
|
"Aliases": null,
|
|||
|
"NetworkID": "7ea29fc1412292a2d7bba362f9253545fecdfa8ce9a6e37dd10ba8bee7129812",
|
|||
|
"EndpointID": "8b27c041c30326d59cd6e6f510d4f8d1d570a228466f956edf7815508f78e30d",
|
|||
|
"Gateway": "172.17.0.1",
|
|||
|
"IPAddress": "172.17.0.6",
|
|||
|
"IPPrefixLen": 16,
|
|||
|
"IPv6Gateway": "",
|
|||
|
"GlobalIPv6Address": "",
|
|||
|
"GlobalIPv6PrefixLen": 0,
|
|||
|
"MacAddress": "02:42:ac:11:00:06"
|
|||
|
}
|
|||
|
}
|
|||
|
}
|
|||
|
},
|
|||
|
{
|
|||
|
"Id": "4cb07b47f9fb",
|
|||
|
"Names":["/running_cat"],
|
|||
|
"Image": "ubuntu:latest",
|
|||
|
"ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82",
|
|||
|
"Command": "echo 444444444444444444444444444444444",
|
|||
|
"Created": 1367854152,
|
|||
|
"Status": "Exit 0",
|
|||
|
"Ports": [],
|
|||
|
"Labels": {},
|
|||
|
"SizeRw": 12288,
|
|||
|
"SizeRootFs": 0,
|
|||
|
"HostConfig": {
|
|||
|
"NetworkMode": "default"
|
|||
|
},
|
|||
|
"NetworkSettings": {
|
|||
|
"Networks": {
|
|||
|
"bridge": {
|
|||
|
"IPAMConfig": null,
|
|||
|
"Links": null,
|
|||
|
"Aliases": null,
|
|||
|
"NetworkID": "7ea29fc1412292a2d7bba362f9253545fecdfa8ce9a6e37dd10ba8bee7129812",
|
|||
|
"EndpointID": "d91c7b2f0644403d7ef3095985ea0e2370325cd2332ff3a3225c4247328e66e9",
|
|||
|
"Gateway": "172.17.0.1",
|
|||
|
"IPAddress": "172.17.0.5",
|
|||
|
"IPPrefixLen": 16,
|
|||
|
"IPv6Gateway": "",
|
|||
|
"GlobalIPv6Address": "",
|
|||
|
"GlobalIPv6PrefixLen": 0,
|
|||
|
"MacAddress": "02:42:ac:11:00:05"
|
|||
|
}
|
|||
|
}
|
|||
|
}
|
|||
|
}
|
|||
|
]
|
|||
|
|
|||
|
**Query parameters**:
|
|||
|
|
|||
|
- **all** – 1/True/true or 0/False/false, Show all containers.
|
|||
|
Only running containers are shown by default (i.e., this defaults to false)
|
|||
|
- **limit** – Show `limit` last created
|
|||
|
containers, include non-running ones.
|
|||
|
- **since** – Show only containers created since Id, include
|
|||
|
non-running ones.
|
|||
|
- **before** – Show only containers created before Id, include
|
|||
|
non-running ones.
|
|||
|
- **size** – 1/True/true or 0/False/false, Show the containers
|
|||
|
sizes
|
|||
|
- **filters** - a JSON encoded value of the filters (a `map[string][]string`) to process on the containers list. Available filters:
|
|||
|
- `exited=<int>`; -- containers with exit code of `<int>` ;
|
|||
|
- `status=`(`created`|`restarting`|`running`|`paused`|`exited`|`dead`)
|
|||
|
- `label=key` or `label="key=value"` of a container label
|
|||
|
- `isolation=`(`default`|`process`|`hyperv`) (Windows daemon only)
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **200** – no error
|
|||
|
- **400** – bad parameter
|
|||
|
- **500** – server error
|
|||
|
|
|||
|
#### Create a container
|
|||
|
|
|||
|
`POST /containers/create`
|
|||
|
|
|||
|
Create a container
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
POST /v1.22/containers/create HTTP/1.1
|
|||
|
Content-Type: application/json
|
|||
|
Content-Length: 12345
|
|||
|
|
|||
|
{
|
|||
|
"Hostname": "",
|
|||
|
"Domainname": "",
|
|||
|
"User": "",
|
|||
|
"AttachStdin": false,
|
|||
|
"AttachStdout": true,
|
|||
|
"AttachStderr": true,
|
|||
|
"Tty": false,
|
|||
|
"OpenStdin": false,
|
|||
|
"StdinOnce": false,
|
|||
|
"Env": [
|
|||
|
"FOO=bar",
|
|||
|
"BAZ=quux"
|
|||
|
],
|
|||
|
"Cmd": [
|
|||
|
"date"
|
|||
|
],
|
|||
|
"Entrypoint": null,
|
|||
|
"Image": "ubuntu",
|
|||
|
"Labels": {
|
|||
|
"com.example.vendor": "Acme",
|
|||
|
"com.example.license": "GPL",
|
|||
|
"com.example.version": "1.0"
|
|||
|
},
|
|||
|
"Volumes": {
|
|||
|
"/volumes/data": {}
|
|||
|
},
|
|||
|
"WorkingDir": "",
|
|||
|
"NetworkDisabled": false,
|
|||
|
"MacAddress": "12:34:56:78:9a:bc",
|
|||
|
"ExposedPorts": {
|
|||
|
"22/tcp": {}
|
|||
|
},
|
|||
|
"StopSignal": "SIGTERM",
|
|||
|
"HostConfig": {
|
|||
|
"Binds": ["/tmp:/tmp"],
|
|||
|
"Tmpfs": { "/run": "rw,noexec,nosuid,size=65536k" },
|
|||
|
"Links": ["redis3:redis"],
|
|||
|
"Memory": 0,
|
|||
|
"MemorySwap": 0,
|
|||
|
"MemoryReservation": 0,
|
|||
|
"KernelMemory": 0,
|
|||
|
"CpuShares": 512,
|
|||
|
"CpuPeriod": 100000,
|
|||
|
"CpuQuota": 50000,
|
|||
|
"CpusetCpus": "0,1",
|
|||
|
"CpusetMems": "0,1",
|
|||
|
"BlkioWeight": 300,
|
|||
|
"BlkioWeightDevice": [{}],
|
|||
|
"BlkioDeviceReadBps": [{}],
|
|||
|
"BlkioDeviceReadIOps": [{}],
|
|||
|
"BlkioDeviceWriteBps": [{}],
|
|||
|
"BlkioDeviceWriteIOps": [{}],
|
|||
|
"MemorySwappiness": 60,
|
|||
|
"OomKillDisable": false,
|
|||
|
"OomScoreAdj": 500,
|
|||
|
"PidMode": "",
|
|||
|
"PortBindings": { "22/tcp": [{ "HostPort": "11022" }] },
|
|||
|
"PublishAllPorts": false,
|
|||
|
"Privileged": false,
|
|||
|
"ReadonlyRootfs": false,
|
|||
|
"Dns": ["8.8.8.8"],
|
|||
|
"DnsOptions": [""],
|
|||
|
"DnsSearch": [""],
|
|||
|
"ExtraHosts": null,
|
|||
|
"VolumesFrom": ["parent", "other:ro"],
|
|||
|
"CapAdd": ["NET_ADMIN"],
|
|||
|
"CapDrop": ["MKNOD"],
|
|||
|
"GroupAdd": ["newgroup"],
|
|||
|
"RestartPolicy": { "Name": "", "MaximumRetryCount": 0 },
|
|||
|
"NetworkMode": "bridge",
|
|||
|
"Devices": [],
|
|||
|
"Ulimits": [{}],
|
|||
|
"LogConfig": { "Type": "json-file", "Config": {} },
|
|||
|
"SecurityOpt": [],
|
|||
|
"CgroupParent": "",
|
|||
|
"VolumeDriver": "",
|
|||
|
"ShmSize": 67108864
|
|||
|
},
|
|||
|
"NetworkingConfig": {
|
|||
|
"EndpointsConfig": {
|
|||
|
"isolated_nw" : {
|
|||
|
"IPAMConfig": {
|
|||
|
"IPv4Address":"172.20.30.33",
|
|||
|
"IPv6Address":"2001:db8:abcd::3033"
|
|||
|
},
|
|||
|
"Links":["container_1", "container_2"],
|
|||
|
"Aliases":["server_x", "server_y"]
|
|||
|
}
|
|||
|
}
|
|||
|
}
|
|||
|
}
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 201 Created
|
|||
|
Content-Type: application/json
|
|||
|
|
|||
|
{
|
|||
|
"Id":"e90e34656806",
|
|||
|
"Warnings":[]
|
|||
|
}
|
|||
|
|
|||
|
**JSON parameters**:
|
|||
|
|
|||
|
- **Hostname** - A string value containing the hostname to use for the
|
|||
|
container.
|
|||
|
- **Domainname** - A string value containing the domain name to use
|
|||
|
for the container.
|
|||
|
- **User** - A string value specifying the user inside the container.
|
|||
|
- **AttachStdin** - Boolean value, attaches to `stdin`.
|
|||
|
- **AttachStdout** - Boolean value, attaches to `stdout`.
|
|||
|
- **AttachStderr** - Boolean value, attaches to `stderr`.
|
|||
|
- **Tty** - Boolean value, Attach standard streams to a `tty`, including `stdin` if it is not closed.
|
|||
|
- **OpenStdin** - Boolean value, opens `stdin`,
|
|||
|
- **StdinOnce** - Boolean value, close `stdin` after the 1 attached client disconnects.
|
|||
|
- **Env** - A list of environment variables in the form of `["VAR=value", ...]`
|
|||
|
- **Labels** - Adds a map of labels to a container. To specify a map: `{"key":"value", ... }`
|
|||
|
- **Cmd** - Command to run specified as a string or an array of strings.
|
|||
|
- **Entrypoint** - Set the entry point for the container as a string or an array
|
|||
|
of strings.
|
|||
|
- **Image** - A string specifying the image name to use for the container.
|
|||
|
- **Volumes** - An object mapping mount point paths (strings) inside the
|
|||
|
container to empty objects.
|
|||
|
- **WorkingDir** - A string specifying the working directory for commands to
|
|||
|
run in.
|
|||
|
- **NetworkDisabled** - Boolean value, when true disables networking for the
|
|||
|
container
|
|||
|
- **ExposedPorts** - An object mapping ports to an empty object in the form of:
|
|||
|
`"ExposedPorts": { "<port>/<tcp|udp>: {}" }`
|
|||
|
- **StopSignal** - Signal to stop a container as a string or unsigned integer. `SIGTERM` by default.
|
|||
|
- **HostConfig**
|
|||
|
- **Binds** – A list of volume bindings for this container. Each volume binding is a string in one of these forms:
|
|||
|
+ `host-src:container-dest` to bind-mount a host path into the
|
|||
|
container. Both `host-src`, and `container-dest` must be an
|
|||
|
_absolute_ path.
|
|||
|
+ `host-src:container-dest:ro` to make the bind mount read-only
|
|||
|
inside the container. Both `host-src`, and `container-dest` must be
|
|||
|
an _absolute_ path.
|
|||
|
+ `volume-name:container-dest` to bind-mount a volume managed by a
|
|||
|
volume driver into the container. `container-dest` must be an
|
|||
|
_absolute_ path.
|
|||
|
+ `volume-name:container-dest:ro` to mount the volume read-only
|
|||
|
inside the container. `container-dest` must be an _absolute_ path.
|
|||
|
- **Tmpfs** – A map of container directories which should be replaced by tmpfs mounts, and their corresponding
|
|||
|
mount options. A JSON object in the form `{ "/run": "rw,noexec,nosuid,size=65536k" }`.
|
|||
|
- **Links** - A list of links for the container. Each link entry should be
|
|||
|
in the form of `container_name:alias`.
|
|||
|
- **Memory** - Memory limit in bytes.
|
|||
|
- **MemorySwap** - Total memory limit (memory + swap); set `-1` to enable unlimited swap.
|
|||
|
You must use this with `memory` and make the swap value larger than `memory`.
|
|||
|
- **MemoryReservation** - Memory soft limit in bytes.
|
|||
|
- **KernelMemory** - Kernel memory limit in bytes.
|
|||
|
- **CpuShares** - An integer value containing the container's CPU Shares
|
|||
|
(ie. the relative weight vs other containers).
|
|||
|
- **CpuPeriod** - The length of a CPU period in microseconds.
|
|||
|
- **CpuQuota** - Microseconds of CPU time that the container can get in a CPU period.
|
|||
|
- **CpusetCpus** - String value containing the `cgroups CpusetCpus` to use.
|
|||
|
- **CpusetMems** - Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems.
|
|||
|
- **BlkioWeight** - Block IO weight (relative weight) accepts a weight value between 10 and 1000.
|
|||
|
- **BlkioWeightDevice** - Block IO weight (relative device weight) in the form of: `"BlkioWeightDevice": [{"Path": "device_path", "Weight": weight}]`
|
|||
|
- **BlkioDeviceReadBps** - Limit read rate (bytes per second) from a device in the form of: `"BlkioDeviceReadBps": [{"Path": "device_path", "Rate": rate}]`, for example:
|
|||
|
`"BlkioDeviceReadBps": [{"Path": "/dev/sda", "Rate": "1024"}]"`
|
|||
|
- **BlkioDeviceWriteBps** - Limit write rate (bytes per second) to a device in the form of: `"BlkioDeviceWriteBps": [{"Path": "device_path", "Rate": rate}]`, for example:
|
|||
|
`"BlkioDeviceWriteBps": [{"Path": "/dev/sda", "Rate": "1024"}]"`
|
|||
|
- **BlkioDeviceReadIOps** - Limit read rate (IO per second) from a device in the form of: `"BlkioDeviceReadIOps": [{"Path": "device_path", "Rate": rate}]`, for example:
|
|||
|
`"BlkioDeviceReadIOps": [{"Path": "/dev/sda", "Rate": "1000"}]`
|
|||
|
- **BlkioDeviceWriteIOps** - Limit write rate (IO per second) to a device in the form of: `"BlkioDeviceWriteIOps": [{"Path": "device_path", "Rate": rate}]`, for example:
|
|||
|
`"BlkioDeviceWriteIOps": [{"Path": "/dev/sda", "Rate": "1000"}]`
|
|||
|
- **MemorySwappiness** - Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100.
|
|||
|
- **OomKillDisable** - Boolean value, whether to disable OOM Killer for the container or not.
|
|||
|
- **OomScoreAdj** - An integer value containing the score given to the container in order to tune OOM killer preferences.
|
|||
|
- **PidMode** - Set the PID (Process) Namespace mode for the container;
|
|||
|
`"container:<name|id>"`: joins another container's PID namespace
|
|||
|
`"host"`: use the host's PID namespace inside the container
|
|||
|
- **PortBindings** - A map of exposed container ports and the host port they
|
|||
|
should map to. A JSON object in the form
|
|||
|
`{ <port>/<protocol>: [{ "HostPort": "<port>" }] }`
|
|||
|
Take note that `port` is specified as a string and not an integer value.
|
|||
|
- **PublishAllPorts** - Allocates an ephemeral host port for all of a container's
|
|||
|
exposed ports. Specified as a boolean value.
|
|||
|
|
|||
|
Ports are de-allocated when the container stops and allocated when the container starts.
|
|||
|
The allocated port might be changed when restarting the container.
|
|||
|
|
|||
|
The port is selected from the ephemeral port range that depends on the kernel.
|
|||
|
For example, on Linux the range is defined by `/proc/sys/net/ipv4/ip_local_port_range`.
|
|||
|
- **Privileged** - Gives the container full access to the host. Specified as
|
|||
|
a boolean value.
|
|||
|
- **ReadonlyRootfs** - Mount the container's root filesystem as read only.
|
|||
|
Specified as a boolean value.
|
|||
|
- **Dns** - A list of DNS servers for the container to use.
|
|||
|
- **DnsOptions** - A list of DNS options
|
|||
|
- **DnsSearch** - A list of DNS search domains
|
|||
|
- **ExtraHosts** - A list of hostnames/IP mappings to add to the
|
|||
|
container's `/etc/hosts` file. Specified in the form `["hostname:IP"]`.
|
|||
|
- **VolumesFrom** - A list of volumes to inherit from another container.
|
|||
|
Specified in the form `<container name>[:<ro|rw>]`
|
|||
|
- **CapAdd** - A list of kernel capabilities to add to the container.
|
|||
|
- **Capdrop** - A list of kernel capabilities to drop from the container.
|
|||
|
- **GroupAdd** - A list of additional groups that the container process will run as
|
|||
|
- **RestartPolicy** – The behavior to apply when the container exits. The
|
|||
|
value is an object with a `Name` property of either `"always"` to
|
|||
|
always restart, `"unless-stopped"` to restart always except when
|
|||
|
user has manually stopped the container or `"on-failure"` to restart only when the container
|
|||
|
exit code is non-zero. If `on-failure` is used, `MaximumRetryCount`
|
|||
|
controls the number of times to retry before giving up.
|
|||
|
The default is not to restart. (optional)
|
|||
|
An ever increasing delay (double the previous delay, starting at 100mS)
|
|||
|
is added before each restart to prevent flooding the server.
|
|||
|
- **NetworkMode** - Sets the networking mode for the container. Supported
|
|||
|
standard values are: `bridge`, `host`, `none`, and `container:<name|id>`. Any other value is taken
|
|||
|
as a custom network's name to which this container should connect to.
|
|||
|
- **Devices** - A list of devices to add to the container specified as a JSON object in the
|
|||
|
form
|
|||
|
`{ "PathOnHost": "/dev/deviceName", "PathInContainer": "/dev/deviceName", "CgroupPermissions": "mrw"}`
|
|||
|
- **Ulimits** - A list of ulimits to set in the container, specified as
|
|||
|
`{ "Name": <name>, "Soft": <soft limit>, "Hard": <hard limit> }`, for example:
|
|||
|
`Ulimits: { "Name": "nofile", "Soft": 1024, "Hard": 2048 }`
|
|||
|
- **SecurityOpt**: A list of string values to customize labels for MLS
|
|||
|
systems, such as SELinux.
|
|||
|
- **LogConfig** - Log configuration for the container, specified as a JSON object in the form
|
|||
|
`{ "Type": "<driver_name>", "Config": {"key1": "val1"}}`.
|
|||
|
Available types: `json-file`, `syslog`, `journald`, `gelf`, `awslogs`, `splunk`, `none`.
|
|||
|
`json-file` logging driver.
|
|||
|
- **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.
|
|||
|
- **VolumeDriver** - Driver that this container users to mount volumes.
|
|||
|
- **ShmSize** - Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB.
|
|||
|
|
|||
|
**Query parameters**:
|
|||
|
|
|||
|
- **name** – Assign the specified name to the container. Must
|
|||
|
match `/?[a-zA-Z0-9_-]+`.
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **201** – no error
|
|||
|
- **400** – bad parameter
|
|||
|
- **404** – no such container
|
|||
|
- **406** – impossible to attach (container not running)
|
|||
|
- **409** – conflict
|
|||
|
- **500** – server error
|
|||
|
|
|||
|
#### Inspect a container
|
|||
|
|
|||
|
`GET /containers/(id or name)/json`
|
|||
|
|
|||
|
Return low-level information on the container `id`
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
GET /v1.22/containers/4fa6e0f0c678/json HTTP/1.1
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 200 OK
|
|||
|
Content-Type: application/json
|
|||
|
|
|||
|
{
|
|||
|
"AppArmorProfile": "",
|
|||
|
"Args": [
|
|||
|
"-c",
|
|||
|
"exit 9"
|
|||
|
],
|
|||
|
"Config": {
|
|||
|
"AttachStderr": true,
|
|||
|
"AttachStdin": false,
|
|||
|
"AttachStdout": true,
|
|||
|
"Cmd": [
|
|||
|
"/bin/sh",
|
|||
|
"-c",
|
|||
|
"exit 9"
|
|||
|
],
|
|||
|
"Domainname": "",
|
|||
|
"Entrypoint": null,
|
|||
|
"Env": [
|
|||
|
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
|
|||
|
],
|
|||
|
"ExposedPorts": null,
|
|||
|
"Hostname": "ba033ac44011",
|
|||
|
"Image": "ubuntu",
|
|||
|
"Labels": {
|
|||
|
"com.example.vendor": "Acme",
|
|||
|
"com.example.license": "GPL",
|
|||
|
"com.example.version": "1.0"
|
|||
|
},
|
|||
|
"MacAddress": "",
|
|||
|
"NetworkDisabled": false,
|
|||
|
"OnBuild": null,
|
|||
|
"OpenStdin": false,
|
|||
|
"StdinOnce": false,
|
|||
|
"Tty": false,
|
|||
|
"User": "",
|
|||
|
"Volumes": {
|
|||
|
"/volumes/data": {}
|
|||
|
},
|
|||
|
"WorkingDir": "",
|
|||
|
"StopSignal": "SIGTERM"
|
|||
|
},
|
|||
|
"Created": "2015-01-06T15:47:31.485331387Z",
|
|||
|
"Driver": "devicemapper",
|
|||
|
"ExecIDs": null,
|
|||
|
"HostConfig": {
|
|||
|
"Binds": null,
|
|||
|
"BlkioWeight": 0,
|
|||
|
"BlkioWeightDevice": [{}],
|
|||
|
"BlkioDeviceReadBps": [{}],
|
|||
|
"BlkioDeviceWriteBps": [{}],
|
|||
|
"BlkioDeviceReadIOps": [{}],
|
|||
|
"BlkioDeviceWriteIOps": [{}],
|
|||
|
"CapAdd": null,
|
|||
|
"CapDrop": null,
|
|||
|
"ContainerIDFile": "",
|
|||
|
"CpusetCpus": "",
|
|||
|
"CpusetMems": "",
|
|||
|
"CpuShares": 0,
|
|||
|
"CpuPeriod": 100000,
|
|||
|
"Devices": [],
|
|||
|
"Dns": null,
|
|||
|
"DnsOptions": null,
|
|||
|
"DnsSearch": null,
|
|||
|
"ExtraHosts": null,
|
|||
|
"IpcMode": "",
|
|||
|
"Links": null,
|
|||
|
"LxcConf": [],
|
|||
|
"Memory": 0,
|
|||
|
"MemorySwap": 0,
|
|||
|
"MemoryReservation": 0,
|
|||
|
"KernelMemory": 0,
|
|||
|
"OomKillDisable": false,
|
|||
|
"OomScoreAdj": 500,
|
|||
|
"NetworkMode": "bridge",
|
|||
|
"PidMode": "",
|
|||
|
"PortBindings": {},
|
|||
|
"Privileged": false,
|
|||
|
"ReadonlyRootfs": false,
|
|||
|
"PublishAllPorts": false,
|
|||
|
"RestartPolicy": {
|
|||
|
"MaximumRetryCount": 2,
|
|||
|
"Name": "on-failure"
|
|||
|
},
|
|||
|
"LogConfig": {
|
|||
|
"Config": null,
|
|||
|
"Type": "json-file"
|
|||
|
},
|
|||
|
"SecurityOpt": null,
|
|||
|
"VolumesFrom": null,
|
|||
|
"Ulimits": [{}],
|
|||
|
"VolumeDriver": "",
|
|||
|
"ShmSize": 67108864
|
|||
|
},
|
|||
|
"HostnamePath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hostname",
|
|||
|
"HostsPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hosts",
|
|||
|
"LogPath": "/var/lib/docker/containers/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b-json.log",
|
|||
|
"Id": "ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39",
|
|||
|
"Image": "04c5d3b7b0656168630d3ba35d8889bd0e9caafcaeb3004d2bfbc47e7c5d35d2",
|
|||
|
"MountLabel": "",
|
|||
|
"Name": "/boring_euclid",
|
|||
|
"NetworkSettings": {
|
|||
|
"Bridge": "",
|
|||
|
"SandboxID": "",
|
|||
|
"HairpinMode": false,
|
|||
|
"LinkLocalIPv6Address": "",
|
|||
|
"LinkLocalIPv6PrefixLen": 0,
|
|||
|
"Ports": null,
|
|||
|
"SandboxKey": "",
|
|||
|
"SecondaryIPAddresses": null,
|
|||
|
"SecondaryIPv6Addresses": null,
|
|||
|
"EndpointID": "",
|
|||
|
"Gateway": "",
|
|||
|
"GlobalIPv6Address": "",
|
|||
|
"GlobalIPv6PrefixLen": 0,
|
|||
|
"IPAddress": "",
|
|||
|
"IPPrefixLen": 0,
|
|||
|
"IPv6Gateway": "",
|
|||
|
"MacAddress": "",
|
|||
|
"Networks": {
|
|||
|
"bridge": {
|
|||
|
"NetworkID": "7ea29fc1412292a2d7bba362f9253545fecdfa8ce9a6e37dd10ba8bee7129812",
|
|||
|
"EndpointID": "7587b82f0dada3656fda26588aee72630c6fab1536d36e394b2bfbcf898c971d",
|
|||
|
"Gateway": "172.17.0.1",
|
|||
|
"IPAddress": "172.17.0.2",
|
|||
|
"IPPrefixLen": 16,
|
|||
|
"IPv6Gateway": "",
|
|||
|
"GlobalIPv6Address": "",
|
|||
|
"GlobalIPv6PrefixLen": 0,
|
|||
|
"MacAddress": "02:42:ac:12:00:02"
|
|||
|
}
|
|||
|
}
|
|||
|
},
|
|||
|
"Path": "/bin/sh",
|
|||
|
"ProcessLabel": "",
|
|||
|
"ResolvConfPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/resolv.conf",
|
|||
|
"RestartCount": 1,
|
|||
|
"State": {
|
|||
|
"Error": "",
|
|||
|
"ExitCode": 9,
|
|||
|
"FinishedAt": "2015-01-06T15:47:32.080254511Z",
|
|||
|
"OOMKilled": false,
|
|||
|
"Dead": false,
|
|||
|
"Paused": false,
|
|||
|
"Pid": 0,
|
|||
|
"Restarting": false,
|
|||
|
"Running": true,
|
|||
|
"StartedAt": "2015-01-06T15:47:32.072697474Z",
|
|||
|
"Status": "running"
|
|||
|
},
|
|||
|
"Mounts": [
|
|||
|
{
|
|||
|
"Name": "fac362...80535",
|
|||
|
"Source": "/data",
|
|||
|
"Destination": "/data",
|
|||
|
"Driver": "local",
|
|||
|
"Mode": "ro,Z",
|
|||
|
"RW": false,
|
|||
|
"Propagation": ""
|
|||
|
}
|
|||
|
]
|
|||
|
}
|
|||
|
|
|||
|
**Example request, with size information**:
|
|||
|
|
|||
|
GET /v1.22/containers/4fa6e0f0c678/json?size=1 HTTP/1.1
|
|||
|
|
|||
|
**Example response, with size information**:
|
|||
|
|
|||
|
HTTP/1.1 200 OK
|
|||
|
Content-Type: application/json
|
|||
|
|
|||
|
{
|
|||
|
....
|
|||
|
"SizeRw": 0,
|
|||
|
"SizeRootFs": 972,
|
|||
|
....
|
|||
|
}
|
|||
|
|
|||
|
**Query parameters**:
|
|||
|
|
|||
|
- **size** – 1/True/true or 0/False/false, return container size information. Default is `false`.
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **200** – no error
|
|||
|
- **404** – no such container
|
|||
|
- **500** – server error
|
|||
|
|
|||
|
#### List processes running inside a container
|
|||
|
|
|||
|
`GET /containers/(id or name)/top`
|
|||
|
|
|||
|
List processes running inside the container `id`. On Unix systems this
|
|||
|
is done by running the `ps` command. This endpoint is not
|
|||
|
supported on Windows.
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
GET /v1.22/containers/4fa6e0f0c678/top HTTP/1.1
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 200 OK
|
|||
|
Content-Type: application/json
|
|||
|
|
|||
|
{
|
|||
|
"Titles" : [
|
|||
|
"UID", "PID", "PPID", "C", "STIME", "TTY", "TIME", "CMD"
|
|||
|
],
|
|||
|
"Processes" : [
|
|||
|
[
|
|||
|
"root", "13642", "882", "0", "17:03", "pts/0", "00:00:00", "/bin/bash"
|
|||
|
],
|
|||
|
[
|
|||
|
"root", "13735", "13642", "0", "17:06", "pts/0", "00:00:00", "sleep 10"
|
|||
|
]
|
|||
|
]
|
|||
|
}
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
GET /v1.22/containers/4fa6e0f0c678/top?ps_args=aux HTTP/1.1
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 200 OK
|
|||
|
Content-Type: application/json
|
|||
|
|
|||
|
{
|
|||
|
"Titles" : [
|
|||
|
"USER","PID","%CPU","%MEM","VSZ","RSS","TTY","STAT","START","TIME","COMMAND"
|
|||
|
]
|
|||
|
"Processes" : [
|
|||
|
[
|
|||
|
"root","13642","0.0","0.1","18172","3184","pts/0","Ss","17:03","0:00","/bin/bash"
|
|||
|
],
|
|||
|
[
|
|||
|
"root","13895","0.0","0.0","4348","692","pts/0","S+","17:15","0:00","sleep 10"
|
|||
|
]
|
|||
|
],
|
|||
|
}
|
|||
|
|
|||
|
**Query parameters**:
|
|||
|
|
|||
|
- **ps_args** – `ps` arguments to use (e.g., `aux`), defaults to `-ef`
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **200** – no error
|
|||
|
- **404** – no such container
|
|||
|
- **500** – server error
|
|||
|
|
|||
|
#### Get container logs
|
|||
|
|
|||
|
`GET /containers/(id or name)/logs`
|
|||
|
|
|||
|
Get `stdout` and `stderr` logs from the container ``id``
|
|||
|
|
|||
|
> **Note**:
|
|||
|
> This endpoint works only for containers with the `json-file` or `journald` logging drivers.
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
GET /v1.22/containers/4fa6e0f0c678/logs?stderr=1&stdout=1×tamps=1&follow=1&tail=10&since=1428990821 HTTP/1.1
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 101 UPGRADED
|
|||
|
Content-Type: application/vnd.docker.raw-stream
|
|||
|
Connection: Upgrade
|
|||
|
Upgrade: tcp
|
|||
|
|
|||
|
{% raw %}
|
|||
|
{{ STREAM }}
|
|||
|
{% endraw %}
|
|||
|
|
|||
|
**Query parameters**:
|
|||
|
|
|||
|
- **follow** – 1/True/true or 0/False/false, return stream. Default `false`.
|
|||
|
- **stdout** – 1/True/true or 0/False/false, show `stdout` log. Default `false`.
|
|||
|
- **stderr** – 1/True/true or 0/False/false, show `stderr` log. Default `false`.
|
|||
|
- **since** – UNIX timestamp (integer) to filter logs. Specifying a timestamp
|
|||
|
will only output log-entries since that timestamp. Default: 0 (unfiltered)
|
|||
|
- **timestamps** – 1/True/true or 0/False/false, print timestamps for
|
|||
|
every log line. Default `false`.
|
|||
|
- **tail** – Output specified number of lines at the end of logs: `all` or `<number>`. Default all.
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **101** – no error, hints proxy about hijacking
|
|||
|
- **200** – no error, no upgrade header found
|
|||
|
- **404** – no such container
|
|||
|
- **500** – server error
|
|||
|
|
|||
|
#### Inspect changes on a container's filesystem
|
|||
|
|
|||
|
`GET /containers/(id or name)/changes`
|
|||
|
|
|||
|
Inspect changes on container `id`'s filesystem
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
GET /v1.22/containers/4fa6e0f0c678/changes HTTP/1.1
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 200 OK
|
|||
|
Content-Type: application/json
|
|||
|
|
|||
|
[
|
|||
|
{
|
|||
|
"Path": "/dev",
|
|||
|
"Kind": 0
|
|||
|
},
|
|||
|
{
|
|||
|
"Path": "/dev/kmsg",
|
|||
|
"Kind": 1
|
|||
|
},
|
|||
|
{
|
|||
|
"Path": "/test",
|
|||
|
"Kind": 1
|
|||
|
}
|
|||
|
]
|
|||
|
|
|||
|
Values for `Kind`:
|
|||
|
|
|||
|
- `0`: Modify
|
|||
|
- `1`: Add
|
|||
|
- `2`: Delete
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **200** – no error
|
|||
|
- **404** – no such container
|
|||
|
- **500** – server error
|
|||
|
|
|||
|
#### Export a container
|
|||
|
|
|||
|
`GET /containers/(id or name)/export`
|
|||
|
|
|||
|
Export the contents of container `id`
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
GET /v1.22/containers/4fa6e0f0c678/export HTTP/1.1
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 200 OK
|
|||
|
Content-Type: application/octet-stream
|
|||
|
|
|||
|
{% raw %}
|
|||
|
{{ TAR STREAM }}
|
|||
|
{% endraw %}
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **200** – no error
|
|||
|
- **404** – no such container
|
|||
|
- **500** – server error
|
|||
|
|
|||
|
#### Get container stats based on resource usage
|
|||
|
|
|||
|
`GET /containers/(id or name)/stats`
|
|||
|
|
|||
|
This endpoint returns a live stream of a container's resource usage statistics.
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
GET /v1.22/containers/redis1/stats HTTP/1.1
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 200 OK
|
|||
|
Content-Type: application/json
|
|||
|
|
|||
|
{
|
|||
|
"read" : "2015-01-08T22:57:31.547920715Z",
|
|||
|
"networks": {
|
|||
|
"eth0": {
|
|||
|
"rx_bytes": 5338,
|
|||
|
"rx_dropped": 0,
|
|||
|
"rx_errors": 0,
|
|||
|
"rx_packets": 36,
|
|||
|
"tx_bytes": 648,
|
|||
|
"tx_dropped": 0,
|
|||
|
"tx_errors": 0,
|
|||
|
"tx_packets": 8
|
|||
|
},
|
|||
|
"eth5": {
|
|||
|
"rx_bytes": 4641,
|
|||
|
"rx_dropped": 0,
|
|||
|
"rx_errors": 0,
|
|||
|
"rx_packets": 26,
|
|||
|
"tx_bytes": 690,
|
|||
|
"tx_dropped": 0,
|
|||
|
"tx_errors": 0,
|
|||
|
"tx_packets": 9
|
|||
|
}
|
|||
|
},
|
|||
|
"memory_stats" : {
|
|||
|
"stats" : {
|
|||
|
"total_pgmajfault" : 0,
|
|||
|
"cache" : 0,
|
|||
|
"mapped_file" : 0,
|
|||
|
"total_inactive_file" : 0,
|
|||
|
"pgpgout" : 414,
|
|||
|
"rss" : 6537216,
|
|||
|
"total_mapped_file" : 0,
|
|||
|
"writeback" : 0,
|
|||
|
"unevictable" : 0,
|
|||
|
"pgpgin" : 477,
|
|||
|
"total_unevictable" : 0,
|
|||
|
"pgmajfault" : 0,
|
|||
|
"total_rss" : 6537216,
|
|||
|
"total_rss_huge" : 6291456,
|
|||
|
"total_writeback" : 0,
|
|||
|
"total_inactive_anon" : 0,
|
|||
|
"rss_huge" : 6291456,
|
|||
|
"hierarchical_memory_limit" : 67108864,
|
|||
|
"total_pgfault" : 964,
|
|||
|
"total_active_file" : 0,
|
|||
|
"active_anon" : 6537216,
|
|||
|
"total_active_anon" : 6537216,
|
|||
|
"total_pgpgout" : 414,
|
|||
|
"total_cache" : 0,
|
|||
|
"inactive_anon" : 0,
|
|||
|
"active_file" : 0,
|
|||
|
"pgfault" : 964,
|
|||
|
"inactive_file" : 0,
|
|||
|
"total_pgpgin" : 477
|
|||
|
},
|
|||
|
"max_usage" : 6651904,
|
|||
|
"usage" : 6537216,
|
|||
|
"failcnt" : 0,
|
|||
|
"limit" : 67108864
|
|||
|
},
|
|||
|
"blkio_stats" : {},
|
|||
|
"cpu_stats" : {
|
|||
|
"cpu_usage" : {
|
|||
|
"percpu_usage" : [
|
|||
|
8646879,
|
|||
|
24472255,
|
|||
|
36438778,
|
|||
|
30657443
|
|||
|
],
|
|||
|
"usage_in_usermode" : 50000000,
|
|||
|
"total_usage" : 100215355,
|
|||
|
"usage_in_kernelmode" : 30000000
|
|||
|
},
|
|||
|
"system_cpu_usage" : 739306590000000,
|
|||
|
"throttling_data" : {"periods":0,"throttled_periods":0,"throttled_time":0}
|
|||
|
},
|
|||
|
"precpu_stats" : {
|
|||
|
"cpu_usage" : {
|
|||
|
"percpu_usage" : [
|
|||
|
8646879,
|
|||
|
24350896,
|
|||
|
36438778,
|
|||
|
30657443
|
|||
|
],
|
|||
|
"usage_in_usermode" : 50000000,
|
|||
|
"total_usage" : 100093996,
|
|||
|
"usage_in_kernelmode" : 30000000
|
|||
|
},
|
|||
|
"system_cpu_usage" : 9492140000000,
|
|||
|
"throttling_data" : {"periods":0,"throttled_periods":0,"throttled_time":0}
|
|||
|
}
|
|||
|
}
|
|||
|
|
|||
|
The `precpu_stats` is the cpu statistic of last read, which is used for calculating the cpu usage percent. It is not the exact copy of the `cpu_stats` field.
|
|||
|
|
|||
|
**Query parameters**:
|
|||
|
|
|||
|
- **stream** – 1/True/true or 0/False/false, pull stats once then disconnect. Default `true`.
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **200** – no error
|
|||
|
- **404** – no such container
|
|||
|
- **500** – server error
|
|||
|
|
|||
|
#### Resize a container TTY
|
|||
|
|
|||
|
`POST /containers/(id or name)/resize`
|
|||
|
|
|||
|
Resize the TTY for container with `id`. The unit is number of characters. You must restart the container for the resize to take effect.
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
POST /v1.22/containers/4fa6e0f0c678/resize?h=40&w=80 HTTP/1.1
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 200 OK
|
|||
|
Content-Length: 0
|
|||
|
Content-Type: text/plain; charset=utf-8
|
|||
|
|
|||
|
**Query parameters**:
|
|||
|
|
|||
|
- **h** – height of `tty` session
|
|||
|
- **w** – width
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **200** – no error
|
|||
|
- **404** – No such container
|
|||
|
- **500** – Cannot resize container
|
|||
|
|
|||
|
#### Start a container
|
|||
|
|
|||
|
`POST /containers/(id or name)/start`
|
|||
|
|
|||
|
Start the container `id`
|
|||
|
|
|||
|
> **Note**:
|
|||
|
> For backwards compatibility, this endpoint accepts a `HostConfig` as JSON-encoded request body.
|
|||
|
> See [create a container](#create-a-container) for details.
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
POST /v1.22/containers/e90e34656806/start HTTP/1.1
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 204 No Content
|
|||
|
|
|||
|
**Query parameters**:
|
|||
|
|
|||
|
- **detachKeys** – Override the key sequence for detaching a
|
|||
|
container. Format is a single character `[a-Z]` or `ctrl-<value>`
|
|||
|
where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`.
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **204** – no error
|
|||
|
- **304** – container already started
|
|||
|
- **404** – no such container
|
|||
|
- **500** – server error
|
|||
|
|
|||
|
#### Stop a container
|
|||
|
|
|||
|
`POST /containers/(id or name)/stop`
|
|||
|
|
|||
|
Stop the container `id`
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
POST /v1.22/containers/e90e34656806/stop?t=5 HTTP/1.1
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 204 No Content
|
|||
|
|
|||
|
**Query parameters**:
|
|||
|
|
|||
|
- **t** – number of seconds to wait before killing the container
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **204** – no error
|
|||
|
- **304** – container already stopped
|
|||
|
- **404** – no such container
|
|||
|
- **500** – server error
|
|||
|
|
|||
|
#### Restart a container
|
|||
|
|
|||
|
`POST /containers/(id or name)/restart`
|
|||
|
|
|||
|
Restart the container `id`
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
POST /v1.22/containers/e90e34656806/restart?t=5 HTTP/1.1
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 204 No Content
|
|||
|
|
|||
|
**Query parameters**:
|
|||
|
|
|||
|
- **t** – number of seconds to wait before killing the container
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **204** – no error
|
|||
|
- **404** – no such container
|
|||
|
- **500** – server error
|
|||
|
|
|||
|
#### Kill a container
|
|||
|
|
|||
|
`POST /containers/(id or name)/kill`
|
|||
|
|
|||
|
Kill the container `id`
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
POST /v1.22/containers/e90e34656806/kill HTTP/1.1
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 204 No Content
|
|||
|
|
|||
|
**Query parameters**:
|
|||
|
|
|||
|
- **signal** - Signal to send to the container: integer or string like `SIGINT`.
|
|||
|
When not set, `SIGKILL` is assumed and the call waits for the container to exit.
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **204** – no error
|
|||
|
- **404** – no such container
|
|||
|
- **500** – server error
|
|||
|
|
|||
|
#### Update a container
|
|||
|
|
|||
|
`POST /containers/(id or name)/update`
|
|||
|
|
|||
|
Update resource configs of one or more containers.
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
POST /v1.22/containers/e90e34656806/update HTTP/1.1
|
|||
|
Content-Type: application/json
|
|||
|
|
|||
|
{
|
|||
|
"BlkioWeight": 300,
|
|||
|
"CpuShares": 512,
|
|||
|
"CpuPeriod": 100000,
|
|||
|
"CpuQuota": 50000,
|
|||
|
"CpusetCpus": "0,1",
|
|||
|
"CpusetMems": "0",
|
|||
|
"Memory": 314572800,
|
|||
|
"MemorySwap": 514288000,
|
|||
|
"MemoryReservation": 209715200,
|
|||
|
"KernelMemory": 52428800
|
|||
|
}
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 200 OK
|
|||
|
Content-Type: application/json
|
|||
|
|
|||
|
{
|
|||
|
"Warnings": []
|
|||
|
}
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **200** – no error
|
|||
|
- **400** – bad parameter
|
|||
|
- **404** – no such container
|
|||
|
- **500** – server error
|
|||
|
|
|||
|
#### Rename a container
|
|||
|
|
|||
|
`POST /containers/(id or name)/rename`
|
|||
|
|
|||
|
Rename the container `id` to a `new_name`
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
POST /v1.22/containers/e90e34656806/rename?name=new_name HTTP/1.1
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 204 No Content
|
|||
|
|
|||
|
**Query parameters**:
|
|||
|
|
|||
|
- **name** – new name for the container
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **204** – no error
|
|||
|
- **404** – no such container
|
|||
|
- **409** - conflict name already assigned
|
|||
|
- **500** – server error
|
|||
|
|
|||
|
#### Pause a container
|
|||
|
|
|||
|
`POST /containers/(id or name)/pause`
|
|||
|
|
|||
|
Pause the container `id`
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
POST /v1.22/containers/e90e34656806/pause HTTP/1.1
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 204 No Content
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **204** – no error
|
|||
|
- **404** – no such container
|
|||
|
- **500** – server error
|
|||
|
|
|||
|
#### Unpause a container
|
|||
|
|
|||
|
`POST /containers/(id or name)/unpause`
|
|||
|
|
|||
|
Unpause the container `id`
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
POST /v1.22/containers/e90e34656806/unpause HTTP/1.1
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 204 No Content
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **204** – no error
|
|||
|
- **404** – no such container
|
|||
|
- **500** – server error
|
|||
|
|
|||
|
#### Attach to a container
|
|||
|
|
|||
|
`POST /containers/(id or name)/attach`
|
|||
|
|
|||
|
Attach to the container `id`
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
POST /v1.22/containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 101 UPGRADED
|
|||
|
Content-Type: application/vnd.docker.raw-stream
|
|||
|
Connection: Upgrade
|
|||
|
Upgrade: tcp
|
|||
|
|
|||
|
{% raw %}
|
|||
|
{{ STREAM }}
|
|||
|
{% endraw %}
|
|||
|
|
|||
|
**Query parameters**:
|
|||
|
|
|||
|
- **detachKeys** – Override the key sequence for detaching a
|
|||
|
container. Format is a single character `[a-Z]` or `ctrl-<value>`
|
|||
|
where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`.
|
|||
|
- **logs** – 1/True/true or 0/False/false, return logs. Default `false`.
|
|||
|
- **stream** – 1/True/true or 0/False/false, return stream.
|
|||
|
Default `false`.
|
|||
|
- **stdin** – 1/True/true or 0/False/false, if `stream=true`, attach
|
|||
|
to `stdin`. Default `false`.
|
|||
|
- **stdout** – 1/True/true or 0/False/false, if `logs=true`, return
|
|||
|
`stdout` log, if `stream=true`, attach to `stdout`. Default `false`.
|
|||
|
- **stderr** – 1/True/true or 0/False/false, if `logs=true`, return
|
|||
|
`stderr` log, if `stream=true`, attach to `stderr`. Default `false`.
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **101** – no error, hints proxy about hijacking
|
|||
|
- **200** – no error, no upgrade header found
|
|||
|
- **400** – bad parameter
|
|||
|
- **404** – no such container
|
|||
|
- **409** - container is paused
|
|||
|
- **500** – server error
|
|||
|
|
|||
|
**Stream details**:
|
|||
|
|
|||
|
When using the TTY setting is enabled in
|
|||
|
[`POST /containers/create`
|
|||
|
](#create-a-container),
|
|||
|
the stream is the raw data from the process PTY and client's `stdin`.
|
|||
|
When the TTY is disabled, then the stream is multiplexed to separate
|
|||
|
`stdout` and `stderr`.
|
|||
|
|
|||
|
The format is a **Header** and a **Payload** (frame).
|
|||
|
|
|||
|
**HEADER**
|
|||
|
|
|||
|
The header contains the information which the stream writes (`stdout` or
|
|||
|
`stderr`). It also contains the size of the associated frame encoded in the
|
|||
|
last four bytes (`uint32`).
|
|||
|
|
|||
|
It is encoded on the first eight bytes like this:
|
|||
|
|
|||
|
header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4}
|
|||
|
|
|||
|
`STREAM_TYPE` can be:
|
|||
|
|
|||
|
- 0: `stdin` (is written on `stdout`)
|
|||
|
- 1: `stdout`
|
|||
|
- 2: `stderr`
|
|||
|
|
|||
|
`SIZE1, SIZE2, SIZE3, SIZE4` are the four bytes of
|
|||
|
the `uint32` size encoded as big endian.
|
|||
|
|
|||
|
**PAYLOAD**
|
|||
|
|
|||
|
The payload is the raw stream.
|
|||
|
|
|||
|
**IMPLEMENTATION**
|
|||
|
|
|||
|
The simplest way to implement the Attach protocol is the following:
|
|||
|
|
|||
|
1. Read eight bytes.
|
|||
|
2. Choose `stdout` or `stderr` depending on the first byte.
|
|||
|
3. Extract the frame size from the last four bytes.
|
|||
|
4. Read the extracted size and output it on the correct output.
|
|||
|
5. Goto 1.
|
|||
|
|
|||
|
#### Attach to a container (websocket)
|
|||
|
|
|||
|
`GET /containers/(id or name)/attach/ws`
|
|||
|
|
|||
|
Attach to the container `id` via websocket
|
|||
|
|
|||
|
Implements websocket protocol handshake according to [RFC 6455](http://tools.ietf.org/html/rfc6455)
|
|||
|
|
|||
|
**Example request**
|
|||
|
|
|||
|
GET /v1.22/containers/e90e34656806/attach/ws?logs=0&stream=1&stdin=1&stdout=1&stderr=1 HTTP/1.1
|
|||
|
|
|||
|
**Example response**
|
|||
|
|
|||
|
{% raw %}
|
|||
|
{{ STREAM }}
|
|||
|
{% endraw %}
|
|||
|
|
|||
|
**Query parameters**:
|
|||
|
|
|||
|
- **detachKeys** – Override the key sequence for detaching a
|
|||
|
container. Format is a single character `[a-Z]` or `ctrl-<value>`
|
|||
|
where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`.
|
|||
|
- **logs** – 1/True/true or 0/False/false, return logs. Default `false`.
|
|||
|
- **stream** – 1/True/true or 0/False/false, return stream.
|
|||
|
Default `false`.
|
|||
|
- **stdin** – 1/True/true or 0/False/false, if `stream=true`, attach
|
|||
|
to `stdin`. Default `false`.
|
|||
|
- **stdout** – 1/True/true or 0/False/false, if `logs=true`, return
|
|||
|
`stdout` log, if `stream=true`, attach to `stdout`. Default `false`.
|
|||
|
- **stderr** – 1/True/true or 0/False/false, if `logs=true`, return
|
|||
|
`stderr` log, if `stream=true`, attach to `stderr`. Default `false`.
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **200** – no error
|
|||
|
- **400** – bad parameter
|
|||
|
- **404** – no such container
|
|||
|
- **500** – server error
|
|||
|
|
|||
|
#### Wait a container
|
|||
|
|
|||
|
`POST /containers/(id or name)/wait`
|
|||
|
|
|||
|
Block until container `id` stops, then returns the exit code
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
POST /v1.22/containers/16253994b7c4/wait HTTP/1.1
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 200 OK
|
|||
|
Content-Type: application/json
|
|||
|
|
|||
|
{"StatusCode": 0}
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **200** – no error
|
|||
|
- **404** – no such container
|
|||
|
- **500** – server error
|
|||
|
|
|||
|
#### Remove a container
|
|||
|
|
|||
|
`DELETE /containers/(id or name)`
|
|||
|
|
|||
|
Remove the container `id` from the filesystem
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
DELETE /v1.22/containers/16253994b7c4?v=1 HTTP/1.1
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 204 No Content
|
|||
|
|
|||
|
**Query parameters**:
|
|||
|
|
|||
|
- **v** – 1/True/true or 0/False/false, Remove the volumes
|
|||
|
associated to the container. Default `false`.
|
|||
|
- **force** - 1/True/true or 0/False/false, Kill then remove the container.
|
|||
|
Default `false`.
|
|||
|
- **link** - 1/True/true or 0/False/false, Remove the specified
|
|||
|
link associated to the container. Default `false`.
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **204** – no error
|
|||
|
- **400** – bad parameter
|
|||
|
- **404** – no such container
|
|||
|
- **409** – conflict
|
|||
|
- **500** – server error
|
|||
|
|
|||
|
#### Copy files or folders from a container
|
|||
|
|
|||
|
`POST /containers/(id or name)/copy`
|
|||
|
|
|||
|
Copy files or folders of container `id`
|
|||
|
|
|||
|
**Deprecated** in favor of the `archive` endpoint below.
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
POST /v1.22/containers/4fa6e0f0c678/copy HTTP/1.1
|
|||
|
Content-Type: application/json
|
|||
|
Content-Length: 12345
|
|||
|
|
|||
|
{
|
|||
|
"Resource": "test.txt"
|
|||
|
}
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 200 OK
|
|||
|
Content-Type: application/x-tar
|
|||
|
|
|||
|
{% raw %}
|
|||
|
{{ TAR STREAM }}
|
|||
|
{% endraw %}
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **200** – no error
|
|||
|
- **404** – no such container
|
|||
|
- **500** – server error
|
|||
|
|
|||
|
#### Retrieving information about files and folders in a container
|
|||
|
|
|||
|
`HEAD /containers/(id or name)/archive`
|
|||
|
|
|||
|
See the description of the `X-Docker-Container-Path-Stat` header in the
|
|||
|
following section.
|
|||
|
|
|||
|
#### Get an archive of a filesystem resource in a container
|
|||
|
|
|||
|
`GET /containers/(id or name)/archive`
|
|||
|
|
|||
|
Get a tar archive of a resource in the filesystem of container `id`.
|
|||
|
|
|||
|
**Query parameters**:
|
|||
|
|
|||
|
- **path** - resource in the container's filesystem to archive. Required.
|
|||
|
|
|||
|
If not an absolute path, it is relative to the container's root directory.
|
|||
|
The resource specified by **path** must exist. To assert that the resource
|
|||
|
is expected to be a directory, **path** should end in `/` or `/.`
|
|||
|
(assuming a path separator of `/`). If **path** ends in `/.` then this
|
|||
|
indicates that only the contents of the **path** directory should be
|
|||
|
copied. A symlink is always resolved to its target.
|
|||
|
|
|||
|
> **Note**: It is not possible to copy certain system files such as resources
|
|||
|
> under `/proc`, `/sys`, `/dev`, and mounts created by the user in the
|
|||
|
> container.
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
GET /v1.22/containers/8cce319429b2/archive?path=/root HTTP/1.1
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 200 OK
|
|||
|
Content-Type: application/x-tar
|
|||
|
X-Docker-Container-Path-Stat: eyJuYW1lIjoicm9vdCIsInNpemUiOjQwOTYsIm1vZGUiOjIxNDc0ODQwOTYsIm10aW1lIjoiMjAxNC0wMi0yN1QyMDo1MToyM1oiLCJsaW5rVGFyZ2V0IjoiIn0=
|
|||
|
|
|||
|
{% raw %}
|
|||
|
{{ TAR STREAM }}
|
|||
|
{% endraw %}
|
|||
|
|
|||
|
On success, a response header `X-Docker-Container-Path-Stat` will be set to a
|
|||
|
base64-encoded JSON object containing some filesystem header information about
|
|||
|
the archived resource. The above example value would decode to the following
|
|||
|
JSON object (whitespace added for readability):
|
|||
|
|
|||
|
```json
|
|||
|
{
|
|||
|
"name": "root",
|
|||
|
"size": 4096,
|
|||
|
"mode": 2147484096,
|
|||
|
"mtime": "2014-02-27T20:51:23Z",
|
|||
|
"linkTarget": ""
|
|||
|
}
|
|||
|
```
|
|||
|
|
|||
|
A `HEAD` request can also be made to this endpoint if only this information is
|
|||
|
desired.
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **200** - success, returns archive of copied resource
|
|||
|
- **400** - client error, bad parameter, details in JSON response body, one of:
|
|||
|
- must specify path parameter (**path** cannot be empty)
|
|||
|
- not a directory (**path** was asserted to be a directory but exists as a
|
|||
|
file)
|
|||
|
- **404** - client error, resource not found, one of:
|
|||
|
– no such container (container `id` does not exist)
|
|||
|
- no such file or directory (**path** does not exist)
|
|||
|
- **500** - server error
|
|||
|
|
|||
|
#### Extract an archive of files or folders to a directory in a container
|
|||
|
|
|||
|
`PUT /containers/(id or name)/archive`
|
|||
|
|
|||
|
Upload a tar archive to be extracted to a path in the filesystem of container
|
|||
|
`id`.
|
|||
|
|
|||
|
**Query parameters**:
|
|||
|
|
|||
|
- **path** - path to a directory in the container
|
|||
|
to extract the archive's contents into. Required.
|
|||
|
|
|||
|
If not an absolute path, it is relative to the container's root directory.
|
|||
|
The **path** resource must exist.
|
|||
|
- **noOverwriteDirNonDir** - If "1", "true", or "True" then it will be an error
|
|||
|
if unpacking the given content would cause an existing directory to be
|
|||
|
replaced with a non-directory and vice versa.
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
PUT /v1.22/containers/8cce319429b2/archive?path=/vol1 HTTP/1.1
|
|||
|
Content-Type: application/x-tar
|
|||
|
|
|||
|
{% raw %}
|
|||
|
{{ TAR STREAM }}
|
|||
|
{% endraw %}
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 200 OK
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **200** – the content was extracted successfully
|
|||
|
- **400** - client error, bad parameter, details in JSON response body, one of:
|
|||
|
- must specify path parameter (**path** cannot be empty)
|
|||
|
- not a directory (**path** should be a directory but exists as a file)
|
|||
|
- unable to overwrite existing directory with non-directory
|
|||
|
(if **noOverwriteDirNonDir**)
|
|||
|
- unable to overwrite existing non-directory with directory
|
|||
|
(if **noOverwriteDirNonDir**)
|
|||
|
- **403** - client error, permission denied, the volume
|
|||
|
or container rootfs is marked as read-only.
|
|||
|
- **404** - client error, resource not found, one of:
|
|||
|
– no such container (container `id` does not exist)
|
|||
|
- no such file or directory (**path** resource does not exist)
|
|||
|
- **500** – server error
|
|||
|
|
|||
|
### 2.2 Images
|
|||
|
|
|||
|
#### List Images
|
|||
|
|
|||
|
`GET /images/json`
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
GET /v1.22/images/json?all=0 HTTP/1.1
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 200 OK
|
|||
|
Content-Type: application/json
|
|||
|
|
|||
|
[
|
|||
|
{
|
|||
|
"RepoTags": [
|
|||
|
"ubuntu:12.04",
|
|||
|
"ubuntu:precise",
|
|||
|
"ubuntu:latest"
|
|||
|
],
|
|||
|
"Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c",
|
|||
|
"Created": 1365714795,
|
|||
|
"Size": 131506275,
|
|||
|
"VirtualSize": 131506275,
|
|||
|
"Labels": {}
|
|||
|
},
|
|||
|
{
|
|||
|
"RepoTags": [
|
|||
|
"ubuntu:12.10",
|
|||
|
"ubuntu:quantal"
|
|||
|
],
|
|||
|
"ParentId": "27cf784147099545",
|
|||
|
"Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc",
|
|||
|
"Created": 1364102658,
|
|||
|
"Size": 24653,
|
|||
|
"VirtualSize": 180116135,
|
|||
|
"Labels": {
|
|||
|
"com.example.version": "v1"
|
|||
|
}
|
|||
|
}
|
|||
|
]
|
|||
|
|
|||
|
**Example request, with digest information**:
|
|||
|
|
|||
|
GET /v1.22/images/json?digests=1 HTTP/1.1
|
|||
|
|
|||
|
**Example response, with digest information**:
|
|||
|
|
|||
|
HTTP/1.1 200 OK
|
|||
|
Content-Type: application/json
|
|||
|
|
|||
|
[
|
|||
|
{
|
|||
|
"Created": 1420064636,
|
|||
|
"Id": "4986bf8c15363d1c5d15512d5266f8777bfba4974ac56e3270e7760f6f0a8125",
|
|||
|
"ParentId": "ea13149945cb6b1e746bf28032f02e9b5a793523481a0a18645fc77ad53c4ea2",
|
|||
|
"RepoDigests": [
|
|||
|
"localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf"
|
|||
|
],
|
|||
|
"RepoTags": [
|
|||
|
"localhost:5000/test/busybox:latest",
|
|||
|
"playdate:latest"
|
|||
|
],
|
|||
|
"Size": 0,
|
|||
|
"VirtualSize": 2429728,
|
|||
|
"Labels": {}
|
|||
|
}
|
|||
|
]
|
|||
|
|
|||
|
The response shows a single image `Id` associated with two repositories
|
|||
|
(`RepoTags`): `localhost:5000/test/busybox`: and `playdate`. A caller can use
|
|||
|
either of the `RepoTags` values `localhost:5000/test/busybox:latest` or
|
|||
|
`playdate:latest` to reference the image.
|
|||
|
|
|||
|
You can also use `RepoDigests` values to reference an image. In this response,
|
|||
|
the array has only one reference and that is to the
|
|||
|
`localhost:5000/test/busybox` repository; the `playdate` repository has no
|
|||
|
digest. You can reference this digest using the value:
|
|||
|
`localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d...`
|
|||
|
|
|||
|
See the `docker run` and `docker build` commands for examples of digest and tag
|
|||
|
references on the command line.
|
|||
|
|
|||
|
**Query parameters**:
|
|||
|
|
|||
|
- **all** – 1/True/true or 0/False/false, default false
|
|||
|
- **filters** – a JSON encoded value of the filters (a map[string][]string) to process on the images list. Available filters:
|
|||
|
- `dangling=true`
|
|||
|
- `label=key` or `label="key=value"` of an image label
|
|||
|
- **filter** - only return images with the specified name
|
|||
|
|
|||
|
#### Build image from a Dockerfile
|
|||
|
|
|||
|
`POST /build`
|
|||
|
|
|||
|
Build an image from a Dockerfile
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
POST /v1.22/build HTTP/1.1
|
|||
|
Content-Type: application/x-tar
|
|||
|
|
|||
|
{% raw %}
|
|||
|
{{ TAR STREAM }}
|
|||
|
{% endraw %}
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 200 OK
|
|||
|
Content-Type: application/json
|
|||
|
|
|||
|
{"stream": "Step 1/5..."}
|
|||
|
{"stream": "..."}
|
|||
|
{"error": "Error...", "errorDetail": {"code": 123, "message": "Error..."}}
|
|||
|
|
|||
|
The input stream must be a `tar` archive compressed with one of the
|
|||
|
following algorithms: `identity` (no compression), `gzip`, `bzip2`, `xz`.
|
|||
|
|
|||
|
The archive must include a build instructions file, typically called
|
|||
|
`Dockerfile` at the archive's root. The `dockerfile` parameter may be
|
|||
|
used to specify a different build instructions file. To do this, its value must be
|
|||
|
the path to the alternate build instructions file to use.
|
|||
|
|
|||
|
The archive may include any number of other files,
|
|||
|
which are accessible in the build context (See the [*ADD build
|
|||
|
command*](../reference/builder.md#add)).
|
|||
|
|
|||
|
The Docker daemon performs a preliminary validation of the `Dockerfile` before
|
|||
|
starting the build, and returns an error if the syntax is incorrect. After that,
|
|||
|
each instruction is run one-by-one until the ID of the new image is output.
|
|||
|
|
|||
|
The build is canceled if the client drops the connection by quitting
|
|||
|
or being killed.
|
|||
|
|
|||
|
**Query parameters**:
|
|||
|
|
|||
|
- **dockerfile** - Path within the build context to the `Dockerfile`. This is
|
|||
|
ignored if `remote` is specified and points to an external `Dockerfile`.
|
|||
|
- **t** – A name and optional tag to apply to the image in the `name:tag` format.
|
|||
|
If you omit the `tag` the default `latest` value is assumed.
|
|||
|
You can provide one or more `t` parameters.
|
|||
|
- **remote** – A Git repository URI or HTTP/HTTPS context URI. If the
|
|||
|
URI points to a single text file, the file's contents are placed into
|
|||
|
a file called `Dockerfile` and the image is built from that file. If
|
|||
|
the URI points to a tarball, the file is downloaded by the daemon and
|
|||
|
the contents therein used as the context for the build. If the URI
|
|||
|
points to a tarball and the `dockerfile` parameter is also specified,
|
|||
|
there must be a file with the corresponding path inside the tarball.
|
|||
|
- **q** – Suppress verbose build output.
|
|||
|
- **nocache** – Do not use the cache when building the image.
|
|||
|
- **pull** - Attempt to pull the image even if an older image exists locally.
|
|||
|
- **rm** - Remove intermediate containers after a successful build (default behavior).
|
|||
|
- **forcerm** - Always remove intermediate containers (includes `rm`).
|
|||
|
- **memory** - Set memory limit for build.
|
|||
|
- **memswap** - Total memory (memory + swap), `-1` to enable unlimited swap.
|
|||
|
- **cpushares** - CPU shares (relative weight).
|
|||
|
- **cpusetcpus** - CPUs in which to allow execution (e.g., `0-3`, `0,1`).
|
|||
|
- **cpuperiod** - The length of a CPU period in microseconds.
|
|||
|
- **cpuquota** - Microseconds of CPU time that the container can get in a CPU period.
|
|||
|
- **buildargs** – JSON map of string pairs for build-time variables. Users pass
|
|||
|
these values at build-time. Docker uses the `buildargs` as the environment
|
|||
|
context for command(s) run via the Dockerfile's `RUN` instruction or for
|
|||
|
variable expansion in other Dockerfile instructions. This is not meant for
|
|||
|
passing secret values. [Read more about the buildargs instruction](../reference/builder.md#arg)
|
|||
|
- **shmsize** - Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB.
|
|||
|
|
|||
|
**Request Headers**:
|
|||
|
|
|||
|
- **Content-type** – Set to `"application/x-tar"`.
|
|||
|
- **X-Registry-Config** – A base64-url-safe-encoded Registry Auth Config JSON
|
|||
|
object with the following structure:
|
|||
|
|
|||
|
{
|
|||
|
"docker.example.com": {
|
|||
|
"username": "janedoe",
|
|||
|
"password": "hunter2"
|
|||
|
},
|
|||
|
"https://index.docker.io/v1/": {
|
|||
|
"username": "mobydock",
|
|||
|
"password": "conta1n3rize14"
|
|||
|
}
|
|||
|
}
|
|||
|
|
|||
|
This object maps the hostname of a registry to an object containing the
|
|||
|
"username" and "password" for that registry. Multiple registries may
|
|||
|
be specified as the build may be based on an image requiring
|
|||
|
authentication to pull from any arbitrary registry. Only the registry
|
|||
|
domain name (and port if not the default "443") are required. However
|
|||
|
(for legacy reasons) the "official" Docker, Inc. hosted registry must
|
|||
|
be specified with both a "https://" prefix and a "/v1/" suffix even
|
|||
|
though Docker will prefer to use the v2 registry API.
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **200** – no error
|
|||
|
- **500** – server error
|
|||
|
|
|||
|
#### Create an image
|
|||
|
|
|||
|
`POST /images/create`
|
|||
|
|
|||
|
Create an image either by pulling it from the registry or by importing it
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
POST /v1.22/images/create?fromImage=busybox&tag=latest HTTP/1.1
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 200 OK
|
|||
|
Content-Type: application/json
|
|||
|
|
|||
|
{"status": "Pulling..."}
|
|||
|
{"status": "Pulling", "progress": "1 B/ 100 B", "progressDetail": {"current": 1, "total": 100}}
|
|||
|
{"error": "Invalid..."}
|
|||
|
...
|
|||
|
|
|||
|
When using this endpoint to pull an image from the registry, the
|
|||
|
`X-Registry-Auth` header can be used to include
|
|||
|
a base64-encoded AuthConfig object.
|
|||
|
|
|||
|
**Query parameters**:
|
|||
|
|
|||
|
- **fromImage** – Name of the image to pull. The name may include a tag or
|
|||
|
digest. This parameter may only be used when pulling an image.
|
|||
|
The pull is cancelled if the HTTP connection is closed.
|
|||
|
- **fromSrc** – Source to import. The value may be a URL from which the image
|
|||
|
can be retrieved or `-` to read the image from the request body.
|
|||
|
This parameter may only be used when importing an image.
|
|||
|
- **repo** – Repository name given to an image when it is imported.
|
|||
|
The repo may include a tag. This parameter may only be used when importing
|
|||
|
an image.
|
|||
|
- **tag** – Tag or digest. If empty when pulling an image, this causes all tags
|
|||
|
for the given image to be pulled.
|
|||
|
|
|||
|
**Request Headers**:
|
|||
|
|
|||
|
- **X-Registry-Auth** – base64-encoded AuthConfig object, containing either login information, or a token
|
|||
|
- Credential based login:
|
|||
|
|
|||
|
```
|
|||
|
{
|
|||
|
"username": "jdoe",
|
|||
|
"password": "secret",
|
|||
|
"email": "jdoe@acme.com"
|
|||
|
}
|
|||
|
```
|
|||
|
|
|||
|
- Token based login:
|
|||
|
|
|||
|
```
|
|||
|
{
|
|||
|
"registrytoken": "9cbaf023786cd7..."
|
|||
|
}
|
|||
|
```
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **200** – no error
|
|||
|
- **404** - repository does not exist or no read access
|
|||
|
- **500** – server error
|
|||
|
|
|||
|
|
|||
|
|
|||
|
#### Inspect an image
|
|||
|
|
|||
|
`GET /images/(name)/json`
|
|||
|
|
|||
|
Return low-level information on the image `name`
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
GET /v1.22/images/example/json HTTP/1.1
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 200 OK
|
|||
|
Content-Type: application/json
|
|||
|
|
|||
|
{
|
|||
|
"Id" : "85f05633ddc1c50679be2b16a0479ab6f7637f8884e0cfe0f4d20e1ebb3d6e7c",
|
|||
|
"Container" : "cb91e48a60d01f1e27028b4fc6819f4f290b3cf12496c8176ec714d0d390984a",
|
|||
|
"Comment" : "",
|
|||
|
"Os" : "linux",
|
|||
|
"Architecture" : "amd64",
|
|||
|
"Parent" : "91e54dfb11794fad694460162bf0cb0a4fa710cfa3f60979c177d920813e267c",
|
|||
|
"ContainerConfig" : {
|
|||
|
"Tty" : false,
|
|||
|
"Hostname" : "e611e15f9c9d",
|
|||
|
"Volumes" : null,
|
|||
|
"Domainname" : "",
|
|||
|
"AttachStdout" : false,
|
|||
|
"PublishService" : "",
|
|||
|
"AttachStdin" : false,
|
|||
|
"OpenStdin" : false,
|
|||
|
"StdinOnce" : false,
|
|||
|
"NetworkDisabled" : false,
|
|||
|
"OnBuild" : [],
|
|||
|
"Image" : "91e54dfb11794fad694460162bf0cb0a4fa710cfa3f60979c177d920813e267c",
|
|||
|
"User" : "",
|
|||
|
"WorkingDir" : "",
|
|||
|
"Entrypoint" : null,
|
|||
|
"MacAddress" : "",
|
|||
|
"AttachStderr" : false,
|
|||
|
"Labels" : {
|
|||
|
"com.example.license" : "GPL",
|
|||
|
"com.example.version" : "1.0",
|
|||
|
"com.example.vendor" : "Acme"
|
|||
|
},
|
|||
|
"Env" : [
|
|||
|
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
|
|||
|
],
|
|||
|
"ExposedPorts" : null,
|
|||
|
"Cmd" : [
|
|||
|
"/bin/sh",
|
|||
|
"-c",
|
|||
|
"#(nop) LABEL com.example.vendor=Acme com.example.license=GPL com.example.version=1.0"
|
|||
|
]
|
|||
|
},
|
|||
|
"DockerVersion" : "1.9.0-dev",
|
|||
|
"VirtualSize" : 188359297,
|
|||
|
"Size" : 0,
|
|||
|
"Author" : "",
|
|||
|
"Created" : "2015-09-10T08:30:53.26995814Z",
|
|||
|
"GraphDriver" : {
|
|||
|
"Name" : "aufs",
|
|||
|
"Data" : null
|
|||
|
},
|
|||
|
"RepoDigests" : [
|
|||
|
"localhost:5000/test/busybox/example@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf"
|
|||
|
],
|
|||
|
"RepoTags" : [
|
|||
|
"example:1.0",
|
|||
|
"example:latest",
|
|||
|
"example:stable"
|
|||
|
],
|
|||
|
"Config" : {
|
|||
|
"Image" : "91e54dfb11794fad694460162bf0cb0a4fa710cfa3f60979c177d920813e267c",
|
|||
|
"NetworkDisabled" : false,
|
|||
|
"OnBuild" : [],
|
|||
|
"StdinOnce" : false,
|
|||
|
"PublishService" : "",
|
|||
|
"AttachStdin" : false,
|
|||
|
"OpenStdin" : false,
|
|||
|
"Domainname" : "",
|
|||
|
"AttachStdout" : false,
|
|||
|
"Tty" : false,
|
|||
|
"Hostname" : "e611e15f9c9d",
|
|||
|
"Volumes" : null,
|
|||
|
"Cmd" : [
|
|||
|
"/bin/bash"
|
|||
|
],
|
|||
|
"ExposedPorts" : null,
|
|||
|
"Env" : [
|
|||
|
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
|
|||
|
],
|
|||
|
"Labels" : {
|
|||
|
"com.example.vendor" : "Acme",
|
|||
|
"com.example.version" : "1.0",
|
|||
|
"com.example.license" : "GPL"
|
|||
|
},
|
|||
|
"Entrypoint" : null,
|
|||
|
"MacAddress" : "",
|
|||
|
"AttachStderr" : false,
|
|||
|
"WorkingDir" : "",
|
|||
|
"User" : ""
|
|||
|
}
|
|||
|
}
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **200** – no error
|
|||
|
- **404** – no such image
|
|||
|
- **500** – server error
|
|||
|
|
|||
|
#### Get the history of an image
|
|||
|
|
|||
|
`GET /images/(name)/history`
|
|||
|
|
|||
|
Return the history of the image `name`
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
GET /v1.22/images/ubuntu/history HTTP/1.1
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 200 OK
|
|||
|
Content-Type: application/json
|
|||
|
|
|||
|
[
|
|||
|
{
|
|||
|
"Id": "3db9c44f45209632d6050b35958829c3a2aa256d81b9a7be45b362ff85c54710",
|
|||
|
"Created": 1398108230,
|
|||
|
"CreatedBy": "/bin/sh -c #(nop) ADD file:eb15dbd63394e063b805a3c32ca7bf0266ef64676d5a6fab4801f2e81e2a5148 in /",
|
|||
|
"Tags": [
|
|||
|
"ubuntu:lucid",
|
|||
|
"ubuntu:10.04"
|
|||
|
],
|
|||
|
"Size": 182964289,
|
|||
|
"Comment": ""
|
|||
|
},
|
|||
|
{
|
|||
|
"Id": "6cfa4d1f33fb861d4d114f43b25abd0ac737509268065cdfd69d544a59c85ab8",
|
|||
|
"Created": 1398108222,
|
|||
|
"CreatedBy": "/bin/sh -c #(nop) MAINTAINER Tianon Gravi <admwiggin@gmail.com> - mkimage-debootstrap.sh -i iproute,iputils-ping,ubuntu-minimal -t lucid.tar.xz lucid http://archive.ubuntu.com/ubuntu/",
|
|||
|
"Tags": null,
|
|||
|
"Size": 0,
|
|||
|
"Comment": ""
|
|||
|
},
|
|||
|
{
|
|||
|
"Id": "511136ea3c5a64f264b78b5433614aec563103b4d4702f3ba7d4d2698e22c158",
|
|||
|
"Created": 1371157430,
|
|||
|
"CreatedBy": "",
|
|||
|
"Tags": [
|
|||
|
"scratch12:latest",
|
|||
|
"scratch:latest"
|
|||
|
],
|
|||
|
"Size": 0,
|
|||
|
"Comment": "Imported from -"
|
|||
|
}
|
|||
|
]
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **200** – no error
|
|||
|
- **404** – no such image
|
|||
|
- **500** – server error
|
|||
|
|
|||
|
#### Push an image on the registry
|
|||
|
|
|||
|
`POST /images/(name)/push`
|
|||
|
|
|||
|
Push the image `name` on the registry
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
POST /v1.22/images/test/push HTTP/1.1
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 200 OK
|
|||
|
Content-Type: application/json
|
|||
|
|
|||
|
{"status": "Pushing..."}
|
|||
|
{"status": "Pushing", "progress": "1/? (n/a)", "progressDetail": {"current": 1}}}
|
|||
|
{"error": "Invalid..."}
|
|||
|
...
|
|||
|
|
|||
|
If you wish to push an image on to a private registry, that image must already have a tag
|
|||
|
into a repository which references that registry `hostname` and `port`. This repository name should
|
|||
|
then be used in the URL. This duplicates the command line's flow.
|
|||
|
|
|||
|
The push is cancelled if the HTTP connection is closed.
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
POST /v1.22/images/registry.acme.com:5000/test/push HTTP/1.1
|
|||
|
|
|||
|
|
|||
|
**Query parameters**:
|
|||
|
|
|||
|
- **tag** – The tag to associate with the image on the registry. This is optional.
|
|||
|
|
|||
|
**Request Headers**:
|
|||
|
|
|||
|
- **X-Registry-Auth** – base64-encoded AuthConfig object, containing either login information, or a token
|
|||
|
- Credential based login:
|
|||
|
|
|||
|
```
|
|||
|
{
|
|||
|
"username": "jdoe",
|
|||
|
"password": "secret",
|
|||
|
"email": "jdoe@acme.com",
|
|||
|
}
|
|||
|
```
|
|||
|
|
|||
|
- Token based login:
|
|||
|
|
|||
|
```
|
|||
|
{
|
|||
|
"registrytoken": "9cbaf023786cd7..."
|
|||
|
}
|
|||
|
```
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **200** – no error
|
|||
|
- **404** – no such image
|
|||
|
- **500** – server error
|
|||
|
|
|||
|
#### Tag an image into a repository
|
|||
|
|
|||
|
`POST /images/(name)/tag`
|
|||
|
|
|||
|
Tag the image `name` into a repository
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
POST /v1.22/images/test/tag?repo=myrepo&force=0&tag=v42 HTTP/1.1
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 201 Created
|
|||
|
|
|||
|
**Query parameters**:
|
|||
|
|
|||
|
- **repo** – The repository to tag in
|
|||
|
- **force** – 1/True/true or 0/False/false, default false
|
|||
|
- **tag** - The new tag name
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **201** – no error
|
|||
|
- **400** – bad parameter
|
|||
|
- **404** – no such image
|
|||
|
- **409** – conflict
|
|||
|
- **500** – server error
|
|||
|
|
|||
|
#### Remove an image
|
|||
|
|
|||
|
`DELETE /images/(name)`
|
|||
|
|
|||
|
Remove the image `name` from the filesystem
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
DELETE /v1.22/images/test HTTP/1.1
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 200 OK
|
|||
|
Content-type: application/json
|
|||
|
|
|||
|
[
|
|||
|
{"Untagged": "3e2f21a89f"},
|
|||
|
{"Deleted": "3e2f21a89f"},
|
|||
|
{"Deleted": "53b4f83ac9"}
|
|||
|
]
|
|||
|
|
|||
|
**Query parameters**:
|
|||
|
|
|||
|
- **force** – 1/True/true or 0/False/false, default false
|
|||
|
- **noprune** – 1/True/true or 0/False/false, default false
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **200** – no error
|
|||
|
- **404** – no such image
|
|||
|
- **409** – conflict
|
|||
|
- **500** – server error
|
|||
|
|
|||
|
#### Search images
|
|||
|
|
|||
|
`GET /images/search`
|
|||
|
|
|||
|
Search for an image on [Docker Hub](https://hub.docker.com).
|
|||
|
|
|||
|
> **Note**:
|
|||
|
> The response keys have changed from API v1.6 to reflect the JSON
|
|||
|
> sent by the registry server to the docker daemon's request.
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
GET /v1.22/images/search?term=sshd HTTP/1.1
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 200 OK
|
|||
|
Content-Type: application/json
|
|||
|
|
|||
|
[
|
|||
|
{
|
|||
|
"description": "",
|
|||
|
"is_official": false,
|
|||
|
"is_automated": false,
|
|||
|
"name": "wma55/u1210sshd",
|
|||
|
"star_count": 0
|
|||
|
},
|
|||
|
{
|
|||
|
"description": "",
|
|||
|
"is_official": false,
|
|||
|
"is_automated": false,
|
|||
|
"name": "jdswinbank/sshd",
|
|||
|
"star_count": 0
|
|||
|
},
|
|||
|
{
|
|||
|
"description": "",
|
|||
|
"is_official": false,
|
|||
|
"is_automated": false,
|
|||
|
"name": "vgauthier/sshd",
|
|||
|
"star_count": 0
|
|||
|
}
|
|||
|
...
|
|||
|
]
|
|||
|
|
|||
|
**Query parameters**:
|
|||
|
|
|||
|
- **term** – term to search
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **200** – no error
|
|||
|
- **500** – server error
|
|||
|
|
|||
|
### 2.3 Misc
|
|||
|
|
|||
|
#### Check auth configuration
|
|||
|
|
|||
|
`POST /auth`
|
|||
|
|
|||
|
Get the default username and email
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
POST /v1.22/auth HTTP/1.1
|
|||
|
Content-Type: application/json
|
|||
|
Content-Length: 12345
|
|||
|
|
|||
|
{
|
|||
|
"username": "hannibal",
|
|||
|
"password": "xxxx",
|
|||
|
"email": "hannibal@a-team.com",
|
|||
|
"serveraddress": "https://index.docker.io/v1/"
|
|||
|
}
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 200 OK
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **200** – no error
|
|||
|
- **204** – no error
|
|||
|
- **500** – server error
|
|||
|
|
|||
|
#### Display system-wide information
|
|||
|
|
|||
|
`GET /info`
|
|||
|
|
|||
|
Display system-wide information
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
GET /v1.22/info HTTP/1.1
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 200 OK
|
|||
|
Content-Type: application/json
|
|||
|
|
|||
|
{
|
|||
|
"Architecture": "x86_64",
|
|||
|
"ClusterStore": "etcd://localhost:2379",
|
|||
|
"Containers": 11,
|
|||
|
"ContainersRunning": 7,
|
|||
|
"ContainersStopped": 3,
|
|||
|
"ContainersPaused": 1,
|
|||
|
"CpuCfsPeriod": true,
|
|||
|
"CpuCfsQuota": true,
|
|||
|
"Debug": false,
|
|||
|
"DockerRootDir": "/var/lib/docker",
|
|||
|
"Driver": "btrfs",
|
|||
|
"DriverStatus": [[""]],
|
|||
|
"ExecutionDriver": "native-0.1",
|
|||
|
"ExperimentalBuild": false,
|
|||
|
"HttpProxy": "http://test:test@localhost:8080",
|
|||
|
"HttpsProxy": "https://test:test@localhost:8080",
|
|||
|
"ID": "7TRN:IPZB:QYBB:VPBQ:UMPP:KARE:6ZNR:XE6T:7EWV:PKF4:ZOJD:TPYS",
|
|||
|
"IPv4Forwarding": true,
|
|||
|
"Images": 16,
|
|||
|
"IndexServerAddress": "https://index.docker.io/v1/",
|
|||
|
"InitPath": "/usr/bin/docker",
|
|||
|
"InitSha1": "",
|
|||
|
"KernelVersion": "3.12.0-1-amd64",
|
|||
|
"Labels": [
|
|||
|
"storage=ssd"
|
|||
|
],
|
|||
|
"MemTotal": 2099236864,
|
|||
|
"MemoryLimit": true,
|
|||
|
"NCPU": 1,
|
|||
|
"NEventsListener": 0,
|
|||
|
"NFd": 11,
|
|||
|
"NGoroutines": 21,
|
|||
|
"Name": "prod-server-42",
|
|||
|
"NoProxy": "9.81.1.160",
|
|||
|
"OomKillDisable": true,
|
|||
|
"OSType": "linux",
|
|||
|
"OperatingSystem": "Boot2Docker",
|
|||
|
"Plugins": {
|
|||
|
"Volume": [
|
|||
|
"local"
|
|||
|
],
|
|||
|
"Network": [
|
|||
|
"null",
|
|||
|
"host",
|
|||
|
"bridge"
|
|||
|
]
|
|||
|
},
|
|||
|
"RegistryConfig": {
|
|||
|
"IndexConfigs": {
|
|||
|
"docker.io": {
|
|||
|
"Mirrors": null,
|
|||
|
"Name": "docker.io",
|
|||
|
"Official": true,
|
|||
|
"Secure": true
|
|||
|
}
|
|||
|
},
|
|||
|
"InsecureRegistryCIDRs": [
|
|||
|
"127.0.0.0/8"
|
|||
|
]
|
|||
|
},
|
|||
|
"ServerVersion": "1.9.0",
|
|||
|
"SwapLimit": false,
|
|||
|
"SystemStatus": [["State", "Healthy"]],
|
|||
|
"SystemTime": "2015-03-10T11:11:23.730591467-07:00"
|
|||
|
}
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **200** – no error
|
|||
|
- **500** – server error
|
|||
|
|
|||
|
#### Show the docker version information
|
|||
|
|
|||
|
`GET /version`
|
|||
|
|
|||
|
Show the docker version information
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
GET /v1.22/version HTTP/1.1
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 200 OK
|
|||
|
Content-Type: application/json
|
|||
|
|
|||
|
{
|
|||
|
"Version": "1.10.0",
|
|||
|
"Os": "linux",
|
|||
|
"KernelVersion": "3.19.0-23-generic",
|
|||
|
"GoVersion": "go1.4.2",
|
|||
|
"GitCommit": "e75da4b",
|
|||
|
"Arch": "amd64",
|
|||
|
"ApiVersion": "1.22",
|
|||
|
"BuildTime": "2015-12-01T07:09:13.444803460+00:00",
|
|||
|
"Experimental": true
|
|||
|
}
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **200** – no error
|
|||
|
- **500** – server error
|
|||
|
|
|||
|
#### Ping the docker server
|
|||
|
|
|||
|
`GET /_ping`
|
|||
|
|
|||
|
Ping the docker server
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
GET /v1.22/_ping HTTP/1.1
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 200 OK
|
|||
|
Content-Type: text/plain
|
|||
|
|
|||
|
OK
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **200** - no error
|
|||
|
- **500** - server error
|
|||
|
|
|||
|
#### Create a new image from a container's changes
|
|||
|
|
|||
|
`POST /commit`
|
|||
|
|
|||
|
Create a new image from a container's changes
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
POST /v1.22/commit?container=44c004db4b17&comment=message&repo=myrepo HTTP/1.1
|
|||
|
Content-Type: application/json
|
|||
|
Content-Length: 12345
|
|||
|
|
|||
|
{
|
|||
|
"Hostname": "",
|
|||
|
"Domainname": "",
|
|||
|
"User": "",
|
|||
|
"AttachStdin": false,
|
|||
|
"AttachStdout": true,
|
|||
|
"AttachStderr": true,
|
|||
|
"Tty": false,
|
|||
|
"OpenStdin": false,
|
|||
|
"StdinOnce": false,
|
|||
|
"Env": null,
|
|||
|
"Cmd": [
|
|||
|
"date"
|
|||
|
],
|
|||
|
"Mounts": [
|
|||
|
{
|
|||
|
"Source": "/data",
|
|||
|
"Destination": "/data",
|
|||
|
"Mode": "ro,Z",
|
|||
|
"RW": false
|
|||
|
}
|
|||
|
],
|
|||
|
"Labels": {
|
|||
|
"key1": "value1",
|
|||
|
"key2": "value2"
|
|||
|
},
|
|||
|
"WorkingDir": "",
|
|||
|
"NetworkDisabled": false,
|
|||
|
"ExposedPorts": {
|
|||
|
"22/tcp": {}
|
|||
|
}
|
|||
|
}
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 201 Created
|
|||
|
Content-Type: application/json
|
|||
|
|
|||
|
{"Id": "596069db4bf5"}
|
|||
|
|
|||
|
**JSON parameters**:
|
|||
|
|
|||
|
- **config** - the container's configuration
|
|||
|
|
|||
|
**Query parameters**:
|
|||
|
|
|||
|
- **container** – source container
|
|||
|
- **repo** – repository
|
|||
|
- **tag** – tag
|
|||
|
- **comment** – commit message
|
|||
|
- **author** – author (e.g., "John Hannibal Smith
|
|||
|
<[hannibal@a-team.com](mailto:hannibal%40a-team.com)>")
|
|||
|
- **pause** – 1/True/true or 0/False/false, whether to pause the container before committing
|
|||
|
- **changes** – Dockerfile instructions to apply while committing
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **201** – no error
|
|||
|
- **404** – no such container
|
|||
|
- **500** – server error
|
|||
|
|
|||
|
#### Monitor Docker's events
|
|||
|
|
|||
|
`GET /events`
|
|||
|
|
|||
|
Get container events from docker, in real time via streaming.
|
|||
|
|
|||
|
Docker containers report the following events:
|
|||
|
|
|||
|
attach, commit, copy, create, destroy, die, exec_create, exec_start, export, kill, oom, pause, rename, resize, restart, start, stop, top, unpause, update
|
|||
|
|
|||
|
Docker images report the following events:
|
|||
|
|
|||
|
delete, import, pull, push, tag, untag
|
|||
|
|
|||
|
Docker volumes report the following events:
|
|||
|
|
|||
|
create, mount, unmount, destroy
|
|||
|
|
|||
|
Docker networks report the following events:
|
|||
|
|
|||
|
create, connect, disconnect, destroy
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
GET /v1.22/events?since=1374067924
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 200 OK
|
|||
|
Content-Type: application/json
|
|||
|
Server: Docker/1.10.0 (linux)
|
|||
|
Date: Fri, 29 Apr 2016 15:18:06 GMT
|
|||
|
Transfer-Encoding: chunked
|
|||
|
|
|||
|
{
|
|||
|
"status": "pull",
|
|||
|
"id": "alpine:latest",
|
|||
|
"Type": "image",
|
|||
|
"Action": "pull",
|
|||
|
"Actor": {
|
|||
|
"ID": "alpine:latest",
|
|||
|
"Attributes": {
|
|||
|
"name": "alpine"
|
|||
|
}
|
|||
|
},
|
|||
|
"time": 1461943101,
|
|||
|
"timeNano": 1461943101301854122
|
|||
|
}
|
|||
|
{
|
|||
|
"status": "create",
|
|||
|
"id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
|
|||
|
"from": "alpine",
|
|||
|
"Type": "container",
|
|||
|
"Action": "create",
|
|||
|
"Actor": {
|
|||
|
"ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
|
|||
|
"Attributes": {
|
|||
|
"com.example.some-label": "some-label-value",
|
|||
|
"image": "alpine",
|
|||
|
"name": "my-container"
|
|||
|
}
|
|||
|
},
|
|||
|
"time": 1461943101,
|
|||
|
"timeNano": 1461943101381709551
|
|||
|
}
|
|||
|
{
|
|||
|
"status": "attach",
|
|||
|
"id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
|
|||
|
"from": "alpine",
|
|||
|
"Type": "container",
|
|||
|
"Action": "attach",
|
|||
|
"Actor": {
|
|||
|
"ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
|
|||
|
"Attributes": {
|
|||
|
"com.example.some-label": "some-label-value",
|
|||
|
"image": "alpine",
|
|||
|
"name": "my-container"
|
|||
|
}
|
|||
|
},
|
|||
|
"time": 1461943101,
|
|||
|
"timeNano": 1461943101383858412
|
|||
|
}
|
|||
|
{
|
|||
|
"Type": "network",
|
|||
|
"Action": "connect",
|
|||
|
"Actor": {
|
|||
|
"ID": "7dc8ac97d5d29ef6c31b6052f3938c1e8f2749abbd17d1bd1febf2608db1b474",
|
|||
|
"Attributes": {
|
|||
|
"container": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
|
|||
|
"name": "bridge",
|
|||
|
"type": "bridge"
|
|||
|
}
|
|||
|
},
|
|||
|
"time": 1461943101,
|
|||
|
"timeNano": 1461943101394865557
|
|||
|
}
|
|||
|
{
|
|||
|
"status": "start",
|
|||
|
"id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
|
|||
|
"from": "alpine",
|
|||
|
"Type": "container",
|
|||
|
"Action": "start",
|
|||
|
"Actor": {
|
|||
|
"ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
|
|||
|
"Attributes": {
|
|||
|
"com.example.some-label": "some-label-value",
|
|||
|
"image": "alpine",
|
|||
|
"name": "my-container"
|
|||
|
}
|
|||
|
},
|
|||
|
"time": 1461943101,
|
|||
|
"timeNano": 1461943101607533796
|
|||
|
}
|
|||
|
{
|
|||
|
"status": "resize",
|
|||
|
"id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
|
|||
|
"from": "alpine",
|
|||
|
"Type": "container",
|
|||
|
"Action": "resize",
|
|||
|
"Actor": {
|
|||
|
"ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
|
|||
|
"Attributes": {
|
|||
|
"com.example.some-label": "some-label-value",
|
|||
|
"height": "46",
|
|||
|
"image": "alpine",
|
|||
|
"name": "my-container",
|
|||
|
"width": "204"
|
|||
|
}
|
|||
|
},
|
|||
|
"time": 1461943101,
|
|||
|
"timeNano": 1461943101610269268
|
|||
|
}
|
|||
|
{
|
|||
|
"status": "die",
|
|||
|
"id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
|
|||
|
"from": "alpine",
|
|||
|
"Type": "container",
|
|||
|
"Action": "die",
|
|||
|
"Actor": {
|
|||
|
"ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
|
|||
|
"Attributes": {
|
|||
|
"com.example.some-label": "some-label-value",
|
|||
|
"exitCode": "0",
|
|||
|
"image": "alpine",
|
|||
|
"name": "my-container"
|
|||
|
}
|
|||
|
},
|
|||
|
"time": 1461943105,
|
|||
|
"timeNano": 1461943105079144137
|
|||
|
}
|
|||
|
{
|
|||
|
"Type": "network",
|
|||
|
"Action": "disconnect",
|
|||
|
"Actor": {
|
|||
|
"ID": "7dc8ac97d5d29ef6c31b6052f3938c1e8f2749abbd17d1bd1febf2608db1b474",
|
|||
|
"Attributes": {
|
|||
|
"container": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
|
|||
|
"name": "bridge",
|
|||
|
"type": "bridge"
|
|||
|
}
|
|||
|
},
|
|||
|
"time": 1461943105,
|
|||
|
"timeNano": 1461943105230860245
|
|||
|
}
|
|||
|
{
|
|||
|
"status": "destroy",
|
|||
|
"id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
|
|||
|
"from": "alpine",
|
|||
|
"Type": "container",
|
|||
|
"Action": "destroy",
|
|||
|
"Actor": {
|
|||
|
"ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
|
|||
|
"Attributes": {
|
|||
|
"com.example.some-label": "some-label-value",
|
|||
|
"image": "alpine",
|
|||
|
"name": "my-container"
|
|||
|
}
|
|||
|
},
|
|||
|
"time": 1461943105,
|
|||
|
"timeNano": 1461943105338056026
|
|||
|
}
|
|||
|
|
|||
|
**Query parameters**:
|
|||
|
|
|||
|
- **since** – Timestamp. Show all events created since timestamp and then stream
|
|||
|
- **until** – Timestamp. Show events created until given timestamp and stop streaming
|
|||
|
- **filters** – A json encoded value of the filters (a map[string][]string) to process on the event list. Available filters:
|
|||
|
- `container=<string>`; -- container to filter
|
|||
|
- `event=<string>`; -- event to filter
|
|||
|
- `image=<string>`; -- image to filter
|
|||
|
- `label=<string>`; -- image and container label to filter
|
|||
|
- `type=<string>`; -- either `container` or `image` or `volume` or `network`
|
|||
|
- `volume=<string>`; -- volume to filter
|
|||
|
- `network=<string>`; -- network to filter
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **200** – no error
|
|||
|
- **500** – server error
|
|||
|
|
|||
|
#### Get a tarball containing all images in a repository
|
|||
|
|
|||
|
`GET /images/(name)/get`
|
|||
|
|
|||
|
Get a tarball containing all images and metadata for the repository specified
|
|||
|
by `name`.
|
|||
|
|
|||
|
If `name` is a specific name and tag (e.g. ubuntu:latest), then only that image
|
|||
|
(and its parents) are returned. If `name` is an image ID, similarly only that
|
|||
|
image (and its parents) are returned, but with the exclusion of the
|
|||
|
'repositories' file in the tarball, as there were no image names referenced.
|
|||
|
|
|||
|
See the [image tarball format](#image-tarball-format) for more details.
|
|||
|
|
|||
|
**Example request**
|
|||
|
|
|||
|
GET /v1.22/images/ubuntu/get
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 200 OK
|
|||
|
Content-Type: application/x-tar
|
|||
|
|
|||
|
Binary data stream
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **200** – no error
|
|||
|
- **500** – server error
|
|||
|
|
|||
|
#### Get a tarball containing all images
|
|||
|
|
|||
|
`GET /images/get`
|
|||
|
|
|||
|
Get a tarball containing all images and metadata for one or more repositories.
|
|||
|
|
|||
|
For each value of the `names` parameter: if it is a specific name and tag (e.g.
|
|||
|
`ubuntu:latest`), then only that image (and its parents) are returned; if it is
|
|||
|
an image ID, similarly only that image (and its parents) are returned and there
|
|||
|
would be no names referenced in the 'repositories' file for this image ID.
|
|||
|
|
|||
|
See the [image tarball format](#image-tarball-format) for more details.
|
|||
|
|
|||
|
**Example request**
|
|||
|
|
|||
|
GET /v1.22/images/get?names=myname%2Fmyapp%3Alatest&names=busybox
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 200 OK
|
|||
|
Content-Type: application/x-tar
|
|||
|
|
|||
|
Binary data stream
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **200** – no error
|
|||
|
- **500** – server error
|
|||
|
|
|||
|
#### Load a tarball with a set of images and tags into docker
|
|||
|
|
|||
|
`POST /images/load`
|
|||
|
|
|||
|
Load a set of images and tags into a Docker repository.
|
|||
|
See the [image tarball format](#image-tarball-format) for more details.
|
|||
|
|
|||
|
**Example request**
|
|||
|
|
|||
|
POST /v1.22/images/load
|
|||
|
Content-Type: application/x-tar
|
|||
|
Content-Length: 12345
|
|||
|
|
|||
|
Tarball in body
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 200 OK
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **200** – no error
|
|||
|
- **500** – server error
|
|||
|
|
|||
|
#### Image tarball format
|
|||
|
|
|||
|
An image tarball contains one directory per image layer (named using its long ID),
|
|||
|
each containing these files:
|
|||
|
|
|||
|
- `VERSION`: currently `1.0` - the file format version
|
|||
|
- `json`: detailed layer information, similar to `docker inspect layer_id`
|
|||
|
- `layer.tar`: A tarfile containing the filesystem changes in this layer
|
|||
|
|
|||
|
The `layer.tar` file contains `aufs` style `.wh..wh.aufs` files and directories
|
|||
|
for storing attribute changes and deletions.
|
|||
|
|
|||
|
If the tarball defines a repository, the tarball should also include a `repositories` file at
|
|||
|
the root that contains a list of repository and tag names mapped to layer IDs.
|
|||
|
|
|||
|
```
|
|||
|
{"hello-world":
|
|||
|
{"latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"}
|
|||
|
}
|
|||
|
```
|
|||
|
|
|||
|
#### Exec Create
|
|||
|
|
|||
|
`POST /containers/(id or name)/exec`
|
|||
|
|
|||
|
Sets up an exec instance in a running container `id`
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
POST /v1.22/containers/e90e34656806/exec HTTP/1.1
|
|||
|
Content-Type: application/json
|
|||
|
Content-Length: 12345
|
|||
|
|
|||
|
{
|
|||
|
"AttachStdin": true,
|
|||
|
"AttachStdout": true,
|
|||
|
"AttachStderr": true,
|
|||
|
"Cmd": ["sh"],
|
|||
|
"DetachKeys": "ctrl-p,ctrl-q",
|
|||
|
"Privileged": true,
|
|||
|
"Tty": true,
|
|||
|
"User": "123:456"
|
|||
|
}
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 201 Created
|
|||
|
Content-Type: application/json
|
|||
|
|
|||
|
{
|
|||
|
"Id": "f90e34656806",
|
|||
|
"Warnings":[]
|
|||
|
}
|
|||
|
|
|||
|
**JSON parameters**:
|
|||
|
|
|||
|
- **AttachStdin** - Boolean value, attaches to `stdin` of the `exec` command.
|
|||
|
- **AttachStdout** - Boolean value, attaches to `stdout` of the `exec` command.
|
|||
|
- **AttachStderr** - Boolean value, attaches to `stderr` of the `exec` command.
|
|||
|
- **DetachKeys** – Override the key sequence for detaching a
|
|||
|
container. Format is a single character `[a-Z]` or `ctrl-<value>`
|
|||
|
where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`.
|
|||
|
- **Tty** - Boolean value to allocate a pseudo-TTY.
|
|||
|
- **Cmd** - Command to run specified as a string or an array of strings.
|
|||
|
- **Privileged** - Boolean value, runs the exec process with extended privileges.
|
|||
|
- **User** - A string value specifying the user, and optionally, group to run
|
|||
|
the exec process inside the container. Format is one of: `"user"`,
|
|||
|
`"user:group"`, `"uid"`, or `"uid:gid"`.
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **201** – no error
|
|||
|
- **404** – no such container
|
|||
|
- **409** - container is paused
|
|||
|
- **500** - server error
|
|||
|
|
|||
|
#### Exec Start
|
|||
|
|
|||
|
`POST /exec/(id)/start`
|
|||
|
|
|||
|
Starts a previously set up `exec` instance `id`. If `detach` is true, this API
|
|||
|
returns after starting the `exec` command. Otherwise, this API sets up an
|
|||
|
interactive session with the `exec` command.
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
POST /v1.22/exec/e90e34656806/start HTTP/1.1
|
|||
|
Content-Type: application/json
|
|||
|
Content-Length: 12345
|
|||
|
|
|||
|
{
|
|||
|
"Detach": false,
|
|||
|
"Tty": false
|
|||
|
}
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 200 OK
|
|||
|
Content-Type: application/vnd.docker.raw-stream
|
|||
|
|
|||
|
{% raw %}
|
|||
|
{{ STREAM }}
|
|||
|
{% endraw %}
|
|||
|
|
|||
|
**JSON parameters**:
|
|||
|
|
|||
|
- **Detach** - Detach from the `exec` command.
|
|||
|
- **Tty** - Boolean value to allocate a pseudo-TTY.
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **200** – no error
|
|||
|
- **404** – no such exec instance
|
|||
|
- **409** - container is paused
|
|||
|
|
|||
|
**Stream details**:
|
|||
|
|
|||
|
Similar to the stream behavior of `POST /containers/(id or name)/attach` API
|
|||
|
|
|||
|
#### Exec Resize
|
|||
|
|
|||
|
`POST /exec/(id)/resize`
|
|||
|
|
|||
|
Resizes the `tty` session used by the `exec` command `id`. The unit is number of characters.
|
|||
|
This API is valid only if `tty` was specified as part of creating and starting the `exec` command.
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
POST /v1.22/exec/e90e34656806/resize?h=40&w=80 HTTP/1.1
|
|||
|
Content-Type: text/plain
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 201 Created
|
|||
|
Content-Type: text/plain
|
|||
|
|
|||
|
**Query parameters**:
|
|||
|
|
|||
|
- **h** – height of `tty` session
|
|||
|
- **w** – width
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **201** – no error
|
|||
|
- **404** – no such exec instance
|
|||
|
|
|||
|
#### Exec Inspect
|
|||
|
|
|||
|
`GET /exec/(id)/json`
|
|||
|
|
|||
|
Return low-level information about the `exec` command `id`.
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
GET /v1.22/exec/11fb006128e8ceb3942e7c58d77750f24210e35f879dd204ac975c184b820b39/json HTTP/1.1
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 200 OK
|
|||
|
Content-Type: application/json
|
|||
|
|
|||
|
{
|
|||
|
"CanRemove": false,
|
|||
|
"ContainerID": "b53ee82b53a40c7dca428523e34f741f3abc51d9f297a14ff874bf761b995126",
|
|||
|
"DetachKeys": "",
|
|||
|
"ExitCode": 2,
|
|||
|
"ID": "f33bbfb39f5b142420f4759b2348913bd4a8d1a6d7fd56499cb41a1bb91d7b3b",
|
|||
|
"OpenStderr": true,
|
|||
|
"OpenStdin": true,
|
|||
|
"OpenStdout": true,
|
|||
|
"ProcessConfig": {
|
|||
|
"arguments": [
|
|||
|
"-c",
|
|||
|
"exit 2"
|
|||
|
],
|
|||
|
"entrypoint": "sh",
|
|||
|
"privileged": false,
|
|||
|
"tty": true,
|
|||
|
"user": "1000"
|
|||
|
},
|
|||
|
"Running": false
|
|||
|
}
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **200** – no error
|
|||
|
- **404** – no such exec instance
|
|||
|
- **500** - server error
|
|||
|
|
|||
|
### 2.4 Volumes
|
|||
|
|
|||
|
#### List volumes
|
|||
|
|
|||
|
`GET /volumes`
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
GET /v1.22/volumes HTTP/1.1
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 200 OK
|
|||
|
Content-Type: application/json
|
|||
|
|
|||
|
{
|
|||
|
"Volumes": [
|
|||
|
{
|
|||
|
"Name": "tardis",
|
|||
|
"Driver": "local",
|
|||
|
"Mountpoint": "/var/lib/docker/volumes/tardis"
|
|||
|
}
|
|||
|
],
|
|||
|
"Warnings": []
|
|||
|
}
|
|||
|
|
|||
|
**Query parameters**:
|
|||
|
|
|||
|
- **filters** - JSON encoded value of the filters (a `map[string][]string`) to process on the volumes list. There is one available filter: `dangling=true`
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **200** - no error
|
|||
|
- **500** - server error
|
|||
|
|
|||
|
#### Create a volume
|
|||
|
|
|||
|
`POST /volumes/create`
|
|||
|
|
|||
|
Create a volume
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
POST /v1.22/volumes/create HTTP/1.1
|
|||
|
Content-Type: application/json
|
|||
|
Content-Length: 12345
|
|||
|
|
|||
|
{
|
|||
|
"Name": "tardis"
|
|||
|
}
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 201 Created
|
|||
|
Content-Type: application/json
|
|||
|
|
|||
|
{
|
|||
|
"Name": "tardis",
|
|||
|
"Driver": "local",
|
|||
|
"Mountpoint": "/var/lib/docker/volumes/tardis"
|
|||
|
}
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **201** - no error
|
|||
|
- **500** - server error
|
|||
|
|
|||
|
**JSON parameters**:
|
|||
|
|
|||
|
- **Name** - The new volume's name. If not specified, Docker generates a name.
|
|||
|
- **Driver** - Name of the volume driver to use. Defaults to `local` for the name.
|
|||
|
- **DriverOpts** - A mapping of driver options and values. These options are
|
|||
|
passed directly to the driver and are driver specific.
|
|||
|
|
|||
|
#### Inspect a volume
|
|||
|
|
|||
|
`GET /volumes/(name)`
|
|||
|
|
|||
|
Return low-level information on the volume `name`
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
GET /volumes/tardis
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 200 OK
|
|||
|
Content-Type: application/json
|
|||
|
|
|||
|
{
|
|||
|
"Name": "tardis",
|
|||
|
"Driver": "local",
|
|||
|
"Mountpoint": "/var/lib/docker/volumes/tardis"
|
|||
|
}
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **200** - no error
|
|||
|
- **404** - no such volume
|
|||
|
- **500** - server error
|
|||
|
|
|||
|
#### Remove a volume
|
|||
|
|
|||
|
`DELETE /volumes/(name)`
|
|||
|
|
|||
|
Instruct the driver to remove the volume (`name`).
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
DELETE /v1.22/volumes/tardis HTTP/1.1
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 204 No Content
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **204** - no error
|
|||
|
- **404** - no such volume or volume driver
|
|||
|
- **409** - volume is in use and cannot be removed
|
|||
|
- **500** - server error
|
|||
|
|
|||
|
### 2.5 Networks
|
|||
|
|
|||
|
#### List networks
|
|||
|
|
|||
|
`GET /networks`
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
GET /v1.22/networks?filters={"type":{"custom":true}} HTTP/1.1
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
```
|
|||
|
HTTP/1.1 200 OK
|
|||
|
Content-Type: application/json
|
|||
|
|
|||
|
[
|
|||
|
{
|
|||
|
"Name": "bridge",
|
|||
|
"Id": "f2de39df4171b0dc801e8002d1d999b77256983dfc63041c0f34030aa3977566",
|
|||
|
"Scope": "local",
|
|||
|
"Driver": "bridge",
|
|||
|
"IPAM": {
|
|||
|
"Driver": "default",
|
|||
|
"Config": [
|
|||
|
{
|
|||
|
"Subnet": "172.17.0.0/16"
|
|||
|
}
|
|||
|
]
|
|||
|
},
|
|||
|
"Containers": {
|
|||
|
"39b69226f9d79f5634485fb236a23b2fe4e96a0a94128390a7fbbcc167065867": {
|
|||
|
"EndpointID": "ed2419a97c1d9954d05b46e462e7002ea552f216e9b136b80a7db8d98b442eda",
|
|||
|
"MacAddress": "02:42:ac:11:00:02",
|
|||
|
"IPv4Address": "172.17.0.2/16",
|
|||
|
"IPv6Address": ""
|
|||
|
}
|
|||
|
},
|
|||
|
"Options": {
|
|||
|
"com.docker.network.bridge.default_bridge": "true",
|
|||
|
"com.docker.network.bridge.enable_icc": "true",
|
|||
|
"com.docker.network.bridge.enable_ip_masquerade": "true",
|
|||
|
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
|
|||
|
"com.docker.network.bridge.name": "docker0",
|
|||
|
"com.docker.network.driver.mtu": "1500"
|
|||
|
}
|
|||
|
},
|
|||
|
{
|
|||
|
"Name": "none",
|
|||
|
"Id": "e086a3893b05ab69242d3c44e49483a3bbbd3a26b46baa8f61ab797c1088d794",
|
|||
|
"Scope": "local",
|
|||
|
"Driver": "null",
|
|||
|
"IPAM": {
|
|||
|
"Driver": "default",
|
|||
|
"Config": []
|
|||
|
},
|
|||
|
"Containers": {},
|
|||
|
"Options": {}
|
|||
|
},
|
|||
|
{
|
|||
|
"Name": "host",
|
|||
|
"Id": "13e871235c677f196c4e1ecebb9dc733b9b2d2ab589e30c539efeda84a24215e",
|
|||
|
"Scope": "local",
|
|||
|
"Driver": "host",
|
|||
|
"IPAM": {
|
|||
|
"Driver": "default",
|
|||
|
"Config": []
|
|||
|
},
|
|||
|
"Containers": {},
|
|||
|
"Options": {}
|
|||
|
}
|
|||
|
]
|
|||
|
```
|
|||
|
|
|||
|
**Query parameters**:
|
|||
|
|
|||
|
- **filters** - JSON encoded network list filter. The filter value is one of:
|
|||
|
- `id=<network-id>` Matches all or part of a network id.
|
|||
|
- `name=<network-name>` Matches all or part of a network name.
|
|||
|
- `type=["custom"|"builtin"]` Filters networks by type. The `custom` keyword returns all user-defined networks.
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **200** - no error
|
|||
|
- **500** - server error
|
|||
|
|
|||
|
#### Inspect network
|
|||
|
|
|||
|
`GET /networks/(id or name)`
|
|||
|
|
|||
|
Return low-level information on the network `id`
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
GET /v1.22/networks/7d86d31b1478e7cca9ebed7e73aa0fdeec46c5ca29497431d3007d2d9e15ed99 HTTP/1.1
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
```
|
|||
|
HTTP/1.1 200 OK
|
|||
|
Content-Type: application/json
|
|||
|
|
|||
|
{
|
|||
|
"Name": "net01",
|
|||
|
"Id": "7d86d31b1478e7cca9ebed7e73aa0fdeec46c5ca29497431d3007d2d9e15ed99",
|
|||
|
"Scope": "local",
|
|||
|
"Driver": "bridge",
|
|||
|
"IPAM": {
|
|||
|
"Driver": "default",
|
|||
|
"Config": [
|
|||
|
{
|
|||
|
"Subnet": "172.19.0.0/16",
|
|||
|
"Gateway": "172.19.0.1/16"
|
|||
|
}
|
|||
|
],
|
|||
|
"Options": {
|
|||
|
"foo": "bar"
|
|||
|
}
|
|||
|
},
|
|||
|
"Containers": {
|
|||
|
"19a4d5d687db25203351ed79d478946f861258f018fe384f229f2efa4b23513c": {
|
|||
|
"Name": "test",
|
|||
|
"EndpointID": "628cadb8bcb92de107b2a1e516cbffe463e321f548feb37697cce00ad694f21a",
|
|||
|
"MacAddress": "02:42:ac:13:00:02",
|
|||
|
"IPv4Address": "172.19.0.2/16",
|
|||
|
"IPv6Address": ""
|
|||
|
}
|
|||
|
},
|
|||
|
"Options": {
|
|||
|
"com.docker.network.bridge.default_bridge": "true",
|
|||
|
"com.docker.network.bridge.enable_icc": "true",
|
|||
|
"com.docker.network.bridge.enable_ip_masquerade": "true",
|
|||
|
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
|
|||
|
"com.docker.network.bridge.name": "docker0",
|
|||
|
"com.docker.network.driver.mtu": "1500"
|
|||
|
}
|
|||
|
}
|
|||
|
```
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **200** - no error
|
|||
|
- **404** - network not found
|
|||
|
- **500** - server error
|
|||
|
|
|||
|
#### Create a network
|
|||
|
|
|||
|
`POST /networks/create`
|
|||
|
|
|||
|
Create a network
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
```
|
|||
|
POST /v1.22/networks/create HTTP/1.1
|
|||
|
Content-Type: application/json
|
|||
|
Content-Length: 12345
|
|||
|
|
|||
|
{
|
|||
|
"Name":"isolated_nw",
|
|||
|
"CheckDuplicate":true,
|
|||
|
"Driver":"bridge",
|
|||
|
"IPAM":{
|
|||
|
"Driver": "default",
|
|||
|
"Config":[
|
|||
|
{
|
|||
|
"Subnet":"172.20.0.0/16",
|
|||
|
"IPRange":"172.20.10.0/24",
|
|||
|
"Gateway":"172.20.10.11"
|
|||
|
},
|
|||
|
{
|
|||
|
"Subnet":"2001:db8:abcd::/64",
|
|||
|
"Gateway":"2001:db8:abcd::1011"
|
|||
|
}
|
|||
|
],
|
|||
|
"Options": {
|
|||
|
"foo": "bar"
|
|||
|
}
|
|||
|
},
|
|||
|
"Internal":true
|
|||
|
}
|
|||
|
```
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
```
|
|||
|
HTTP/1.1 201 Created
|
|||
|
Content-Type: application/json
|
|||
|
|
|||
|
{
|
|||
|
"Id": "22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30",
|
|||
|
"Warning": ""
|
|||
|
}
|
|||
|
```
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **201** - no error
|
|||
|
- **404** - plugin not found
|
|||
|
- **500** - server error
|
|||
|
|
|||
|
**JSON parameters**:
|
|||
|
|
|||
|
- **Name** - The new network's name. this is a mandatory field
|
|||
|
- **CheckDuplicate** - Requests daemon to check for networks with same name. Defaults to `false`.
|
|||
|
Since Network is primarily keyed based on a random ID and not on the name,
|
|||
|
and network name is strictly a user-friendly alias to the network
|
|||
|
which is uniquely identified using ID, there is no guaranteed way to check for duplicates.
|
|||
|
This parameter CheckDuplicate is there to provide a best effort checking of any networks
|
|||
|
which has the same name but it is not guaranteed to catch all name collisions.
|
|||
|
- **Driver** - Name of the network driver plugin to use. Defaults to `bridge` driver
|
|||
|
- **IPAM** - Optional custom IP scheme for the network
|
|||
|
- **Driver** - Name of the IPAM driver to use. Defaults to `default` driver
|
|||
|
- **Config** - List of IPAM configuration options, specified as a map:
|
|||
|
`{"Subnet": <CIDR>, "IPRange": <CIDR>, "Gateway": <IP address>, "AuxAddress": <device_name:IP address>}`
|
|||
|
- **Options** - Driver-specific options, specified as a map: `{"option":"value" [,"option2":"value2"]}`
|
|||
|
- **Options** - Network specific options to be used by the drivers
|
|||
|
|
|||
|
#### Connect a container to a network
|
|||
|
|
|||
|
`POST /networks/(id or name)/connect`
|
|||
|
|
|||
|
Connect a container to a network
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
```
|
|||
|
POST /v1.22/networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30/connect HTTP/1.1
|
|||
|
Content-Type: application/json
|
|||
|
Content-Length: 12345
|
|||
|
|
|||
|
{
|
|||
|
"Container":"3613f73ba0e4",
|
|||
|
"EndpointConfig": {
|
|||
|
"IPAMConfig": {
|
|||
|
"IPv4Address":"172.24.56.89",
|
|||
|
"IPv6Address":"2001:db8::5689"
|
|||
|
}
|
|||
|
}
|
|||
|
}
|
|||
|
```
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 200 OK
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **200** - no error
|
|||
|
- **404** - network or container is not found
|
|||
|
- **500** - Internal Server Error
|
|||
|
|
|||
|
**JSON parameters**:
|
|||
|
|
|||
|
- **container** - container-id/name to be connected to the network
|
|||
|
|
|||
|
#### Disconnect a container from a network
|
|||
|
|
|||
|
`POST /networks/(id or name)/disconnect`
|
|||
|
|
|||
|
Disconnect a container from a network
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
```
|
|||
|
POST /v1.22/networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30/disconnect HTTP/1.1
|
|||
|
Content-Type: application/json
|
|||
|
Content-Length: 12345
|
|||
|
|
|||
|
{
|
|||
|
"Container":"3613f73ba0e4",
|
|||
|
"Force":false
|
|||
|
}
|
|||
|
```
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 200 OK
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **200** - no error
|
|||
|
- **404** - network or container not found
|
|||
|
- **500** - Internal Server Error
|
|||
|
|
|||
|
**JSON parameters**:
|
|||
|
|
|||
|
- **Container** - container-id/name to be disconnected from a network
|
|||
|
- **Force** - Force the container to disconnect from a network
|
|||
|
|
|||
|
#### Remove a network
|
|||
|
|
|||
|
`DELETE /networks/(id or name)`
|
|||
|
|
|||
|
Instruct the driver to remove the network (`id`).
|
|||
|
|
|||
|
**Example request**:
|
|||
|
|
|||
|
DELETE /v1.22/networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30 HTTP/1.1
|
|||
|
|
|||
|
**Example response**:
|
|||
|
|
|||
|
HTTP/1.1 200 OK
|
|||
|
|
|||
|
**Status codes**:
|
|||
|
|
|||
|
- **200** - no error
|
|||
|
- **403** - operation not supported for pre-defined networks
|
|||
|
- **404** - no such network
|
|||
|
- **500** - server error
|
|||
|
|
|||
|
## 3. Going further
|
|||
|
|
|||
|
### 3.1 Inside `docker run`
|
|||
|
|
|||
|
As an example, the `docker run` command line makes the following API calls:
|
|||
|
|
|||
|
- Create the container
|
|||
|
|
|||
|
- If the status code is 404, it means the image doesn't exist:
|
|||
|
- Try to pull it.
|
|||
|
- Then, retry to create the container.
|
|||
|
|
|||
|
- Start the container.
|
|||
|
|
|||
|
- If you are not in detached mode:
|
|||
|
- Attach to the container, using `logs=1` (to have `stdout` and
|
|||
|
`stderr` from the container's start) and `stream=1`
|
|||
|
|
|||
|
- If in detached mode or only `stdin` is attached, display the container's id.
|
|||
|
|
|||
|
### 3.2 Hijacking
|
|||
|
|
|||
|
In this version of the API, `/attach`, uses hijacking to transport `stdin`,
|
|||
|
`stdout`, and `stderr` on the same socket.
|
|||
|
|
|||
|
To hint potential proxies about connection hijacking, Docker client sends
|
|||
|
connection upgrade headers similarly to websocket.
|
|||
|
|
|||
|
Upgrade: tcp
|
|||
|
Connection: Upgrade
|
|||
|
|
|||
|
When Docker daemon detects the `Upgrade` header, it switches its status code
|
|||
|
from **200 OK** to **101 UPGRADED** and resends the same headers.
|
|||
|
|
|||
|
|
|||
|
### 3.3 CORS Requests
|
|||
|
|
|||
|
To set cross origin requests to the Engine API please give values to
|
|||
|
`--api-cors-header` when running Docker in daemon mode. Set * (asterisk) allows all,
|
|||
|
default or blank means CORS disabled
|
|||
|
|
|||
|
$ dockerd -H="192.168.1.9:2375" --api-cors-header="http://foo.bar"
|