--- 标题: “引擎 API v1.24” 描述: “Docker 的 API 文档” 关键字: “API,Docker,rcli,REST,文档” redirect_from:

- /engine/reference/api/docker_remote_api_v1.24/
- /reference/api/docker_remote_api_v1.24/

1.简要介绍

  • 守护进程侦听unix:///var/run/docker.sock but you can Bind Docker to another host/port or a Unix socket.
  • API 往往是rest。然而,对于一些复杂的命令,如attach or pull,HTTP 连接被劫持传输stdout, stdin and stderr.
  • A Content-Length标头应该存在于POST对期望主体的端点的请求。
  • 若要锁定 API 的特定版本,请在 URL 前加上要使用的 API 版本。例如,/v1.18/info。如果 URL 中不包含任何版本,则使用最大支持的 API 版本。
  • 如果守护程序不支持 URL 中指定的 API 版本,则会使用 HTTP400 Bad Request返回错误消息。

2. Errors

引擎 API 使用标准的 HTTP 状态代码来指示 API 调用的成功或失败。响应的主体将以以下格式为 JSON:

{
    "message": "page not found"
}

为每个终结点返回的状态代码都在以下终结点文档中指定。

3. Endpoints

3.1 Containers

List containers

GET /containers/json

List containers

Example request:

GET /v1.24/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,
             "State": "exited",
             "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"
                              }
                     }
             },
             "Mounts": [
                     {
                              "Name": "fac362...80535",
                              "Source": "/data",
                              "Destination": "/data",
                              "Driver": "local",
                              "Mode": "ro,Z",
                              "RW": false,
                              "Propagation": ""
                     }
             ]
     },
     {
             "Id": "9cd87474be90",
             "Names":["/coolName"],
             "Image": "ubuntu:latest",
             "ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82",
             "Command": "echo 222222",
             "Created": 1367854155,
             "State": "exited",
             "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"
                              }
                     }
             },
             "Mounts": []
     },
     {
             "Id": "3176a2479c92",
             "Names":["/sleepy_dog"],
             "Image": "ubuntu:latest",
             "ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82",
             "Command": "echo 3333333333333333",
             "Created": 1367854154,
             "State": "exited",
             "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"
                              }
                     }
             },
             "Mounts": []
     },
     {
             "Id": "4cb07b47f9fb",
             "Names":["/running_cat"],
             "Image": "ubuntu:latest",
             "ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82",
             "Command": "echo 444444444444444444444444444444444",
             "Created": 1367854152,
             "State": "exited",
             "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"
                              }
                     }
             },
             "Mounts": []
     }
]

Query parameters:

  • all-1/True/true 或 0/False/false,显示所有容器。默认情况下只显示正在运行的容器 (即,该默认值为 false)
  • limit – Show limit最后创建的容器,包括非运行的容器。
  • since-仅显示自 Id 创建的容器,包括非运行的容器。
  • before-仅显示 Id 之前创建的容器,包括非运行的容器。
  • size-1/True 或 0/False/false,显示容器大小
  • filters-过滤器的 JSON 编码值 (amap[string][]string) 在容器列表上处理。可用筛选器:
  • exited=<int>; -- 容器的退出代码<int> ;
  • status=(created|restarting|running|paused|exited|dead)
  • label=key or label="key=value"容器标签的
  • isolation=(default|process|hyperv) (仅 Windows 守护程序)
  • ancestor=(<image-name>[:<tag>], <image id> or <image@digest>)
  • before=(<container id> or <container name>)
  • since=(<container id> or <container name>)
  • volume=(<volume name> or <mount point destination>)
  • network=(<network id> or <network name>)

Status codes:

  • 200 – no error
  • 400 – bad parameter
  • 500 – server error

Create a container

POST /containers/create

Create a container

Example request:

POST /v1.24/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": "",
       "Image": "ubuntu",
       "Labels": {
               "com.example.vendor": "Acme",
               "com.example.license": "GPL",
               "com.example.version": "1.0"
       },
       "Volumes": {
         "/volumes/data": {}
       },
       "Healthcheck":{
          "Test": ["CMD-SHELL", "curl localhost:3000"],
          "Interval": 1000000000,
          "Timeout": 10000000000,
          "Retries": 10,
          "StartPeriod": 60000000000
       },
       "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,
         "CpuPercent": 80,
         "CpuShares": 512,
         "CpuPeriod": 100000,
         "CpuQuota": 50000,
         "CpusetCpus": "0,1",
         "CpusetMems": "0,1",
         "IOMaximumBandwidth": 0,
         "IOMaximumIOps": 0,
         "BlkioWeight": 300,
         "BlkioWeightDevice": [{}],
         "BlkioDeviceReadBps": [{}],
         "BlkioDeviceReadIOps": [{}],
         "BlkioDeviceWriteBps": [{}],
         "BlkioDeviceWriteIOps": [{}],
         "MemorySwappiness": 60,
         "OomKillDisable": false,
         "OomScoreAdj": 500,
         "PidMode": "",
         "PidsLimit": -1,
         "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": [],
         "Sysctls": { "net.ipv4.ip_forward": "1" },
         "Ulimits": [{}],
         "LogConfig": { "Type": "json-file", "Config": {} },
         "SecurityOpt": [],
         "StorageOpt": {},
         "CgroupParent": "",
         "VolumeDriver": "",
         "ShmSize": 67108864
      },
      "NetworkingConfig": {
          "EndpointsConfig": {
              "isolated_nw" : {
                  "IPAMConfig": {
                      "IPv4Address":"172.20.30.33",
                      "IPv6Address":"2001:db8:abcd::3033",
                      "LinkLocalIPs":["169.254.34.68", "fe80::3468"]
                  },
                  "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-包含要用于容器的主机名的字符串值。这必须是有效的 RFC 1123 主机名。
  • Domainname-包含要用于容器的域名的字符串值。
  • User-指定容器中的用户的字符串值。
  • AttachStdin-布尔值,附加到stdin.
  • AttachStdout-布尔值,附加到stdout.
  • AttachStderr-布尔值,附加到stderr.
  • Tty-布尔值,将标准流附加到tty, including stdin如果它不关闭。
  • OpenStdin-布尔值,打开stdin,
  • StdinOnce-布尔值,关闭stdin连接的 1 个客户端断开后。
  • Env-环境变量的列表,以["VAR=value", ...]
  • Labels-将标签的地图添加到容器中。要指定地图:{"key":"value", ... }
  • Cmd-命令运行指定为字符串或字符串数组。
  • Entrypoint-将容器的入口点设置为字符串或字符串数组。
  • Image-指定要用于容器的图像名称的字符串。
  • Volumes-对象映射将容器中的挂载点路径 (字符串) 映射为空对象。
  • Healthcheck-用于检查容器是否健康的测试。Test-要执行的测试。可能的值是: +{}从映像或父映像继承 healthcheck +{"NONE"}禁用 healthcheck +{"CMD", args...}直接执行参数 +{"CMD-SHELL", command}使用系统的默认 shell 运行命令Interval-在几秒钟内检查之间等待的时间。应该是 0 或至少 1000000 MS)。0 意味着继承。Timeout-等待的时间之前考虑的检查已暂停。应该是 0 或至少 1000000 MS)。0 意味着继承。Retries-需要将容器视为不健康的连续故障数。0 意味着继承。StartPeriod-开始运行状况之前等待容器初始化的时间-在纳秒中重试倒计时。应该是 0 或至少 1000000 MS)。0 意味着继承。
  • WorkingDir-指定要运行的命令的工作目录的字符串。
  • NetworkDisabled-布尔值,当 true 禁用容器的网络时
  • ExposedPorts-对象映射端口的形式为:"ExposedPorts": { "<port>/<tcp|udp>: {}" }
  • StopSignal-信号以字符串或无符号整数形式停止容器。SIGTERM by default.
  • HostConfigBinds-此容器的卷绑定列表。每个卷绑定都是这些形式之一的字符串:host-src:container-dest将主机路径绑定到容器中。两者host-src, and container-dest must be an absolute path.host-src:container-dest:ro使绑定装载在容器内只读。两者host-src, and container-dest must be an absolute path.volume-name:container-dest要将由卷驱动程序管理的卷绑定到容器中。container-dest must be an absolute path.volume-name:container-dest:ro将卷装入容器内只读。container-dest must be an absolute path.Tmpfs-容器目录的映射,应该由 tmpfs 装载替换,以及相应的装载选项。表单中的 JSON 对象{ "/run": "rw,noexec,nosuid,size=65536k" }.Links-容器的链接列表。每个链接条目应以container_name:alias.Memory-内存限制 (以字节为单位)。MemorySwap-总内存限制 (内存 + 交换); 设置-1启用无限制交换。你必须用这个memory并使交换值大于memory.MemoryReservation-内存软限制字节。KernelMemory-内核内存限制 (以字节为单位)。CpuPercent-包含可用 cpu 可用百分比的整数值。(仅限 Windows 守护程序)CpuShares-包含容器的 CPU 共享的整数值 (即。相对重量与其他容器)。CpuPeriod-CPU 周期的长度 (毫秒)。CpuQuota-容器可以在 CPU 周期内获得的 CPU 时间的微秒。CpusetCpus-包含cgroups CpusetCpus to use.CpusetMems-内存节点 (MEMs),其中允许执行 (0-3,0,1)。仅对 NUMA 系统有效。IOMaximumBandwidth-IOps 的最大 IO 绝对速率。IOMaximumIOps-以每秒字节为单位的最大 IO 绝对速率。BlkioWeight-块 IO 重量 (相对重量) 接受 10 到 1000 之间的重量值。BlkioWeightDevice-块 IO 重量 (相对设备重量) 的形式:"BlkioWeightDevice": [{"Path": "device_path", "Weight": weight}]BlkioDeviceReadBps-以以下形式限制设备的读取速率 (每秒字节数):"BlkioDeviceReadBps": [{"Path": "device_path", "Rate": rate}], for example: "BlkioDeviceReadBps": [{"Path": "/dev/sda", "Rate": "1024"}]"BlkioDeviceWriteBps-限制写入速率 (每秒字节) 到设备的形式:"BlkioDeviceWriteBps": [{"Path": "device_path", "Rate": rate}], for example: "BlkioDeviceWriteBps": [{"Path": "/dev/sda", "Rate": "1024"}]"BlkioDeviceReadIOps-限制读取速率 (IO 每秒) 从设备的形式:"BlkioDeviceReadIOps": [{"Path": "device_path", "Rate": rate}], for example: "BlkioDeviceReadIOps": [{"Path": "/dev/sda", "Rate": "1000"}]BlkioDeviceWriteIOps-限制写入速率 (IO 每秒) 到设备的形式:"BlkioDeviceWriteIOps": [{"Path": "device_path", "Rate": rate}], for example: "BlkioDeviceWriteIOps": [{"Path": "/dev/sda", "Rate": "1000"}]MemorySwappiness-调整容器的内存弹性行为。接受介于 0 和 100 之间的整数。OomKillDisable-布尔值,是否为容器禁用 OOM 杀手。OomScoreAdj-包含给容器的得分的整数值,以便调整 OOM killer 首选项。PidMode-为容器设置 PID (进程) 命名空间模式;"container:<name|id>": 加入另一个容器的 PID 命名空间"host": 在容器中使用主机的 PID 命名空间PidsLimit-调整容器的 pid 限制。设置-1 为无限。PortBindings-暴露的集装箱港口和他们应该映射到主机港口的地图。表单中的 JSON 对象{ <port>/<protocol>: [{ "HostPort": "<port>" }] } Take note that port被指定为字符串而不是整数值。PublishAllPorts-为容器的所有暴露端口分配临时主机端口。指定为布尔值。当容器停止并在容器启动时分配时,会取消分配端口。重新启动容器时,可能会更改分配的端口。端口是从依赖于内核的临时端口范围中选择的。例如,在 Linux 上,范围由/proc/sys/net/ipv4/ip_local_port_range.Privileged-让容器完全访问主机。指定为布尔值。ReadonlyRootfs-将容器的根文件系统装载为只读。指定为布尔值。Dns-要使用的容器的 DNS 服务器列表。DnsOptions-DNS 选项列表DnsSearch-DNS 搜索域的列表ExtraHosts-主机名/IP 映射列表,以添加到容器的/etc/hosts文件。在表单中指定["hostname:IP"].VolumesFrom-要从另一个容器继承的卷的列表。在表单中指定<container name>[:<ro|rw>]CapAdd-要添加到容器的内核功能列表。Capdrop-从容器中删除的内核功能列表。GroupAdd-容器进程将运行的其他组的列表RestartPolicy-容器退出时要应用的行为。该值是一个具有Name任意一个的属性"always"要始终重新启动,"unless-stopped"除非用户手动停止容器或"on-failure"只有当容器退出代码为非零时才重新启动。如果on-failure is used, MaximumRetryCount控制放弃前要重试的次数。默认不重新启动。 (可选) 每次重新启动之前会添加一个不断增加的延迟 (将上一个延迟增加一倍,以 100 MS 开始),以防止淹没服务器。UsernsMode-在启用 usernamespace 重新映射选项时,为容器设置 usernamespace 模式。支持的值为:host.NetworkMode-设置容器的网络模式。支持的标准值为:bridge, host, none, and container:<name|id>。任何其他值都被视为此容器应连接到的自定义网络的名称。Devices-一个设备列表添加到容器指定为 JSON 对象的形式{ "PathOnHost": "/dev/deviceName", "PathInContainer": "/dev/deviceName", "CgroupPermissions": "mrw"}Ulimits-要在容器中设置的 ulimit 的列表,指定为{ "Name": <name>, "Soft": <soft limit>, "Hard": <hard limit> }, for example: Ulimits: { "Name": "nofile", "Soft": 1024, "Hard": 2048 }Sysctls-要在容器中设置的内核参数 (sysctls) 的列表,指定为{ <name>: <Value> }, for example: { "net.ipv4.ip_forward": "1" }SecurityOpt: 用于自定义 MLS 系统标签的字符串值列表,如 SELinux。StorageOpt: 每个容器的存储驱动程序选项。可以在表单中传递选项{"size":"120G"}LogConfig-容器的日志配置,指定为 JSON 对象的形式{ "Type": "<driver_name>", "Config": {"key1": "val1"}}. Available types: json-file, syslog, journald, gelf, fluentd, awslogs, splunk, etwlogs, none. json-file logging driver.CgroupParent - Path to cgroups容器下面的cgroup已创建。如果路径不是绝对的,则认为路径是相对于cgroups初始化过程的路径。如果尚未存在,将创建 Cgroups。VolumeDriver-驱动程序,这个容器用户装载卷。ShmSize - Size of /dev/shm以字节为单位。大小必须大于 0。如果省略,系统将使用 64 MB。

Query parameters:

  • name-为容器分配指定的名称。必须匹配/?[a-zA-Z0-9_-]+.

Status codes:

  • 201 – no error
  • 400 – bad parameter
  • 404-没有这样的容器
  • 406-无法附加 (容器不运行)
  • 409 – conflict
  • 500 – server error

Inspect a container

GET /containers/(id or name)/json

返回容器的低水平信息id

Example request:

  GET /v1.24/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,
       "IOMaximumBandwidth": 0,
       "IOMaximumIOps": 0,
       "BlkioWeight": 0,
       "BlkioWeightDevice": [{}],
       "BlkioDeviceReadBps": [{}],
       "BlkioDeviceWriteBps": [{}],
       "BlkioDeviceReadIOps": [{}],
       "BlkioDeviceWriteIOps": [{}],
       "CapAdd": null,
       "CapDrop": null,
       "ContainerIDFile": "",
       "CpusetCpus": "",
       "CpusetMems": "",
       "CpuPercent": 80,
       "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,
       "Sysctls": {
               "net.ipv4.ip_forward": "1"
       },
       "StorageOpt": 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": ""
       }
    ]
}

示例请求,包含大小信息:

GET /v1.24/containers/4fa6e0f0c678/json?size=1 HTTP/1.1

示例响应,包含大小信息:

HTTP/1.1 200 OK
Content-Type: application/json

{
....
"SizeRw": 0,
"SizeRootFs": 972,
....
}

Query parameters:

  • size-1/True 或 0/False/false,返回容器大小信息。默认值为false.

Status codes:

  • 200 – no error
  • 404-没有这样的容器
  • 500 – server error

列出容器内运行的进程

GET /containers/(id or name)/top

列出容器内运行的进程id。在 Unix 系统上,这是通过运行ps命令。Windows 不支持此终结点。

Example request:

GET /v1.24/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.24/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_argsps要使用的参数 (例如,aux), defaults to -ef

Status codes:

  • 200 – no error
  • 404-没有这样的容器
  • 500 – server error

Get container logs

GET /containers/(id or name)/logs

Get stdout and stderr容器中的日志id

Note: 此终结点仅适用于具有json-file or journald logging drivers.

Example request:

 GET /v1.24/containers/4fa6e0f0c678/logs?stderr=1&stdout=1&timestamps=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:

  • details-1/真或 0/假,显示额外的细节提供给日志。默认false.
  • follow-1/True/true 或 0/False/false,返回流。默认false.
  • stdout-1/真或 0/假,显示?stdout log. Default false.
  • stderr-1/真或 0/假,显示?stderr log. Default false.
  • since-UNIX 时间戳 (整数) 来筛选日志。指定时间戳将只输出日志条目,因为该时间戳。默认值: 0 (未筛选)
  • timestamps-1/真或 0/假,打印每个日志行的时间戳。默认false.
  • tail-输出日志结束时指定的行数:all or <number>. Default all.

Status codes:

  • 101-没有错误,关于劫持的提示代理
  • 200-没有错误,没有发现升级标题
  • 404-没有这样的容器
  • 500 – server error

检查容器文件系统上的更改

GET /containers/(id or name)/changes

检查容器上的更改id's filesystem

Example request:

GET /v1.24/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-没有这样的容器
  • 500 – server error

Export a container

GET /containers/(id or name)/export

导出容器的内容id

Example request:

GET /v1.24/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-没有这样的容器
  • 500 – server error

获取基于资源使用情况的容器统计信息

GET /containers/(id or name)/stats

此终结点返回容器的资源使用统计信息的实时流。

Example request:

GET /v1.24/containers/redis1/stats HTTP/1.1

Example response:

  HTTP/1.1 200 OK
  Content-Type: application/json

  {
     "read" : "2015-01-08T22:57:31.547920715Z",
     "pids_stats": {
        "current": 3
     },
     "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是 cpu 的统计previousRead,用于计算 cpu 使用率百分比。这不是确切的副本cpu_stats field.

Query parameters:

  • stream-1/真或 0/假,拉统计一次,然后断开连接。默认true.

Status codes:

  • 200 – no error
  • 404-没有这样的容器
  • 500 – server error

调整容器 TTY 的大小

POST /containers/(id or name)/resize

调整容器的 TTY 大小id。单位是字符数。必须重新启动容器,使调整大小生效。

Example request:

  POST /v1.24/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-没有这样的容器
  • 500-无法调整容器大小

Start a container

POST /containers/(id or name)/start

启动容器id

Example request:

POST /v1.24/containers/e90e34656806/start HTTP/1.1

Example response:

HTTP/1.1 204 No Content

Query parameters:

  • detachKeys-重写用于分离容器的键序列。格式是单个字符[a-Z] or ctrl-<value> where <value> is one of: a-z, @, ^, [, , or _.

Status codes:

  • 204 – no error
  • 304-容器已经开始
  • 404-没有这样的容器
  • 500 – server error

Stop a container

POST /containers/(id or name)/stop

Stop the container id

Example request:

POST /v1.24/containers/e90e34656806/stop?t=5 HTTP/1.1

Example response:

HTTP/1.1 204 No Content

Query parameters:

  • t-杀死容器前等待的秒数

Status codes:

  • 204 – no error
  • 304-容器已经停止
  • 404-没有这样的容器
  • 500 – server error

Restart a container

POST /containers/(id or name)/restart

重新启动容器id

Example request:

POST /v1.24/containers/e90e34656806/restart?t=5 HTTP/1.1

Example response:

HTTP/1.1 204 No Content

Query parameters:

  • t-杀死容器前等待的秒数

Status codes:

  • 204 – no error
  • 404-没有这样的容器
  • 500 – server error

Kill a container

POST /containers/(id or name)/kill

Kill the container id

Example request:

POST /v1.24/containers/e90e34656806/kill HTTP/1.1

Example response:

HTTP/1.1 204 No Content

Query parameters:

  • signal-信号发送到容器: 整数或字符串SIGINT. When not set, SIGKILL假设并调用等待容器退出。

Status codes:

  • 204 – no error
  • 404-没有这样的容器
  • 500 – server error

Update a container

POST /containers/(id or name)/update

更新一个或多个容器的配置。

Example request:

   POST /v1.24/containers/e90e34656806/update HTTP/1.1
   Content-Type: application/json
   Content-Length: 12345

   {
     "BlkioWeight": 300,
     "CpuShares": 512,
     "CpuPeriod": 100000,
     "CpuQuota": 50000,
     "CpusetCpus": "0,1",
     "CpusetMems": "0",
     "Memory": 314572800,
     "MemorySwap": 514288000,
     "MemoryReservation": 209715200,
     "KernelMemory": 52428800,
     "RestartPolicy": {
       "MaximumRetryCount": 4,
       "Name": "on-failure"
     }
   }

Example response:

   HTTP/1.1 200 OK
   Content-Type: application/json

   {
       "Warnings": []
   }

Status codes:

  • 200 – no error
  • 400 – bad parameter
  • 404-没有这样的容器
  • 500 – server error

Rename a container

POST /containers/(id or name)/rename

重命名容器id to a new_name

Example request:

POST /v1.24/containers/e90e34656806/rename?name=new_name HTTP/1.1

Example response:

HTTP/1.1 204 No Content

Query parameters:

  • name-容器的新名称

Status codes:

  • 204 – no error
  • 404-没有这样的容器
  • 409-冲突名称已分配
  • 500 – server error

Pause a container

POST /containers/(id or name)/pause

暂停容器id

Example request:

POST /v1.24/containers/e90e34656806/pause HTTP/1.1

Example response:

HTTP/1.1 204 No Content

Status codes:

  • 204 – no error
  • 404-没有这样的容器
  • 500 – server error

Unpause a container

POST /containers/(id or name)/unpause

取消暂停容器id

Example request:

POST /v1.24/containers/e90e34656806/unpause HTTP/1.1

Example response:

HTTP/1.1 204 No Content

Status codes:

  • 204 – no error
  • 404-没有这样的容器
  • 500 – server error

附加到容器

POST /containers/(id or name)/attach

附加到容器id

Example request:

POST /v1.24/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-重写用于分离容器的键序列。格式是单个字符[a-Z] or ctrl-<value> where <value> is one of: a-z, @, ^, [, , or _.
  • logs-1/True/true 或 0/False/false,返回日志。默认false.
  • stream-1/True/true 或 0/False/false,返回流。默认false.
  • stdin-1/True 或 0/False/false,如果stream=true, attach to stdin. Default false.
  • stdout-1/True 或 0/False/false,如果logs=true, return stdout log, if stream=true, attach to stdout. Default false.
  • stderr-1/True 或 0/False/false,如果logs=true, return stderr log, if stream=true, attach to stderr. Default false.

Status codes:

  • 101-没有错误,关于劫持的提示代理
  • 200-没有错误,没有发现升级标题
  • 400 – bad parameter
  • 404-没有这样的容器
  • 409-容器已暂停
  • 500 – server error

Stream details:

在中启用使用 TTY 设置时POST /containers/create ,流是来自进程 PTY 和客户端的原始数据。stdin。禁用 TTY 时,流被多路复用以分离stdout and stderr.

The format is a Header and a Payload (frame).

HEADER

标头包含流写入的信息 (stdout or stderr)。它还包含在最后四个字节中编码的关联帧的大小 (uint32).

它是编码在前八个字节像这样:

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是四个字节的uint32大小编码为大 endian。

PAYLOAD

有效载荷是原始流。

IMPLEMENTATION

实现附加协议的最简单方法是:

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.

附加到容器 (websocket)

GET /containers/(id or name)/attach/ws

附加到容器id via websocket

根据 websocket 协议实现握手RFC 6455

Example request

GET /v1.24/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-重写用于分离容器的键序列。格式是单个字符[a-Z] or ctrl-<value> where <value> is one of: a-z, @, ^, [, , or _.
  • logs-1/True/true 或 0/False/false,返回日志。默认false.
  • stream-1/True/true 或 0/False/false,返回流。默认false.
  • stdin-1/True 或 0/False/false,如果stream=true, attach to stdin. Default false.
  • stdout-1/True 或 0/False/false,如果logs=true, return stdout log, if stream=true, attach to stdout. Default false.
  • stderr-1/True 或 0/False/false,如果logs=true, return stderr log, if stream=true, attach to stderr. Default false.

Status codes:

  • 200 – no error
  • 400 – bad parameter
  • 404-没有这样的容器
  • 500 – server error

Wait a container

POST /containers/(id or name)/wait

阻止直到容器id停止,然后返回退出代码

Example request:

POST /v1.24/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-没有这样的容器
  • 500 – server error

Remove a container

DELETE /containers/(id or name)

删除容器id从文件系统

Example request:

DELETE /v1.24/containers/16253994b7c4?v=1 HTTP/1.1

Example response:

HTTP/1.1 204 No Content

Query parameters:

  • v-1/True/true 或 0/False/false,删除与容器关联的卷。默认false.
  • force-1/True 或 0/False/false,杀死然后删除容器。默认false.
  • link-1/True/true 或 0/False/false,删除与容器关联的指定链接。默认false.

Status codes:

  • 204 – no error
  • 400 – bad parameter
  • 404-没有这样的容器
  • 409 – conflict
  • 500 – server error

在容器中检索有关文件和文件夹的信息

HEAD /containers/(id or name)/archive

请参阅的描述X-Docker-Container-Path-Stat下一节中的标题。

在容器中获取文件系统资源的存档

GET /containers/(id or name)/archive

在容器的文件系统中获取资源的 tar 存档id.

Query parameters:

  • path-容器文件系统中的资源进行归档。需要。如果不是绝对路径,则它相对于容器的根目录。由指定的资源path必须存在。要断言资源预计是一个目录,path should end in / or /.(假设一个路径分隔符/). If path ends in /.然后,这表明只有的内容path应该复制目录。Sylink 总是解析为其目标。Note: 不可能复制某些系统文件,如资源/proc, /sys, /dev,并在容器中由用户创建的挂载。

Example request:

GET /v1.24/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 %}

在成功时,一个响应头X-Docker-Container-Path-Stat将设置为包含有关存档资源的一些文件系统标头信息的 base64-encoded JSON 对象。上面的示例值将解码到以下 JSON 对象 (为可读性添加了空格):

json { "name": "root", "size": 4096, "mode": 2147484096, "mtime": "2014-02-27T20:51:23Z", "linkTarget": "" }

A HEAD如果需要此信息,也可以向此终结点提出请求。

Status codes:

  • 200-成功,返回复制资源的存档
  • 400-客户端错误,错误的参数,JSON 响应体的细节,其中之一:必须指定路径参数 (* path * 不能为空)不是一个目录 (* 路径 * * 被断言是一个目录,但作为文件存在)
  • 404-客户端错误,找不到资源,其中一个:-没有这样的容器 (容器id does not exist)没有这种文件或目录 (* 路径 * * 不存在)
  • 500 - server error

将文件或文件夹的存档解压缩到容器中的目录中

PUT /containers/(id or name)/archive

将一个 tar 归档文件上载到容器文件系统中的路径中id.

Query parameters:

  • path-路径到容器中的目录,提取归档的内容到。需要。如果不是绝对路径,则它相对于容器的根目录。Thepath资源必须存在。
  • noOverwriteDirNonDir-如果 "1","true", 或者 “True”,那么如果解压缩给定内容将导致现有目录被替换为非目录,反之亦然,这将是一个错误。

Example request:

PUT /v1.24/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-内容被成功提取
  • 400-客户端错误,错误的参数,JSON 响应体的细节,其中之一:必须指定路径参数 (* path * 不能为空)不是一个目录 (* 路径 * * 应该是一个目录,但作为文件存在)无法使用非目录覆盖现有目录 (如果noOverwriteDirNonDir)无法使用目录覆盖现有非目录 (如果noOverwriteDirNonDir)
  • 403-客户端错误,权限被拒绝,卷或容器 rootfs 被标记为只读。
  • 404-客户端错误,找不到资源,其中一个:-没有这样的容器 (容器id does not exist)没有这样的文件或目录 (* 路径 * 资源不存在)
  • 500 – server error

3.2 Images

List Images

GET /images/json

Example request:

GET /v1.24/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"
     }
  }
]

示例请求,包含摘要信息:

GET /v1.24/images/json?digests=1 HTTP/1.1

示例响应,包含摘要信息:

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": {}
  }
]

响应显示单个图像Id与两个存储库关联 (RepoTags): localhost:5000/test/busybox: and playdate。呼叫者可以使用RepoTags values localhost:5000/test/busybox:latest or playdate:latest以引用图像。

You can also use RepoDigests要引用图像的值。在此响应中,数组只有一个引用,这是对localhost:5000/test/busybox repository; the playdate存储库没有摘要。您可以使用以下值引用此摘要:localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d...

See the docker run and docker build用于命令行上摘要和标记引用的示例的命令。

Query parameters:

  • all-1/True/true 或 0/False/false,默认为 false
  • filters-在图像列表上处理的过滤器 (映射 [string] [] 字符串) 的 JSON 编码值。可用筛选器:
  • dangling=true
  • label=key or label="key=value" of an image label
  • before=(<image-name>[:<tag>], <image id> or <image@digest>)
  • since=(<image-name>[:<tag>], <image id> or <image@digest>)
  • filter-只返回具有指定名称的图像

从 Dockerfile 生成图像

POST /build

从 Dockerfile 构建图像

Example request:

POST /v1.24/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..."}}

输入流必须是tar使用以下算法之一压缩存档:identity (no compression), gzip, bzip2, xz.

存档必须包括通常称为的生成说明文件。Dockerfile在档案的根目录。Thedockerfile参数可用于指定不同的生成说明文件。为此,其值必须是要使用的备用生成说明文件的路径。

存档可能包括任何数量的其他文件,这些文件可在生成上下文中访问 (请参阅ADD build command).

Docker 守护进程执行的初步验证Dockerfile在启动生成之前,如果语法不正确,则返回错误。在此之后,每个指令都会逐一运行,直到输出新映像的 ID 为止。

如果客户端放弃或被杀死,则取消生成。

Query parameters:

  • dockerfile-构建上下文中的路径Dockerfile。如果忽略此remote被指定并指向外部Dockerfile.
  • t-一个名称和可选标记应用到图像name:tag格式。如果你忽略了tag the default latest假设值。您可以提供一个或多个?t parameters.
  • remote-Git 存储库 URI 或 HTTP/HTTPS 上下文 URI。如果 URI 指向单个文本文件,则该文件的内容将被放置到名为Dockerfile图像是从该文件生成的。如果 URI 指向 tarball,则该文件由守护程序下载,其中的内容用作生成的上下文。如果 URI 指向一个 tarball 和dockerfile参数也指定,必须有一个文件与 tarball 内的相应路径。
  • q-抑制详细生成输出。
  • nocache-在构建图像时不要使用缓存。
  • pull-尝试拉图像,即使一个旧的图像存在于本地。
  • rm-在成功构建 (默认行为) 后删除中间容器。
  • forcerm-始终删除中间容器 (包括rm).
  • memory-为构建设置内存限制。
  • memswap-总内存 (内存 + 交换),-1启用无限制交换。
  • cpushares-CPU 份额 (相对权重)。
  • cpusetcpus-允许执行的 cpu (例如,0-3, 0,1).
  • cpuperiod-CPU 周期的长度 (毫秒)。
  • cpuquota-容器可以在 CPU 周期内获得的 CPU 时间的微秒。
  • buildargs-构建时间变量的字符串对的 JSON 映射。用户在生成时传递这些值。码头工人使用buildargs作为命令的环境上下文,通过 Dockerfile 的RUN指令或其他 Dockerfile 指令中的变量扩展。这并不意味着传递秘密值。Read more about the buildargs instruction
  • shmsize - Size of /dev/shm以字节为单位。大小必须大于 0。如果省略,系统将使用 64 MB。
  • labels-在图像上设置标签的字符串对的 JSON 映射。

Request Headers:

  • Content-type – Set to "application/x-tar".
  • X-Registry-Config-具有以下结构的 base64-url-safe-encoded 注册表验证配置 JSON 对象:    {         "docker.example.com": {             "username": "janedoe",             "password": "hunter2"         },         "https://index.docker.io/v1/": {             "username": "mobydock",             "password": "conta1n3rize14"         }     } 该对象将注册表的主机名映射到包含该注册表的 “用户名” 和 “密码” 的对象。可以指定多个注册表,因为生成可能基于要求身份验证从任意注册表中提取的图像。只有注册表域名 (如果不是默认的 “443”) 是必需的。然而 (出于传统原因) 的 “正式” 码头工人,公司。托管注册表必须同时指定一个 “https:/v1/” 前缀和一个 “/v1/” 后缀,即使 Docker 更喜欢使用 v2 注册表 API。

Status codes:

  • 200 – no error
  • 500 – server error

Create an image

POST /images/create

通过从注册表中提取或导入映像来创建映像

Example request:

POST /v1.24/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..."}
...

当使用此端点从注册表拉图像时,X-Registry-Auth头可以用于包含 base64-encoded AuthConfig 对象。

Query parameters:

  • fromImage-要拉的图像的名称。该名称可能包含一个标记或摘要。此参数只能在拉图像时使用。如果 HTTP 连接已关闭,则拉将被取消。
  • fromSrc-源导入。该值可能是可以从中检索图像的 URL 或-从请求主体读取图像。此参数只能在导入图像时使用。
  • repo-在导入图像时提供给图像的存储库名称。回购可能包括一个标签。此参数只能在导入图像时使用。
  • tag-标签或摘要。如果提取图像时为空,则会导致提取给定图像的所有标记。

Request Headers:

  • X-Registry-Auth-Base64-encoded AuthConfig 对象,包含登录信息或令牌基于凭据的登录:{ "username": "jdoe", "password": "secret", "email": "jdoe@acme.com" }Token based login:{ "identitytoken": "9cbaf023786cd7..." }

Status codes:

  • 200 – no error
  • 404-存储库不存在或没有读取访问?
  • 500 – server error

Inspect an image

GET /images/(name)/json

返回图像中的低水平信息name

Example request:

GET /v1.24/images/example/json HTTP/1.1

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "Id" : "sha256:85f05633ddc1c50679be2b16a0479ab6f7637f8884e0cfe0f4d20e1ebb3d6e7c",
   "Container" : "cb91e48a60d01f1e27028b4fc6819f4f290b3cf12496c8176ec714d0d390984a",
   "Comment" : "",
   "Os" : "linux",
   "Architecture" : "amd64",
   "Parent" : "sha256: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" : ""
   },
   "RootFS": {
       "Type": "layers",
       "Layers": [
           "sha256:1834950e52ce4d5a88a1bbd131c537f4d0e56d10ff0dd69e66be3b7dfa9df7e6",
           "sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef"
       ]
   }
}

Status codes:

  • 200 – no error
  • 404 – no such image
  • 500 – server error

获取图像的历史

GET /images/(name)/history

返回图像的历史记录name

Example request:

GET /v1.24/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

在注册表上推送图像

POST /images/(name)/push

Push the image name on the registry

Example request:

POST /v1.24/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..."}
...

如果要将图像推送到专用注册表,该图像必须已经有一个标记到引用该注册表的存储库中。hostname and port。然后,应在 URL 中使用此存储库名称。这重复了命令行的流程。

如果 HTTP 连接已关闭,则取消推送。

Example request:

POST /v1.24/images/registry.acme.com:5000/test/push HTTP/1.1

Query parameters:

  • tag-与注册表上的图像关联的标记。这是可选的。

Request Headers:

  • X-Registry-Auth-Base64-encoded AuthConfig 对象,包含登录信息或令牌基于凭据的登录:{ "username": "jdoe", "password": "secret", "email": "jdoe@acme.com", }基于身份令牌的登录:{ "identitytoken": "9cbaf023786cd7..." }

Status codes:

  • 200 – no error
  • 404 – no such image
  • 500 – server error

将图像标记到存储库中

POST /images/(name)/tag

Tag the image name into a repository

Example request:

POST /v1.24/images/test/tag?repo=myrepo&tag=v42 HTTP/1.1

Example response:

HTTP/1.1 201 Created

Query parameters:

  • repo-要标记的存储库
  • 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从文件系统

Example request:

DELETE /v1.24/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 或 0/False/false,默认为 false
  • noprune-1/True/true 或 0/False/false,默认为 false

Status codes:

  • 200 – no error
  • 404 – no such image
  • 409 – conflict
  • 500 – server error

Search images

GET /images/search

在上搜索图像Docker Hub.

Note: 响应键已从 API v1.6 更改为反映注册表服务器发送给 docker 守护程序的请求的 JSON。

Example request:

GET /v1.24/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
  • limit-最大返回的搜索结果
  • filters-在图像列表上处理的过滤器 (映射 [string] [] 字符串) 的 JSON 编码值。可用筛选器:
  • stars=<number>
  • is-automated=(true|false)
  • is-official=(true|false)

Status codes:

  • 200 – no error
  • 500 – server error

3.3 Misc

检查身份验证配置

POST /auth

验证注册表的凭据,并获取标识令牌 (如果可用),以无需密码即可访问注册表。

Example request:

POST /v1.24/auth HTTP/1.1
Content-Type: application/json
Content-Length: 12345

{
     "username": "hannibal",
     "password": "xxxx",
     "serveraddress": "https://index.docker.io/v1/"
}

Example response:

HTTP/1.1 200 OK

{
     "Status": "Login Succeeded",
     "IdentityToken": "9cbaf023786cd7..."
}

Status codes:

  • 200 – no error
  • 204 – no error
  • 500 – server error

显示全系统信息

GET /info

显示全系统信息

Example request:

GET /v1.24/info HTTP/1.1

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "Architecture": "x86_64",
    "ClusterStore": "etcd://localhost:2379",
    "CgroupDriver": "cgroupfs",
    "Containers": 11,
    "ContainersRunning": 7,
    "ContainersStopped": 3,
    "ContainersPaused": 1,
    "CpuCfsPeriod": true,
    "CpuCfsQuota": true,
    "Debug": false,
    "DockerRootDir": "/var/lib/docker",
    "Driver": "btrfs",
    "DriverStatus": [[""]],
    "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": "",
    "KernelMemory": true,
    "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"
        ]
    },
    "SecurityOptions": [
        "apparmor",
        "seccomp",
        "selinux"
    ],
    "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

显示 docker 版本信息

GET /version

显示 docker 版本信息

Example request:

GET /v1.24/version HTTP/1.1

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
     "Version": "1.12.0",
     "Os": "linux",
     "KernelVersion": "3.19.0-23-generic",
     "GoVersion": "go1.6.3",
     "GitCommit": "deadbee",
     "Arch": "amd64",
     "ApiVersion": "1.24",
     "BuildTime": "2016-06-14T07:09:13.444803460+00:00",
     "Experimental": true
}

Status codes:

  • 200 – no error
  • 500 – server error

Ping docker 服务器

GET /_ping

Ping docker 服务器

Example request:

GET /v1.24/_ping HTTP/1.1

Example response:

HTTP/1.1 200 OK
Content-Type: text/plain

OK

Status codes:

  • 200 - no error
  • 500 - server error

从容器的更改创建新映像

POST /commit

从容器的更改创建新映像

Example request:

POST /v1.24/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-容器的配置

Query parameters:

  • container – source container
  • repo – repository
  • tag – tag
  • comment – commit message
  • author作者 (例如,约翰 · 汉尼拔 · 史密斯 <hannibal@a-team.com>")
  • pause-1/True 或 0/False/false,是否在提交前暂停容器
  • changes-Dockerfile 在提交时要应用的说明

Status codes:

  • 201 – no error
  • 404-没有这样的容器
  • 500 – server error

监控 Docker 的活动

GET /events

从 docker 获取容器事件,通过流实时。

Docker 容器报告以下事件:

attach, commit, copy, create, destroy, detach, die, exec_create, exec_detach, exec_start, export, health_status, kill, oom, pause, rename, resize, restart, start, stop, top, unpause, update

Docker images 报告以下事件:

delete, import, load, pull, push, save, tag, untag

Docker 卷报告以下事件:

create, mount, unmount, destroy

Docker 网络报告以下事件:

create, connect, disconnect, destroy

Docker 守护进程报告以下事件:

reload

Example request:

GET /v1.24/events?since=1374067924

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Server: Docker/1.12.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-时间戳。显示自时间戳后创建的所有事件,然后流
  • until-时间戳。显示在给定时间戳之前创建的事件并停止流
  • filters-在事件列表上处理的筛选器 (映射 [string] [] 字符串) 的 json 编码值。可用筛选器:
  • container=<string>; -- 容器过滤
  • event=<string>; -- 要筛选的事件
  • image=<string>; -- 图像过滤
  • label=<string>; -- 图像和容器标签过滤
  • type=<string>; -- either container or image or volume or network or daemon
  • volume=<string>; -- 要过滤的卷
  • network=<string>; -- 网络过滤
  • daemon=<string>; -- 要筛选的守护程序名称或 id

Status codes:

  • 200 – no error
  • 400 - bad parameter
  • 500 – server error

获取包含存储库中的所有图像的 tarball

GET /images/(name)/get

获取一个 tarball,其中包含由指定的存储库的所有图像和元数据。name.

If name是一个特定的名称和标签 (例如 ubuntu: 最新),然后只返回该图像 (及其父母)。如果name是一个图像 ID,同样只返回图像 (及其父级),但在 tarball 中排除了 “重新定位” 文件,因为没有引用图像名称。

See the image tarball format for more details.

Example request

GET /v1.24/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

获取包含所有图像的 tarball

GET /images/get

获取一个包含一个或多个存储库的所有图像和元数据的 tarball。

对于每个值的names参数: 如果它是一个特定的名称和标记 (例如:ubuntu:latest),然后只有该图像 (及其父母) 被返回; 如果它是一个图像 ID,同样只有该图像 (及其父母) 返回,并不会在这个映像 ID 的 “存储库” 文件中引用名称。

See the image tarball format for more details.

Example request

GET /v1.24/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

用一组图像和标签加载到 docker

POST /images/load

将一组图像和标签加载到 Docker 存储库中。查看image tarball format for more details.

Example request

POST /v1.24/images/load
Content-Type: application/x-tar
Content-Length: 12345

Tarball in body

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Transfer-Encoding: chunked

{"status":"Loading layer","progressDetail":{"current":32768,"total":1292800},"progress":"[=                                                 ] 32.77 kB/1.293 MB","id":"8ac8bfaff55a"}
{"status":"Loading layer","progressDetail":{"current":65536,"total":1292800},"progress":"[==                                                ] 65.54 kB/1.293 MB","id":"8ac8bfaff55a"}
{"status":"Loading layer","progressDetail":{"current":98304,"total":1292800},"progress":"[===                                               ]  98.3 kB/1.293 MB","id":"8ac8bfaff55a"}
{"status":"Loading layer","progressDetail":{"current":131072,"total":1292800},"progress":"[=====                                             ] 131.1 kB/1.293 MB","id":"8ac8bfaff55a"}
...
{"stream":"Loaded image: busybox:latest\n"}

Example response:

如果 “安静” 查询参数设置为true / 1 (?quiet=1) 、进度详细信息被抑制,并且只有在操作完成后才返回确认消息。

HTTP/1.1 200 OK
Content-Type: application/json
Transfer-Encoding: chunked

{"stream":"Loaded image: busybox:latest\n"}

Query parameters:

  • quiet-布尔值,在加载期间抑制进度详细信息。默认为0 / false if omitted.

Status codes:

  • 200 – no error
  • 500 – server error

图像 tarball 格式

映像 tarball 每个映像层包含一个目录 (使用其长 ID 命名),每个目录都包含以下文件:

  • VERSION: currently 1.0-文件格式版本
  • json: 详细的层信息,类似于docker inspect layer_id
  • layer.tar: 包含此层文件系统更改的 tarfile

The layer.tar file contains aufs style .wh..wh.aufs用于存储属性更改和删除的文件和目录。

如果 tarball 定义了存储库,则 tarball 还应该包括repositories根目录下的文件,其中包含映射到层 id 的存储库和标记名称的列表。

{"hello-world": {"latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"} }

Exec Create

POST /containers/(id or name)/exec

在正在运行的容器中设置 exec 实例id

Example request:

POST /v1.24/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-布尔值,附加到stdin of the exec command.
  • AttachStdout-布尔值,附加到stdout of the exec command.
  • AttachStderr-布尔值,附加到stderr of the exec command.
  • DetachKeys-重写用于分离容器的键序列。格式是单个字符[a-Z] or ctrl-<value> where <value> is one of: a-z, @, ^, [, , or _.
  • Tty-用于分配伪 TTY 的布尔值。
  • Cmd-命令运行指定为字符串或字符串数组。
  • Privileged-布尔值,以扩展权限运行 exec 进程。
  • User-指定用户的字符串值,也可以选择组运行容器中的 exec 进程。格式是:"user", "user:group", "uid", or "uid:gid".

Status codes:

  • 201 – no error
  • 404-没有这样的容器
  • 409-容器已暂停
  • 500 - server error

Exec Start

POST /exec/(id)/start

启动以前的设置exec instance id. If detach是真的,这个 API 开始后返回exec命令。否则,这个 API 将设置一个交互式会话。exec command.

Example request:

POST /v1.24/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-用于分配伪 TTY 的布尔值。

Status codes:

  • 200 – no error
  • 404-没有这样的执行实例
  • 409-容器已暂停

Stream details:

类似的流行为POST /containers/(id or name)/attach API

Exec Resize

POST /exec/(id)/resize

Resizes the tty会话所使用的exec command id。单位是字符数。这个 API 只有在tty被指定为创建和启动exec command.

Example request:

POST /v1.24/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-没有这样的执行实例

Exec Inspect

GET /exec/(id)/json

返回有关exec command id.

Example request:

GET /v1.24/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-没有这样的执行实例
  • 500 - server error

3.4 Volumes

List volumes

GET /volumes

Example request:

GET /v1.24/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",
      "Labels": null,
      "Scope": "local"
    }
  ],
  "Warnings": []
}

Query parameters:

  • filters-JSON 编码的过滤器值 (amap[string][]string) 在卷列表上处理。可用筛选器:
  • name=<volume-name>匹配卷名称的全部或部分。
  • dangling=<boolean> When set to true (or 1),返回所有 “悬挂” 的卷 (不是由容器使用)。设置为false (or 0),只返回一个或多个容器正在使用的卷。
  • driver=<volume-driver-name>匹配卷驱动程序名称的全部或部分。

Status codes:

  • 200 - no error
  • 500 - server error

Create a volume

POST /volumes/create

Create a volume

Example request:

POST /v1.24/volumes/create HTTP/1.1
Content-Type: application/json
Content-Length: 12345

{
  "Name": "tardis",
  "Labels": {
    "com.example.some-label": "some-value",
    "com.example.some-other-label": "some-other-value"
  },
  "Driver": "custom"
}

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "Name": "tardis",
  "Driver": "custom",
  "Mountpoint": "/var/lib/docker/volumes/tardis",
  "Status": {
    "hello": "world"
  },
  "Labels": {
    "com.example.some-label": "some-value",
    "com.example.some-other-label": "some-other-value"
  },
  "Scope": "local"
}

Status codes:

  • 201 - no error
  • 500 - server error

JSON parameters:

  • Name-新卷的名称。如果未指定,Docker 将生成一个名称。
  • Driver-要使用的卷驱动程序的名称。默认为local for the name.
  • DriverOpts-驱动程序选项和值的映射。这些选项直接传递给驱动程序,并且是驱动程序特定的。
  • Labels-要在卷上设置的标签,指定为地图:{"key":"value","key2":"value2"}

响应的 JSON 字段:

Refer to the inspect a volume响应中返回的 JSON 字段的部分或详细信息。

Inspect a volume

GET /volumes/(name)

返回卷的低水平信息name

Example request:

GET /v1.24/volumes/tardis

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "Name": "tardis",
  "Driver": "custom",
  "Mountpoint": "/var/lib/docker/volumes/tardis/_data",
  "Status": {
    "hello": "world"
  },
  "Labels": {
      "com.example.some-label": "some-value",
      "com.example.some-other-label": "some-other-value"
  },
  "Scope": "local"
}

Status codes:

  • 200 - no error
  • 404 - no such volume
  • 500 - server error

响应的 JSON 字段:

可以在 API 响应中返回以下字段。空字段或卷驱动程序不支持的字段可能会在响应中省略。

  • Name-卷的名称。
  • Driver-卷所使用的卷驱动程序的名称。
  • Mountpoint-在主机上的卷的装载路径。
  • Status-卷驱动程序提供的有关卷的低水平详细信息。详细信息将作为具有键/值对的映射返回:{"key":"value","key2":"value2"}. The Status字段是可选的,如果卷驱动程序不支持此功能,则省略该字段。
  • Labels-在卷上设置的标签,指定为地图:{"key":"value","key2":"value2"}.
  • Scope-适用范围描述卷存在的级别,可以是global集群范围还是?local对于机器级别。默认值为local.

Remove a volume

DELETE /volumes/(name)

指示驱动程序删除卷 (name).

Example request:

DELETE /v1.24/volumes/tardis HTTP/1.1

Example response:

HTTP/1.1 204 No Content

Status codes:

  • 204 - no error
  • 404-没有此类卷或卷驱动程序
  • 409-卷正在使用中,无法删除
  • 500 - server error

3.5 Networks

List networks

GET /networks

Example request:

GET /v1.24/networks?filters={"type":{"custom":true}} HTTP/1.1

Example response:

'HTTP/1.1 200 确定内容类型: 应用程序/json

[{"Name": "bridge","Id": "","Scope": "local","Driver": "bridge","EnableIPv6": false, “内部”: false,“IPAM”: {“驱动程序”: “默认”,“配置”: [{“子网”: “172.170.0/16”}]},"集装箱": {"": {"EndpointID": "","地址": "02: 42: ac: 11: 00: 02", "4address": "172.17.0.2/16"," 6address": "}," 选项 ": {" com.doc ker。网络。布里奇。 default_bridge ":" true "," com.doc ker。网络。布里奇。 enable_icc ":" true "," com.doc ker。网络。布里奇。 enable_ip_masiade ":" true ","考多克。网络。布里奇。 host_binding_ipv4 ":" 0.0.0.0 "," com.doc ker。网络。布里奇。名称: “docker0”,“com.doc ker。网络。司机。 mtu: “1500”},{“名称”: “无”,“Id”: “”,“范围”: “本地”,“驱动程序”: “null”, "EnableIPv6": false,"内部": false,"IPAM":{“驱动程序”: “默认”,“配置”: []},“容器”: {},“选项”: {},{“名称”: “主机”,“Id”: "13e871235c677196c4eecbb9dc733b9b2d2ab530c5efeda84a24215e","适用范围": "本地","驱动程序": "主机","EnableIPv6": false,"内部 “: false,“ IPAM ”: {“ 驱动程序 ”:“ 默认 ”,“ 配置 ”: []},“ 容器 ”: {},“ 选项 ”: {}]

```

Query parameters:

  • filters-JSON 编码网络列表过滤器。筛选器值是:
  • driver=<driver-name>匹配网络的驱动程序。
  • id=<network-id>匹配网络 id 的所有或部分。
  • label=<key> or label=<key>=<value>网络标签的。
  • name=<network-name>匹配网络名称的全部或部分。
  • type=["custom"|"builtin"]按类型筛选网络。Thecustom关键字返回所有用户定义的网络。

Status codes:

  • 200 - no error
  • 500 - server error

Inspect network

GET /networks/(id or name)

返回网络上的低水平信息id

Example request:

GET /v1.24/networks/7d86d31b1478e7cca9ebed7e73aa0fdeec46c5ca29497431d3007d2d9e15ed99 HTTP/1.1

Example response:

'HTTP/1.1 200 确定内容类型: 应用程序/json

{“名称”: “net01”,“Id”: “”,“范围”: “本地”,“驱动程序”: “bridge”,“EnableIPv6”: false, “IPAM”: {“驱动程序”: “默认”,“配置”: [{“子网”: “172.19.0.0/16”,“网关”: “172.19.0.1”}],“选项”: {“foo”: “bar”},“内部”: false,“容器”: {“”: {“名称”: “测试”, "EndpointID": "","MacAddress": "02: 42: ac: 13: 00: 02"," 4address": "172.19.0.2/16"," 6address": ""},"选项": {"com.doc ker。网络。布里奇。 default_bridge ":" true "," com.doc ker。网络。布里奇。 enable_icc ":" true "," com.doc ker。网络。布里奇。 enable_ip_masiade ":" true "," com.doc ker。网络。布里奇。 host_binding_ipv4 ":" 0.0.0.0 "," com.doc ker。网络。布里奇。名称: “docker0”,“com.doc ker。网络。司机。 mtu: “1500”},“标签”: {”com。例如。一些标签 “:“ 一些值 ”,“ com。例如。一些其他标签 ":" 一些其他值 "}}

```

Status codes:

  • 200 - no error
  • 404-找不到网络
  • 500 - server error

Create a network

POST /networks/create

Create a network

Example request:

'POST/v1.24 网络/创建 HTTP/1.1 内容类型: 应用程序/json 内容长度: 12345

{"Name": "isolated_nw","检查重复": true,"Driver": "bridge","EnableIPv6": true,"IPAM": {"Driver": “默认”,“配置”: [{“子网”: “172. 0.0/16”,“iprangge”: “172. 10.0/24”,“网关”: "172. 10.11"},{"子网": "2001: db8: abcd:/64","网关": "2001: db8: abcd: 1011"}], 选项: {"foo": "bar"}},“内部”: true,“选项”: {“com.doc ker。网络。布里奇。 default_bridge ":" true "," com.doc ker。网络。布里奇。 enable_icc ":" true "," com.doc ker。网络。布里奇。 enable_ip_masiade ":" true "," com.doc ker。网络。布里奇。 host_binding_ipv4 ":" 0.0.0.0 "," com.doc ker。网络。布里奇。名称: “docker0”,“com.doc ker。网络。司机。 mtu: “1500”},“标签”: {”com。例如。一些标签 “:“ 一些值 ”,“ com。例如。一些其他标签 ":"一些其他值"}

```

Example response:

'HTTP/1.1 创建的内容类型: 应用程序/json

{“Id”: “22be93d5babb089c5aab8c 42fad48ff791584ca2100db837a1c7c30”,“警告”: “}

```

Status codes:

  • 201 - no error
  • 403-不支持预定义网络的操作
  • 404 - plugin not found
  • 500 - server error

JSON parameters:

  • Name-新网络的名字。这是一个强制字段
  • CheckDuplicate-请求守护程序检查具有相同名称的网络。默认为false。由于网络主要是基于随机 ID 而非名称键,而且网络名称严格地是使用 ID 唯一标识的网络的用户友好别名, 没有保证的方式来检查重复。此参数检查副本是为了提供任何具有相同名称的网络的最佳检查,但不能保证捕获所有名称冲突。
  • Driver-使用网络驱动程序插件的名称。默认为bridge driver
  • Internal-限制对网络的外部访问
  • IPAM-网络的可选自定义 IP 方案
  • Driver-要使用的 IPAM 驱动程序的名称。默认为default driver
  • Config-IPAM 配置选项列表,指定为地图:{"Subnet": <CIDR>, "IPRange": <CIDR>, "Gateway": <IP address>, "AuxAddress": <device_name:IP address>}
  • Options-驱动程序特定选项,指定为地图:{"option":"value" [,"option2":"value2"]}
  • EnableIPv6-在网络上启用 IPv6
  • Options-驱动程序使用的网络特定选项
  • Labels-要在网络上设置的标签,指定为地图:{"key":"value" [,"key2":"value2"]}

将容器连接到网络

POST /networks/(id or name)/connect

将容器连接到网络

Example request:

''POST/v1.24/网络/22be93d5babb089c5aab8c 42fad48ff791584ca2100db837a1c30/连接 HTTP/1.1 内容类型: 应用/json 内容长度: 12345

{“容器”: “3613f73ba0e4”,“端点配置”: {“IPAMConfig”: {“ 4address”: “172.24.56.89”,“ 6address”: “2001: db8: 5689 "}}

```

Example response:

HTTP/1.1 200 OK

Status codes:

  • 200 - no error
  • 403-不支持 swarm 作用域网络的操作
  • 404-找不到网络或容器
  • 500-内部服务器错误

JSON parameters:

  • container-要连接到网络的容器 id/名称

从网络断开容器的连接

POST /networks/(id or name)/disconnect

从网络断开容器的连接

Example request:

''POST/v1.24/网络/22be93d5babb089c5aab8c 42fad48ff791584ca2100db837a1c30/断开 HTTP/1.1 内容类型: 应用/json 内容长度: 12345

{"Container": "3613f73ba0e4","Force": false}

```

Example response:

HTTP/1.1 200 OK

Status codes:

  • 200 - no error
  • 403-不支持 swarm 作用域网络的操作
  • 404-找不到网络或容器
  • 500-内部服务器错误

JSON parameters:

  • Container-要从网络断开连接的容器 id/名称
  • Force-强制容器与网络断开连接

Remove a network

DELETE /networks/(id or name)

指示驱动程序删除网络 (id).

Example request:

DELETE /v1.24/networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30 HTTP/1.1

Example response:

HTTP/1.1 204 No Content

Status codes:

  • 204 - no error
  • 403-不支持预定义网络的操作
  • 404 - no such network
  • 500 - server error

3.6 插件 (实验)

List plugins

GET /plugins

返回有关已安装插件的信息。

Example request:

GET /v1.24/plugins HTTP/1.1

Example response:

'HTTP/1.1 200 确定内容类型: 应用程序/json

[{"Id": "","名称": "tiborvass/no-remove","Tag": "最新","Active": true,"Config": {"mount": [{"Name": "," Description ":","可设置": null,"Source": "/data","目标 ":"/数据 "," 类型 ":" 绑定 "," 选项 ": [" 共享 "," rbind "]},{" 名称 ":", 描述: “”,“可设置”: null,“源”: null,“目标”: “/foobar”,“类型”: “tmpfs”,选项 ": null}]," Env ": [" DEBUG = 1 "]," Args ": null," Devices ": null}," Manifest ": {"清单版本": "v0","描述": "Docker 的测试插件","文档": "https://docs.docker.com/engine/extend/plugins/","接口": {"类型":["Docker。 volumedriver/1.0 “],“ 套接字 ”:“ 插件。 sock "}," Entrypoint ": [插件-无删除","/数据"],"Workdir": "," 用户 ": {}," 网络 ": {"Type": "host"},"capability": null,"mount": [{“名称”: “”,“描述”: “”,“可设置”: null,“源”: “/数据”,“目标”: “/数据”, "类型": "绑定","选项": ["共享","rbind"]},{"名称": "," 描述 ":",“可设置”: null,“源”: null,“目标”: “/foobar”,“类型”: “tmpfs”,“选项”: null}], “设备”: [{“名称”: “设备”,“描述”: “要装入的主机设备”,“可设置”: null,“路径”:"/Dev/cpu_dma_latency"},"Env": [{"Name": "DEBUG","Description": "如果设置,将打印调试消息","可设置": null,"Value": "1"}],"Args": {"Name": "args","Description": "命令行参数",“可设置”: null,“值”: [

    ]
  }
}

} ]

```

Status codes:

  • 200 - no error
  • 500 - server error

Install a plugin

POST /plugins/pull?name=<plugin name>

拉并安装一个插件。安装插件后,可以使用POST /plugins/(plugin name)/enable endpoint.

Example request:

POST /v1.24/plugins/pull?name=tiborvass/no-remove:latest HTTP/1.1

The :latest标记是可选的,如果省略,则用作默认值。当使用这个端点从注册表中拉一个插件时,X-Registry-Auth头可以用于包含 base64-encoded AuthConfig 对象。请参阅create an image更多详情。

Example response:

'HTTP/1.1 200 确定内容类型: 应用程序/json 内容长度: 175

[{"Name": "network","Description": "","Value": ["host"]},{"Name": "mount","Description": "," 值 ": ["/数据 "]},{" 名称 ":" 设备 "," 说明 ":","Value": ["/dev/cpu_dma_latency"]}]

```

Query parameters:

  • name-插件的名字拉。该名称可能包含一个标记或摘要。需要此参数。

Status codes:

  • 200 - no error
  • 500-解析引用时出错/无效存储库/标记: 存储库名称必须至少有一个组件
  • 500-插件已经存在

Inspect a plugin

GET /plugins/(plugin name)

返回有关已安装插件的详细信息。

Example request:

GET /v1.24/plugins/tiborvass/no-remove:latest HTTP/1.1

The :latest标记是可选的,如果省略,则用作默认值。

Example response:

'HTTP/1.1 200 确定内容类型: 应用程序/json

{“Id”: “”,“名称”: “tiborvass/no-remove”,“标记”: “最新”,“活动”: false,“配置”: {"mount": [{"Name": "," Description ":","可设置": null,"Source": "/data","Destination":“/数据”,“类型”: “绑定”,“选项”: [“共享”,“rbind”]},{“名称”: “”,“描述”: "," 可设置 ": null," Source ": null," Destination ":"/foobar "," Type ":" tmpfs "," Options ":Null}],"Env": ["DEBUG = 1"],"Args": null,"设备": null},"清单": {"清单版本": “v0”,“描述”: “Docker 的测试插件”,“文档”: “https://docs.docker.com/engine/extend/plugins/”,“接口”: {“类型”: [”码头工人。 volumedriver/1.0 “],“ 套接字 ”:“ 插件。 sock "}," Entrypoint ": [插件-无删除","/数据"],"Workdir": "," 用户 ": {}," 网络 ": {"Type": "host"},"capability": null,"mount": [{"名称: “”,“描述”: “”,“可设置”: null,“源”: “/数据”,“目标”: “/数据”, “类型”: “绑定”,“选项”: [“共享”,“rbind”]},{“名称”: “”,“描述”: “”,“可设置”: null,“源”: null,“目标”: “/foobar”,“类型”: “tmpfs”,“选项”: null}], “设备”: [{“名称”: “设备”,“描述”: “要装入的主机设备”,“可设置”: null,“路径”:“/Dev/cpu_dma_latency],"Env": [{"Name": "DEBUG","Description": "如果设置,将打印调试消息","可设置": null,"Value": "1"}],"Args": {"Name": "args","Description": "命令行参数","可设置 “: null,” 值: [

  ]
}

} }

```

Status codes:

  • 200 - no error
  • 404-插件未安装

Enable a plugin

POST /plugins/(plugin name)/enable

Enables a plugin

Example request:

POST /v1.24/plugins/tiborvass/no-remove:latest/enable HTTP/1.1

The :latest标记是可选的,如果省略,则用作默认值。

Example response:

HTTP/1.1 200 OK Content-Length: 0 Content-Type: text/plain; charset=utf-8

Status codes:

  • 200 - no error
  • 404-插件未安装
  • 500-插件已经启用

Disable a plugin

POST /plugins/(plugin name)/disable

Disables a plugin

Example request:

POST /v1.24/plugins/tiborvass/no-remove:latest/disable HTTP/1.1

The :latest标记是可选的,如果省略,则用作默认值。

Example response:

HTTP/1.1 200 OK Content-Length: 0 Content-Type: text/plain; charset=utf-8

Status codes:

  • 200 - no error
  • 404-插件未安装
  • 500-插件已经禁用

Remove a plugin

DELETE /plugins/(plugin name)

Removes a plugin

Example request:

DELETE /v1.24/plugins/tiborvass/no-remove:latest HTTP/1.1

The :latest标记是可选的,如果省略,则用作默认值。

Example response:

HTTP/1.1 200 OK Content-Length: 0 Content-Type: text/plain; charset=utf-8

Status codes:

  • 200 - no error
  • 404-插件未安装
  • 500 - plugin is active

3.7 Nodes

Note: 节点操作要求引擎是 swarm 的一部分。

List nodes

GET /nodes

List nodes

Example request:

GET /v1.24/nodes HTTP/1.1

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "ID": "24ifsmvkjbyhk",
    "Version": {
      "Index": 8
    },
    "CreatedAt": "2016-06-07T20:31:11.853781916Z",
    "UpdatedAt": "2016-06-07T20:31:11.999868824Z",
    "Spec": {
      "Name": "my-node",
      "Role": "manager",
      "Availability": "active"
      "Labels": {
          "foo": "bar"
      }
    },
    "Description": {
      "Hostname": "bf3067039e47",
      "Platform": {
        "Architecture": "x86_64",
        "OS": "linux"
      },
      "Resources": {
        "NanoCPUs": 4000000000,
        "MemoryBytes": 8272408576
      },
      "Engine": {
        "EngineVersion": "1.12.0",
        "Labels": {
            "foo": "bar",
        }
        "Plugins": [
          {
            "Type": "Volume",
            "Name": "local"
          },
          {
            "Type": "Network",
            "Name": "bridge"
          }
          {
            "Type": "Network",
            "Name": "null"
          }
          {
            "Type": "Network",
            "Name": "overlay"
          }
        ]
      }
    },
    "Status": {
      "State": "ready"
    },
    "ManagerStatus": {
      "Leader": true,
      "Reachability": "reachable",
      "Addr": "172.17.0.2:2377""
    }
  }
]

Query parameters:

  • filters-过滤器的 JSON 编码值 (amap[string][]string) 在节点列表上进行处理。可用筛选器:
  • id=<node id>
  • label=<engine label>
  • membership=(accepted|pending)`
  • name=<node name>
  • role=(manager|worker)`

Status codes:

  • 200 – no error
  • 406-节点不是群的一部分
  • 500 – server error

Inspect a node

GET /nodes/(id or name)

返回节点上的低水平信息id

Example request:

  GET /v1.24/nodes/24ifsmvkjbyhk HTTP/1.1

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ID": "24ifsmvkjbyhk",
  "Version": {
    "Index": 8
  },
  "CreatedAt": "2016-06-07T20:31:11.853781916Z",
  "UpdatedAt": "2016-06-07T20:31:11.999868824Z",
  "Spec": {
    "Name": "my-node",
    "Role": "manager",
    "Availability": "active"
    "Labels": {
        "foo": "bar"
    }
  },
  "Description": {
    "Hostname": "bf3067039e47",
    "Platform": {
      "Architecture": "x86_64",
      "OS": "linux"
    },
    "Resources": {
      "NanoCPUs": 4000000000,
      "MemoryBytes": 8272408576
    },
    "Engine": {
      "EngineVersion": "1.12.0",
      "Labels": {
          "foo": "bar",
      }
      "Plugins": [
        {
          "Type": "Volume",
          "Name": "local"
        },
        {
          "Type": "Network",
          "Name": "bridge"
        }
        {
          "Type": "Network",
          "Name": "null"
        }
        {
          "Type": "Network",
          "Name": "overlay"
        }
      ]
    }
  },
  "Status": {
    "State": "ready"
  },
  "ManagerStatus": {
    "Leader": true,
    "Reachability": "reachable",
    "Addr": "172.17.0.2:2377""
  }
}

Status codes:

  • 200 – no error
  • 404 – no such node
  • 406-节点不是群的一部分
  • 500 – server error

Remove a node

DELETE /nodes/(id or name)

从群中删除节点。

Example request:

DELETE /v1.24/nodes/24ifsmvkjbyhk HTTP/1.1

Example response:

HTTP/1.1 200 OK
Content-Length: 0
Content-Type: text/plain; charset=utf-8

Query parameters:

  • force-1/True 或 0/False/false,强制从群删除节点。默认false.

Status codes:

  • 200 – no error
  • 404 – no such node
  • 406-节点不是群的一部分
  • 500 – server error

Update a node

POST /nodes/(id)/update

Update a node.

The payload of the POST请求是新的NodeSpec并覆盖当前NodeSpec对于指定节点。

If Availability or Role省略,这将返回一个错误。省略的任何其他字段都将当前值重置为空值或默认的集群范围内值。

Example Request

POST /v1.24/nodes/24ifsmvkjbyhk/update?version=8 HTTP/1.1
Content-Type: application/json
Content-Length: 12345

{
  "Availability": "active",
  "Name": "node-name",
  "Role": "manager",
  "Labels": {
    "foo": "bar"
  }
}

Example response:

HTTP/1.1 200 OK
Content-Length: 0
Content-Type: text/plain; charset=utf-8

Query parameters:

  • version-正在更新的节点对象的版本号。这需要避免冲突的写入。

JSON Parameters:

  • Annotations-与节点关联的可选 medata。Name-节点的用户定义名称。Labels-标签映射与节点关联 (例如,{"key":"value", "key2":"value2"}).
  • Role-节点的角色 (worker | manager)。
  • Availability-节点的可用性 (活动 | 暂停 | 排水)。

Status codes:

  • 200 – no error
  • 404 – no such node
  • 406-节点不是群的一部分
  • 500 – server error

3.8 Swarm

Inspect swarm

GET /swarm

Inspect swarm

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "CreatedAt" : "2016-08-15T16:00:20.349727406Z",
  "Spec" : {
    "Dispatcher" : {
      "HeartbeatPeriod" : 5000000000
    },
    "Orchestration" : {
     "TaskHistoryRetentionLimit" : 10
    },
    "CAConfig" : {
      "NodeCertExpiry" : 7776000000000000
    },
    "Raft" : {
      "LogEntriesForSlowFollowers" : 500,
      "HeartbeatTick" : 1,
      "SnapshotInterval" : 10000,
      "ElectionTick" : 3
    },
    "TaskDefaults" : {},
    "Name" : "default"
  },
 "JoinTokens" : {
    "Worker" : "SWMTKN-1-1h8aps2yszaiqmz2l3oc5392pgk8e49qhx2aj3nyv0ui0hez2a-6qmn92w6bu3jdvnglku58u11a",
    "Manager" : "SWMTKN-1-1h8aps2yszaiqmz2l3oc5392pgk8e49qhx2aj3nyv0ui0hez2a-8llk83c4wm9lwioey2s316r9l"
 },
 "ID" : "70ilmkj2f6sp2137c753w2nmt",
 "UpdatedAt" : "2016-08-15T16:32:09.623207604Z",
 "Version" : {
   "Index" : 51
}

}

Status codes:

  • 200 - no error
  • 406-节点不是群的一部分
  • 500 - sever error

初始化新群体

POST /swarm/init

初始化一个新的群。HTTP 响应的主体包含节点 ID。

Example request:

POST /v1.24/swarm/init HTTP/1.1
Content-Type: application/json
Content-Length: 12345

{
  "ListenAddr": "0.0.0.0:2377",
  "AdvertiseAddr": "192.168.1.1:2377",
  "ForceNewCluster": false,
  "Spec": {
    "Orchestration": {},
    "Raft": {},
    "Dispatcher": {},
    "CAConfig": {}
  }
}

Example response:

HTTP/1.1 200 OK
Content-Length: 28
Content-Type: application/json
Date: Thu, 01 Sep 2016 21:49:13 GMT
Server: Docker/1.12.0 (linux)

"7v2t30z9blmxuhnyo6s4cpenp"

Status codes:

  • 200 – no error
  • 400 – bad parameter
  • 406-节点已经是群的一部分
  • 500 - server error

JSON Parameters:

  • ListenAddr-用于管理器间通信的侦听地址,以及确定用于 VXLAN 隧道端点 (VTEP) 的网络接口。这可以是一个地址/端口组合的形式192.168.1.1:4567,或一个接口,后跟一个端口号,如eth0:4567。如果省略了端口号,则使用默认的 swarm 侦听端口。
  • AdvertiseAddr-外部可访问地址通告到其他节点。这可以是一个地址/端口组合的形式192.168.1.1:4567,或一个接口,后跟一个端口号,如eth0:4567。如果省略了端口号,则使用侦听地址中的端口号。如果AdvertiseAddr未指定,可能时将自动检测到。
  • ForceNewCluster-力量创建一个新的群体。
  • Spec-新群体的配置设置。Orchestration-Swarm 的编排方面的配置设置。TaskHistoryRetentionLimit-存储的最大任务历史记录数。Raft-筏相关配置。SnapshotInterval-快照之间的日志条目数。KeepOldSnapshots-要超过当前快照的快照数量。LogEntriesForSlowFollowers-在创建快照后保持同步的日志条目数量。HeartbeatTick-每个心跳之间的滴答量 (秒)。ElectionTick-不需要领导就可以触发新的选举所需的滴答数 (秒)。Dispatcher-任务调度程序的配置设置。HeartbeatPeriod-代理发送心跳到调度程序的延迟。CAConfig-证书颁发机构配置。NodeCertExpiry-节点证书自动过期。ExternalCA-用于将签名请求转发到外部证书颁发机构的配置。Protocol-与外部 CA 通信的协议 (目前只支持 “cfssl”)。URL-应发送证书签名请求的 URL。Options-具有键/值对的对象,这些对象被解释为外部 CA 驱动程序的协议特定选项。

加入现有的 swarm

POST /swarm/join

加入现有的 swarm

Example request:

POST /v1.24/swarm/join HTTP/1.1
Content-Type: application/json

{
  "ListenAddr": "0.0.0.0:2377",
  "AdvertiseAddr": "192.168.1.1:2377",
  "RemoteAddrs": ["node1:2377"],
  "JoinToken": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2"
}

Example response:

HTTP/1.1 200 OK
Content-Length: 0
Content-Type: text/plain; charset=utf-8

Status codes:

  • 200 – no error
  • 400 – bad parameter
  • 406-节点已经是群的一部分
  • 500 - server error

JSON Parameters:

  • ListenAddr-当节点提升为管理器时用于跨管理器通信的侦听地址,以及确定用于 VXLAN 隧道端点 (VTEP) 的网络接口。
  • AdvertiseAddr-外部可访问地址通告到其他节点。这可以是一个地址/端口组合的形式192.168.1.1:4567,或一个接口,后跟一个端口号,如eth0:4567。如果省略了端口号,则使用侦听地址中的端口号。如果AdvertiseAddr未指定,可能时将自动检测到。
  • RemoteAddr-已参与 swarm 的任何 manager 节点的地址。
  • JoinToken-加入这个群体的秘密令牌。

Leave a swarm

POST /swarm/leave

Leave a swarm

Example request:

POST /v1.24/swarm/leave HTTP/1.1

Example response:

HTTP/1.1 200 OK
Content-Length: 0
Content-Type: text/plain; charset=utf-8

Query parameters:

  • force布尔 (0/1,false/true)。强制离开群,即使这是最后一个管理器或它将打破集群。

Status codes:

  • 200 – no error
  • 406-节点不是群的一部分
  • 500 - server error

Update a swarm

POST /swarm/update

Update a swarm

Example request:

POST /v1.24/swarm/update HTTP/1.1
Content-Length: 12345

{
  "Name": "default",
  "Orchestration": {
    "TaskHistoryRetentionLimit": 10
  },
  "Raft": {
    "SnapshotInterval": 10000,
    "LogEntriesForSlowFollowers": 500,
    "HeartbeatTick": 1,
    "ElectionTick": 3
  },
  "Dispatcher": {
    "HeartbeatPeriod": 5000000000
  },
  "CAConfig": {
    "NodeCertExpiry": 7776000000000000
  },
  "JoinTokens": {
    "Worker": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-1awxwuwd3z9j1z3puu7rcgdbx",
    "Manager": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2"
  }
}

Example response:

HTTP/1.1 200 OK
Content-Length: 0
Content-Type: text/plain; charset=utf-8

Query parameters:

  • version-正在更新的 swarm 对象的版本号。这需要避免冲突的写入。
  • rotateWorkerToken - Set to true (or 1) 旋转工作加入令牌。
  • rotateManagerToken - Set to true (or 1) 旋转管理器连接令牌。

Status codes:

  • 200 – no error
  • 400 – bad parameter
  • 406-节点不是群的一部分
  • 500 - server error

JSON Parameters:

  • Orchestration-Swarm 的编排方面的配置设置。TaskHistoryRetentionLimit-存储的最大任务历史记录数。
  • Raft-筏相关配置。SnapshotInterval-快照之间的日志条目数。KeepOldSnapshots-要超过当前快照的快照数量。LogEntriesForSlowFollowers-在创建快照后保持同步的日志条目数量。HeartbeatTick-每个心跳之间的滴答量 (秒)。ElectionTick-不需要领导就可以触发新的选举所需的滴答数 (秒)。
  • Dispatcher-任务调度程序的配置设置。HeartbeatPeriod-代理发送心跳到调度程序的延迟。
  • CAConfig-CA 配置。NodeCertExpiry-节点证书自动过期。ExternalCA-用于将签名请求转发到外部证书颁发机构的配置。Protocol-与外部 CA 通信的协议 (目前只支持 “cfssl”)。URL-应发送证书签名请求的 URL。Options-具有键/值对的对象,这些对象被解释为外部 CA 驱动程序的协议特定选项。
  • JoinTokens-其他节点可以使用的令牌加入群。Worker-令牌用于作为一个工人加入。Manager-作为经理加入使用的令牌。

3.9 Services

Note: 服务业务首先需要成为群体的一部分。

List services

GET /services

List services

Example request:

GET /v1.24/services HTTP/1.1

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "ID": "9mnpnzenvg8p8tdbtq4wvbkcz",
    "Version": {
      "Index": 19
    },
    "CreatedAt": "2016-06-07T21:05:51.880065305Z",
    "UpdatedAt": "2016-06-07T21:07:29.962229872Z",
    "Spec": {
      "Name": "hopeful_cori",
      "TaskTemplate": {
        "ContainerSpec": {
          "Image": "redis"
        },
        "Resources": {
          "Limits": {},
          "Reservations": {}
        },
        "RestartPolicy": {
          "Condition": "any",
          "MaxAttempts": 0
        },
        "Placement": {
          "Constraints": [
            "node.role == worker"
          ]
        }
      },
      "Mode": {
        "Replicated": {
          "Replicas": 1
        }
      },
      "UpdateConfig": {
        "Parallelism": 1,
        "FailureAction": "pause"
      },
      "EndpointSpec": {
        "Mode": "vip",
        "Ports": [
          {
            "Protocol": "tcp",
            "TargetPort": 6379,
            "PublishedPort": 30001
          }
        ]
      }
    },
    "Endpoint": {
      "Spec": {
        "Mode": "vip",
        "Ports": [
          {
            "Protocol": "tcp",
            "TargetPort": 6379,
            "PublishedPort": 30001
          }
        ]
      },
      "Ports": [
        {
          "Protocol": "tcp",
          "TargetPort": 6379,
          "PublishedPort": 30001
        }
      ],
      "VirtualIPs": [
        {
          "NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
          "Addr": "10.255.0.2/16"
        },
        {
          "NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
          "Addr": "10.255.0.3/16"
        }
      ]
    }
  }
]

Query parameters:

  • filters-过滤器的 JSON 编码值 (amap[string][]string) 在服务列表上处理。可用筛选器:
  • id=<service id>
  • label=<service label>
  • name=<service name>

Status codes:

  • 200 – no error
  • 406-节点不是群的一部分
  • 500 – server error

Create a service

POST /services/create

创建服务。当使用此终结点使用注册表中的私有存储库创建服务时,X-Registry-Auth头必须用于包含 base64-encoded AuthConfig 对象。请参阅create an image更多详情。

Example request:

POST /v1.24/services/create HTTP/1.1
Content-Type: application/json
Content-Length: 12345

{
  "Name": "web",
  "TaskTemplate": {
    "ContainerSpec": {
      "Image": "nginx:alpine",
      "Mounts": [
        {
          "ReadOnly": true,
          "Source": "web-data",
          "Target": "/usr/share/nginx/html",
          "Type": "volume",
          "VolumeOptions": {
            "DriverConfig": {
            },
            "Labels": {
              "com.example.something": "something-value"
            }
          }
        }
      ],
      "User": "33"
    },
    "Networks": [
        {
          "Target": "overlay1"
        }
    ],
    "LogDriver": {
      "Name": "json-file",
      "Options": {
        "max-file": "3",
        "max-size": "10M"
      }
    },
    "Placement": {
      "Constraints": [
        "node.role == worker"
      ]
    },
    "Resources": {
      "Limits": {
        "MemoryBytes": 104857600
      },
      "Reservations": {
      }
    },
    "RestartPolicy": {
      "Condition": "on-failure",
      "Delay": 10000000000,
      "MaxAttempts": 10
    }
  },
  "Mode": {
    "Replicated": {
      "Replicas": 4
    }
  },
  "UpdateConfig": {
    "Delay": 30000000000,
    "Parallelism": 2,
    "FailureAction": "pause"
  },
  "EndpointSpec": {
    "Ports": [
      {
        "Protocol": "tcp",
        "PublishedPort": 8080,
        "TargetPort": 80
      }
    ]
  },
  "Labels": {
    "foo": "bar"
  }
}

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "ID":"ak7w3gjqoa3kuz8xcpnyy0pvl"
}

Status codes:

  • 201 – no error
  • 403-网络不享受服务
  • 406-节点不是群的一部分
  • 409-与现有对象的名称冲突
  • 500 - server error

JSON Parameters:

  • Name-服务的用户定义名称。
  • Labels-标签与服务相关联的地图 (例如,{"key":"value", "key2":"value2"}).
  • TaskTemplate-规范新服务的部分任务。ContainerSpec-容器的容器设置开始作为这个任务的一部分。Image-指定要用于容器的图像名称的字符串。Command-要在图像中运行的命令。Args-命令的参数。Env-环境变量的列表,以["VAR=value"[,"VAR2=value2"]].Dir-指定要运行的命令的工作目录的字符串。User-指定容器中的用户的字符串值。Labels-标签与服务相关联的地图 (例如,{"key":"value", "key2":"value2"}).Mounts-将挂载添加到作为服务的一部分创建的容器的规范。Target – Container path.Source-装入源 (例如,卷名,主机路径)。Type – The mount type (bind, or volume).ReadOnly-一个布尔值,指示装入是否应该是只读的。BindOptions-可选的配置bind type.Propagation-具有值的传播模式[r]private, [r]shared, or [r]slave.VolumeOptions-可选的配置volume type.NoCopy-一个布尔值,指示是否应使用目标中的数据填充卷。(默认为 false)Labels-卷的用户定义名称和标签。DriverConfig-驱动程序特定选项的地图。Name-用于创建卷的驱动程序的名称。Options-驱动程序特定选项的键/值映射。StopGracePeriod-等待容器终止之前强制杀死它的时间。LogDriver-为服务的一部分创建的容器的日志配置。Name-要使用的日志驱动程序的名称 (json-file, syslog, journald, gelf, fluentd, awslogs, splunk, etwlogs, none).Options-驱动程序特定选项。Resources-资源需求,适用于作为服务的一部分创建的每个容器。Limits-定义资源限制。NanoCPUs-CPU 限制在 10 单位-9 CPU shares.MemoryBytes-内存限制 (以字节为单位)。Reservation-定义资源保留。NanoCPUs-CPU 预留 10 单位-9 CPU shares.MemoryBytes-内存预留字节。RestartPolicy-适用于作为此服务的一部分创建的容器的重新启动策略的规范。Condition-重新启动的条件 (none, on-failure, or any).Delay-重启尝试之间的延迟。MaxAttempts-放弃之前重新启动给定容器的最大尝试次数 (默认值为 0,被忽略)。Window-Windows 是用于评估重新启动策略的时间窗口 (默认值为 0,这是无界的)。Placement-对服务可以运行的地方的限制。Constraints-一个约束数组,例如[ "node.role == manager" ].
  • Mode-服务的调度模式 (replicated or global, defaults to replicated).
  • UpdateConfig-服务更新策略规范。Parallelism-在一个迭代中要更新的任务的最大数量 (0 意味着无限的并行)。Delay-更新之间的时间。FailureAction-如果更新的任务无法运行,或在更新期间停止运行,则采取的操作。值是continue and pause.
  • Networks-将服务附加到的网络名称或 id 的数组。
  • EndpointSpec-可以配置为访问和负载平衡服务的属性。Mode-用于任务之间的内部负载平衡的分辨率模式 (vip or dnsrr). Defaults to vip if not provided.Ports-从外部访问此服务的公开端口列表,以:{"Protocol": <"tcp"|"udp">, "PublishedPort": <port>, "TargetPort": <port>}。只有在vip使用分辨率模式。

Request Headers:

  • Content-type – Set to "application/json".
  • X-Registry-Auth-Base64-encoded AuthConfig 对象,包含登录信息或令牌。请参阅create an image更多详情。

Remove a service

DELETE /services/(id or name)

停止并删除服务id

Example request:

DELETE /v1.24/services/16253994b7c4 HTTP/1.1

Example response:

HTTP/1.1 200 OK
Content-Length: 0
Content-Type: text/plain; charset=utf-8

Status codes:

  • 200 – no error
  • 404 – no such service
  • 406-节点不是群的一部分
  • 500 – server error

检查一个或多个服务

GET /services/(id or name)

返回服务信息id.

Example request:

GET /v1.24/services/1cb4dnqcyx6m66g2t538x3rxha HTTP/1.1

Example response:

{
  "ID": "ak7w3gjqoa3kuz8xcpnyy0pvl",
  "Version": {
    "Index": 95
  },
  "CreatedAt": "2016-06-07T21:10:20.269723157Z",
  "UpdatedAt": "2016-06-07T21:10:20.276301259Z",
  "Spec": {
    "Name": "redis",
    "TaskTemplate": {
      "ContainerSpec": {
        "Image": "redis"
      },
      "Resources": {
        "Limits": {},
        "Reservations": {}
      },
      "RestartPolicy": {
        "Condition": "any",
        "MaxAttempts": 0
      },
      "Placement": {}
    },
    "Mode": {
      "Replicated": {
        "Replicas": 1
      }
    },
    "UpdateConfig": {
      "Parallelism": 1,
      "FailureAction": "pause"
    },
    "EndpointSpec": {
      "Mode": "vip",
      "Ports": [
        {
          "Protocol": "tcp",
          "TargetPort": 6379,
          "PublishedPort": 30001
        }
      ]
    }
  },
  "Endpoint": {
    "Spec": {
      "Mode": "vip",
      "Ports": [
        {
          "Protocol": "tcp",
          "TargetPort": 6379,
          "PublishedPort": 30001
        }
      ]
    },
    "Ports": [
      {
        "Protocol": "tcp",
        "TargetPort": 6379,
        "PublishedPort": 30001
      }
    ],
    "VirtualIPs": [
      {
        "NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
        "Addr": "10.255.0.4/16"
      }
    ]
  }
}

Status codes:

  • 200 – no error
  • 404 – no such service
  • 406-节点不是群的一部分
  • 500 – server error

Update a service

POST /services/(id)/update

更新服务。当使用此终结点使用注册表中的私有存储库创建服务时,X-Registry-Auth头可以用于更新为服务存储的身份验证信息。标头包含一个 base64-encoded AuthConfig 对象。请参阅create an image更多详情。

Example request:

POST /v1.24/services/1cb4dnqcyx6m66g2t538x3rxha/update?version=23 HTTP/1.1
Content-Type: application/json
Content-Length: 12345

{
  "Name": "top",
  "TaskTemplate": {
    "ContainerSpec": {
      "Image": "busybox",
      "Args": [
        "top"
      ]
    },
    "Resources": {
      "Limits": {},
      "Reservations": {}
    },
    "RestartPolicy": {
      "Condition": "any",
      "MaxAttempts": 0
    },
    "Placement": {}
  },
  "Mode": {
    "Replicated": {
      "Replicas": 1
    }
  },
  "UpdateConfig": {
    "Parallelism": 1
  },
  "EndpointSpec": {
    "Mode": "vip"
  }
}

Example response:

HTTP/1.1 200 OK
Content-Length: 0
Content-Type: text/plain; charset=utf-8

JSON Parameters:

  • Name-服务的用户定义名称。请注意,不支持重命名服务。
  • Labels-标签与服务相关联的地图 (例如,{"key":"value", "key2":"value2"}).
  • TaskTemplate-规范新服务的部分任务。ContainerSpec-容器的容器设置开始作为这个任务的一部分。Image-指定要用于容器的图像名称的字符串。Command-要在图像中运行的命令。Args-命令的参数。Env-环境变量的列表,以["VAR=value"[,"VAR2=value2"]].Dir-指定要运行的命令的工作目录的字符串。User-指定容器中的用户的字符串值。Labels-标签与服务相关联的地图 (例如,{"key":"value", "key2":"value2"}).Mounts-将挂载添加到作为新服务的一部分创建的容器的规范。Target – Container path.Source-装入源 (例如,卷名,主机路径)。Type – The mount type (bind, or volume).ReadOnly-一个布尔值,指示装入是否应该是只读的。BindOptions-可选的配置bind typePropagation-具有值的传播模式[r]private, [r]shared, or [r]slave.VolumeOptions-可选的配置volume type.NoCopy-一个布尔值,指示是否应使用目标中的数据填充卷。(默认为 false)Labels-卷的用户定义名称和标签。DriverConfig-驱动程序特定选项的地图。Name-用于创建卷的驱动程序的名称Options-驱动程序特定选项的键/值映射StopGracePeriod-等待容器终止之前强制杀死它的时间。Resources-资源需求,适用于作为服务的一部分创建的每个容器。Limits-定义资源限制。CPU – CPU limitMemory – Memory limitReservation-定义资源保留。CPU – CPU reservationMemory-内存预留RestartPolicy-适用于作为此服务的一部分创建的容器的重新启动策略的规范。Condition-重新启动的条件 (none, on-failure, or any).Delay-重启尝试之间的延迟。MaxAttempts-放弃之前重新启动给定容器的最大尝试次数 (默认值为 0,被忽略)。Window-Windows 是用于评估重新启动策略的时间窗口 (默认值为 0,这是无界的)。Placement-对服务可以运行的地方的限制。Constraints-一个约束数组,例如[ "node.role == manager" ].
  • Mode-服务的调度模式 (replicated or global, defaults to replicated).
  • UpdateConfig-服务更新策略规范。Parallelism-在一个迭代中要更新的任务的最大数量 (0 意味着无限的并行)。Delay-更新之间的时间。
  • Networks-将服务附加到的网络名称或 id 的数组。
  • EndpointSpec-可以配置为访问和负载平衡服务的属性。Mode-用于任务之间的内部负载平衡的分辨率模式 (vip or dnsrr). Defaults to vip if not provided.Ports-从外部访问此服务的公开端口列表,以:{"Protocol": <"tcp"|"udp">, "PublishedPort": <port>, "TargetPort": <port>}。只有在vip使用分辨率模式。

Query parameters:

  • version-正在更新的服务对象的版本号。这需要避免冲突的写入。

Request Headers:

  • Content-type – Set to "application/json".
  • X-Registry-Auth-Base64-encoded AuthConfig 对象,包含登录信息或令牌。请参阅create an image更多详情。

Status codes:

  • 200 – no error
  • 404 – no such service
  • 406-节点不是群的一部分
  • 500 – server error

3.10 Tasks

Note: 任务操作要求引擎是群的一部分。

List tasks

GET /tasks

List tasks

Example request:

GET /v1.24/tasks HTTP/1.1

Example response:

[
  {
    "ID": "0kzzo1i0y4jz6027t0k7aezc7",
    "Version": {
      "Index": 71
    },
    "CreatedAt": "2016-06-07T21:07:31.171892745Z",
    "UpdatedAt": "2016-06-07T21:07:31.376370513Z",
    "Spec": {
      "ContainerSpec": {
        "Image": "redis"
      },
      "Resources": {
        "Limits": {},
        "Reservations": {}
      },
      "RestartPolicy": {
        "Condition": "any",
        "MaxAttempts": 0
      },
      "Placement": {}
    },
    "ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
    "Slot": 1,
    "NodeID": "60gvrl6tm78dmak4yl7srz94v",
    "Status": {
      "Timestamp": "2016-06-07T21:07:31.290032978Z",
      "State": "running",
      "Message": "started",
      "ContainerStatus": {
        "ContainerID": "e5d62702a1b48d01c3e02ca1e0212a250801fa8d67caca0b6f35919ebc12f035",
        "PID": 677
      }
    },
    "DesiredState": "running",
    "NetworksAttachments": [
      {
        "Network": {
          "ID": "4qvuz4ko70xaltuqbt8956gd1",
          "Version": {
            "Index": 18
          },
          "CreatedAt": "2016-06-07T20:31:11.912919752Z",
          "UpdatedAt": "2016-06-07T21:07:29.955277358Z",
          "Spec": {
            "Name": "ingress",
            "Labels": {
              "com.docker.swarm.internal": "true"
            },
            "DriverConfiguration": {},
            "IPAMOptions": {
              "Driver": {},
              "Configs": [
                {
                  "Subnet": "10.255.0.0/16",
                  "Gateway": "10.255.0.1"
                }
              ]
            }
          },
          "DriverState": {
            "Name": "overlay",
            "Options": {
              "com.docker.network.driver.overlay.vxlanid_list": "256"
            }
          },
          "IPAMOptions": {
            "Driver": {
              "Name": "default"
            },
            "Configs": [
              {
                "Subnet": "10.255.0.0/16",
                "Gateway": "10.255.0.1"
              }
            ]
          }
        },
        "Addresses": [
          "10.255.0.10/16"
        ]
      }
    ],
  },
  {
    "ID": "1yljwbmlr8er2waf8orvqpwms",
    "Version": {
      "Index": 30
    },
    "CreatedAt": "2016-06-07T21:07:30.019104782Z",
    "UpdatedAt": "2016-06-07T21:07:30.231958098Z",
    "Name": "hopeful_cori",
    "Spec": {
      "ContainerSpec": {
        "Image": "redis"
      },
      "Resources": {
        "Limits": {},
        "Reservations": {}
      },
      "RestartPolicy": {
        "Condition": "any",
        "MaxAttempts": 0
      },
      "Placement": {}
    },
    "ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
    "Slot": 1,
    "NodeID": "60gvrl6tm78dmak4yl7srz94v",
    "Status": {
      "Timestamp": "2016-06-07T21:07:30.202183143Z",
      "State": "shutdown",
      "Message": "shutdown",
      "ContainerStatus": {
        "ContainerID": "1cf8d63d18e79668b0004a4be4c6ee58cddfad2dae29506d8781581d0688a213"
      }
    },
    "DesiredState": "shutdown",
    "NetworksAttachments": [
      {
        "Network": {
          "ID": "4qvuz4ko70xaltuqbt8956gd1",
          "Version": {
            "Index": 18
          },
          "CreatedAt": "2016-06-07T20:31:11.912919752Z",
          "UpdatedAt": "2016-06-07T21:07:29.955277358Z",
          "Spec": {
            "Name": "ingress",
            "Labels": {
              "com.docker.swarm.internal": "true"
            },
            "DriverConfiguration": {},
            "IPAMOptions": {
              "Driver": {},
              "Configs": [
                {
                  "Subnet": "10.255.0.0/16",
                  "Gateway": "10.255.0.1"
                }
              ]
            }
          },
          "DriverState": {
            "Name": "overlay",
            "Options": {
              "com.docker.network.driver.overlay.vxlanid_list": "256"
            }
          },
          "IPAMOptions": {
            "Driver": {
              "Name": "default"
            },
            "Configs": [
              {
                "Subnet": "10.255.0.0/16",
                "Gateway": "10.255.0.1"
              }
            ]
          }
        },
        "Addresses": [
          "10.255.0.5/16"
        ]
      }
    ]
  }
]

Query parameters:

  • filters-过滤器的 JSON 编码值 (amap[string][]string) 在服务列表上处理。可用筛选器:
  • id=<task id>
  • name=<task name>
  • service=<service name>
  • node=<node id or name>
  • label=key or label="key=value"
  • desired-state=(running | shutdown | accepted)

Status codes:

  • 200 – no error
  • 406-节点不是群的一部分
  • 500 – server error

Inspect a task

GET /tasks/(id)

获取任务的详细信息id

Example request:

GET /v1.24/tasks/0kzzo1i0y4jz6027t0k7aezc7 HTTP/1.1

Example response:

{
  "ID": "0kzzo1i0y4jz6027t0k7aezc7",
  "Version": {
    "Index": 71
  },
  "CreatedAt": "2016-06-07T21:07:31.171892745Z",
  "UpdatedAt": "2016-06-07T21:07:31.376370513Z",
  "Spec": {
    "ContainerSpec": {
      "Image": "redis"
    },
    "Resources": {
      "Limits": {},
      "Reservations": {}
    },
    "RestartPolicy": {
      "Condition": "any",
      "MaxAttempts": 0
    },
    "Placement": {}
  },
  "ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
  "Slot": 1,
  "NodeID": "60gvrl6tm78dmak4yl7srz94v",
  "Status": {
    "Timestamp": "2016-06-07T21:07:31.290032978Z",
    "State": "running",
    "Message": "started",
    "ContainerStatus": {
      "ContainerID": "e5d62702a1b48d01c3e02ca1e0212a250801fa8d67caca0b6f35919ebc12f035",
      "PID": 677
    }
  },
  "DesiredState": "running",
  "NetworksAttachments": [
    {
      "Network": {
        "ID": "4qvuz4ko70xaltuqbt8956gd1",
        "Version": {
          "Index": 18
        },
        "CreatedAt": "2016-06-07T20:31:11.912919752Z",
        "UpdatedAt": "2016-06-07T21:07:29.955277358Z",
        "Spec": {
          "Name": "ingress",
          "Labels": {
            "com.docker.swarm.internal": "true"
          },
          "DriverConfiguration": {},
          "IPAMOptions": {
            "Driver": {},
            "Configs": [
              {
                "Subnet": "10.255.0.0/16",
                "Gateway": "10.255.0.1"
              }
            ]
          }
        },
        "DriverState": {
          "Name": "overlay",
          "Options": {
            "com.docker.network.driver.overlay.vxlanid_list": "256"
          }
        },
        "IPAMOptions": {
          "Driver": {
            "Name": "default"
          },
          "Configs": [
            {
              "Subnet": "10.255.0.0/16",
              "Gateway": "10.255.0.1"
            }
          ]
        }
      },
      "Addresses": [
        "10.255.0.10/16"
      ]
    }
  ]
}

Status codes:

  • 200 – no error
  • 404 – unknown task
  • 406-节点不是群的一部分
  • 500 – server error

4. Going further

4.1 Inside docker run

As an example, the docker run命令行进行以下 API 调用:

  • 创建容器
  • 如果状态代码是 404,这意味着图像不存在:Try to pull it.然后,重试创建容器。
  • 启动容器。
  • 如果您不处于分离模式:
  • 附加到容器,使用logs=1 (to have stdout and stderr从容器的开始) 和stream=1
  • 如果处于分离模式或仅stdin已附加,显示容器的 id。

4.2 Hijacking

在这个版本的 API 中,/attach,利用劫持来运输stdin, stdout, and stderr在同一个套接字上。

要提示连接劫持的潜在代理,Docker 客户端发送连接升级头类似 websocket。

Upgrade: tcp
Connection: Upgrade

当 Docker 守护程序检测到Upgrade头,它将其状态代码从200 OK to 101 UPGRADED并重新发送相同的标题。

4.3 CORS Requests

若要将交叉原点请求设置为引擎 API,请向--api-cors-header在守护进程模式下运行 Docker 时。设置 * (星号) 允许所有,默认或空白意味着 CORS 禁用

$ dockerd -H="192.168.1.9:2375" --api-cors-header="http://foo.bar"