From 5d72b7a5820de2a7ae46f2017f645bc5e8357a7d Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Tue, 3 Nov 2015 14:03:18 +0100 Subject: [PATCH] docs: update remote API responses and minor fixes Add back the "old" networksettings fields that were removed, but added back to maintain backward compatibility, in https://github.com/docker/docker/pull/17538 Update network endpoint responses, with updated response introduced in; https://github.com/docker/docker/pull/17536 Added changes to v1.22 that were applied to the v1.21 / v1.20 docs after the API bump(s); https://github.com/docker/docker/pull/17085 https://github.com/docker/docker/pull/17127 https://github.com/docker/docker/pull/13707 Also fixed some mixed tab/spaces indentation and Markdown formatting issues (causing code-blocks to be rendered incorrectly) Signed-off-by: Sebastiaan van Stijn (cherry picked from commit 286fe69d5376add77dc31833dc3c2fcc9639dd17) Conflicts: docs/reference/api/docker_remote_api_v1.22.md --- docs/reference/api/docker_remote_api.md | 10 + docs/reference/api/docker_remote_api_v1.20.md | 8 +- docs/reference/api/docker_remote_api_v1.21.md | 361 ++++++++++-------- 3 files changed, 223 insertions(+), 156 deletions(-) diff --git a/docs/reference/api/docker_remote_api.md b/docs/reference/api/docker_remote_api.md index 27e1c3ae0..dfeb51633 100644 --- a/docs/reference/api/docker_remote_api.md +++ b/docs/reference/api/docker_remote_api.md @@ -111,6 +111,16 @@ list of DNS options to be used in the container. * `GET /containers/json` will return `ImageID` of the image used by container. * `POST /exec/(name)/start` will now return an HTTP 409 when the container is either stopped or paused. * `GET /containers/(name)/json` now accepts a `size` parameter. Setting this parameter to '1' returns container size information in the `SizeRw` and `SizeRootFs` fields. +* `GET /containers/(name)/json` now returns a `NetworkSettings.Networks` field, + detailing network settings per network. This field deprecates the + `NetworkSettings.Gateway`, `NetworkSettings.IPAddress`, + `NetworkSettings.IPPrefixLen`, and `NetworkSettings.MacAddress` fields, which + are still returned for backward-compatibility, but will be removed in a future version. +* `GET /exec/(id)/json` now returns a `NetworkSettings.Networks` field, + detailing networksettings per network. This field deprecates the + `NetworkSettings.Gateway`, `NetworkSettings.IPAddress`, + `NetworkSettings.IPPrefixLen`, and `NetworkSettings.MacAddress` fields, which + are still returned for backward-compatibility, but will be removed in a future version. ### v1.20 API changes diff --git a/docs/reference/api/docker_remote_api_v1.20.md b/docs/reference/api/docker_remote_api_v1.20.md index d5dabc761..80103965d 100644 --- a/docs/reference/api/docker_remote_api_v1.20.md +++ b/docs/reference/api/docker_remote_api_v1.20.md @@ -217,7 +217,7 @@ Json Parameters: for the container. - **User** - A string value specifying the user inside the container. - **Memory** - Memory limit in bytes. -- **MemorySwap**- Total memory limit (memory + swap); set `-1` to disable swap +- **MemorySwap** - Total memory limit (memory + swap); set `-1` to disable swap You must use this with `memory` and make the swap value larger than `memory`. - **CpuShares** - An integer value containing the container's CPU Shares (ie. the relative weight vs other containers). @@ -2141,12 +2141,12 @@ Status Codes: `POST /exec/(id)/resize` -Resizes the `tty` session used by the `exec` command `id`. +Resizes the `tty` session used by the `exec` command `id`. The unit is number of characters. This API is valid only if `tty` was specified as part of creating and starting the `exec` command. **Example request**: - POST /exec/e90e34656806/resize HTTP/1.1 + POST /exec/e90e34656806/resize?h=40&w=80 HTTP/1.1 Content-Type: text/plain **Example response**: @@ -2257,7 +2257,7 @@ Return low-level information about the `exec` command `id`. "ProcessLabel" : "", "AppArmorProfile" : "", "RestartCount" : 0, - "Mounts" : [], + "Mounts" : [] } } diff --git a/docs/reference/api/docker_remote_api_v1.21.md b/docs/reference/api/docker_remote_api_v1.21.md index 92a2c3eb6..2322e7957 100644 --- a/docs/reference/api/docker_remote_api_v1.21.md +++ b/docs/reference/api/docker_remote_api_v1.21.md @@ -46,7 +46,7 @@ List containers "Id": "8dfafdbc3a40", "Names":["/boring_feynman"], "Image": "ubuntu:latest", - "ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82", + "ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82", "Command": "echo 1", "Created": 1367854155, "Status": "Exit 0", @@ -63,7 +63,7 @@ List containers "Id": "9cd87474be90", "Names":["/coolName"], "Image": "ubuntu:latest", - "ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82", + "ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82", "Command": "echo 222222", "Created": 1367854155, "Status": "Exit 0", @@ -76,7 +76,7 @@ List containers "Id": "3176a2479c92", "Names":["/sleepy_dog"], "Image": "ubuntu:latest", - "ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82", + "ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82", "Command": "echo 3333333333333333", "Created": 1367854154, "Status": "Exit 0", @@ -89,7 +89,7 @@ List containers "Id": "4cb07b47f9fb", "Names":["/running_cat"], "Image": "ubuntu:latest", - "ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82", + "ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82", "Command": "echo 444444444444444444444444444444444", "Created": 1367854152, "Status": "Exit 0", @@ -204,7 +204,7 @@ Create a container "LogConfig": { "Type": "json-file", "Config": {} }, "SecurityOpt": [""], "CgroupParent": "", - "VolumeDriver": "" + "VolumeDriver": "" } } @@ -439,15 +439,23 @@ Return low-level information on the container `id` "HairpinMode": false, "LinkLocalIPv6Address": "", "LinkLocalIPv6PrefixLen": 0, - "SandboxKey": "", - "SecondaryIPAddresses": [], - "SecondaryIPv6Addresses": [], "Ports": null, + "SandboxKey": "", + "SecondaryIPAddresses": null, + "SecondaryIPv6Addresses": null, + "EndpointID": "", + "Gateway": "", + "GlobalIPv6Address": "", + "GlobalIPv6PrefixLen": 0, + "IPAddress": "", + "IPPrefixLen": 0, + "IPv6Gateway": "", + "MacAddress": "", "Networks": { "bridge": { "EndpointID": "", "Gateway": "", - "IPAdress": "", + "IPAddress": "", "IPPrefixLen": 0, "IPv6Gateway": "", "GlobalIPv6Address": "", @@ -560,7 +568,7 @@ Status Codes: Get `stdout` and `stderr` logs from the container ``id`` > **Note**: -> This endpoint works only for containers with `json-file` logging driver. +> This endpoint works only for containers with the `json-file` or `journald` logging drivers. **Example request**: @@ -1242,14 +1250,14 @@ Query Parameters: **Example request**: - PUT /containers/8cce319429b2/archive?path=/vol1 HTTP/1.1 - Content-Type: application/x-tar + PUT /containers/8cce319429b2/archive?path=/vol1 HTTP/1.1 + Content-Type: application/x-tar - {{ TAR STREAM }} + {{ TAR STREAM }} **Example response**: - HTTP/1.1 200 OK + HTTP/1.1 200 OK Status Codes: @@ -2381,29 +2389,37 @@ Return low-level information about the `exec` command `id`. "SecurityOpt" : null }, "Image" : "5506de2b643be1e6febbf3b8a240760c6843244c41e12aa2f60ccbb7153d17f5", - "NetworkSettings": { - "Bridge": "", - "SandboxID": "", - "HairpinMode": false, - "LinkLocalIPv6Address": "", - "LinkLocalIPv6PrefixLen": 0, - "SandboxKey": "", - "SecondaryIPAddresses": [], - "SecondaryIPv6Addresses": [], - "Ports": null, - "Networks": { - "bridge": { - "EndpointID": "", - "Gateway": "", - "IPAdress": "", - "IPPrefixLen": 0, - "IPv6Gateway": "", - "GlobalIPv6Address": "", - "GlobalIPv6PrefixLen": 0, - "MacAddress": "" - } - } - }, + "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": { + "EndpointID": "", + "Gateway": "", + "IPAddress": "", + "IPPrefixLen": 0, + "IPv6Gateway": "", + "GlobalIPv6Address": "", + "GlobalIPv6PrefixLen": 0, + "MacAddress": "" + } + } + }, "ResolvConfPath" : "/var/lib/docker/containers/8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c/resolv.conf", "HostnamePath" : "/var/lib/docker/containers/8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c/hostname", "HostsPath" : "/var/lib/docker/containers/8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c/hosts", @@ -2433,22 +2449,22 @@ Status Codes: **Example request**: - GET /volumes HTTP/1.1 + GET /volumes HTTP/1.1 **Example response**: - HTTP/1.1 200 OK - Content-Type: application/json + HTTP/1.1 200 OK + Content-Type: application/json - { - "Volumes": [ - { - "Name": "tardis", - "Driver": "local", - "Mountpoint": "/var/lib/docker/volumes/tardis" - } - ] - } + { + "Volumes": [ + { + "Name": "tardis", + "Driver": "local", + "Mountpoint": "/var/lib/docker/volumes/tardis" + } + ] + } Query Parameters: @@ -2467,23 +2483,23 @@ Create a volume **Example request**: - POST /volumes/create HTTP/1.1 - Content-Type: application/json + POST /volumes/create HTTP/1.1 + Content-Type: application/json - { - "Name": "tardis" - } + { + "Name": "tardis" + } **Example response**: - HTTP/1.1 201 Created - Content-Type: application/json + HTTP/1.1 201 Created + Content-Type: application/json - { - "Name": "tardis" - "Driver": "local", - "Mountpoint": "/var/lib/docker/volumes/tardis" - } + { + "Name": "tardis", + "Driver": "local", + "Mountpoint": "/var/lib/docker/volumes/tardis" + } Status Codes: @@ -2509,14 +2525,14 @@ Return low-level information on the volume `name` **Example response**: - HTTP/1.1 200 OK - Content-Type: application/json + HTTP/1.1 200 OK + Content-Type: application/json - { - "Name": "tardis", - "Driver": "local", - "Mountpoint": "/var/lib/docker/volumes/tardis" - } + { + "Name": "tardis", + "Driver": "local", + "Mountpoint": "/var/lib/docker/volumes/tardis" + } Status Codes: @@ -2532,11 +2548,11 @@ Instruct the driver to remove the volume (`name`). **Example request**: - DELETE /volumes/local/tardis HTTP/1.1 + DELETE /volumes/local/tardis HTTP/1.1 **Example response**: - HTTP/1.1 204 No Content + HTTP/1.1 204 No Content Status Codes @@ -2553,34 +2569,70 @@ Status Codes **Example request**: - GET /networks HTTP/1.1 + GET /networks HTTP/1.1 **Example response**: - HTTP/1.1 200 OK - Content-Type: application/json - ``` - [ - { - "name": "bridge", - "id": "f995e41e471c833266786a64df584fbe4dc654ac99f63a4ee7495842aa093fc4", - "driver": "bridge", - "containers": {} +HTTP/1.1 200 OK +Content-Type: application/json + +[ + { + "Name": "bridge", + "Id": "f2de39df4171b0dc801e8002d1d999b77256983dfc63041c0f34030aa3977566", + "Scope": "local", + "Driver": "bridge", + "IPAM": { + "Driver": "default", + "Config": [ + { + "Subnet": "172.17.0.0/16" + } + ] }, - { - "name": "none", - "id": "21e34df9b29c74ae45ba312f8e9f83c02433c9a877cfebebcf57be78f69b77c8", - "driver": "null", - "containers": {} + "Containers": { + "39b69226f9d79f5634485fb236a23b2fe4e96a0a94128390a7fbbcc167065867": { + "EndpointID": "ed2419a97c1d9954d05b46e462e7002ea552f216e9b136b80a7db8d98b442eda", + "MacAddress": "02:42:ac:11:00:02", + "IPv4Address": "172.17.0.2/16", + "IPv6Address": "" + } }, - { - "name": "host", - "id": "3f43a0873f00310a71cd6a71e2e60c113cf17d1812be2ec22fd519fbac68ec91", - "driver": "host", - "containers": {} + "Options": { + "com.docker.network.bridge.default_bridge": "true", + "com.docker.network.bridge.enable_icc": "true", + "com.docker.network.bridge.enable_ip_masquerade": "true", + "com.docker.network.bridge.host_binding_ipv4": "0.0.0.0", + "com.docker.network.bridge.name": "docker0", + "com.docker.network.driver.mtu": "1500" } - ] + }, + { + "Name": "none", + "Id": "e086a3893b05ab69242d3c44e49483a3bbbd3a26b46baa8f61ab797c1088d794", + "Scope": "local", + "Driver": "null", + "IPAM": { + "Driver": "default", + "Config": [] + }, + "Containers": {}, + "Options": {} + }, + { + "Name": "host", + "Id": "13e871235c677f196c4e1ecebb9dc733b9b2d2ab589e30c539efeda84a24215e", + "Scope": "local", + "Driver": "host", + "IPAM": { + "Driver": "default", + "Config": [] + }, + "Containers": {}, + "Options": {} + } +] ``` @@ -2600,39 +2652,44 @@ Status Codes: **Example request**: - GET /networks/f995e41e471c833266786a64df584fbe4dc654ac99f63a4ee7495842aa093fc4 HTTP/1.1 + GET /networks/f2de39df4171b0dc801e8002d1d999b77256983dfc63041c0f34030aa3977566 HTTP/1.1 **Example response**: - HTTP/1.1 200 OK - Content-Type: application/json - ``` - { - "name": "bridge", - "id": "f995e41e471c833266786a64df584fbe4dc654ac99f63a4ee7495842aa093fc4", - "driver": "bridge", - "containers": { - "931d29e96e63022a3691f55ca18b28600239acf53878451975f77054b05ba559": { - "endpoint": "aa79321e2899e6d72fcd46e6a4ad7f81ab9a19c3b06e384ef4ce51fea35827f9", - "mac_address": "02:42:ac:11:00:04", - "ipv4_address": "172.17.0.4/16", - "ipv6_address": "" - }, - "961249b4ae6c764b11eed923e8463c102689111fffd933627b2e7e359c7d0f7c": { - "endpoint": "4f62c5aea6b9a70512210be7db976bd4ec2cdba47125e4fe514d18c81b1624b1", - "mac_address": "02:42:ac:11:00:02", - "ipv4_address": "172.17.0.2/16", - "ipv6_address": "" - }, - "9f6e0fec4449f42a173ed85be96dc2253b6719edd850d8169bc31bdc45db675c": { - "endpoint": "352b512a5bccdfc77d16c2c04d04408e718f879a16f9ce3913a4733139e4f98d", - "mac_address": "02:42:ac:11:00:03", - "ipv4_address": "172.17.0.3/16", - "ipv6_address": "" +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "Name": "bridge", + "Id": "f2de39df4171b0dc801e8002d1d999b77256983dfc63041c0f34030aa3977566", + "Scope": "local", + "Driver": "bridge", + "IPAM": { + "Driver": "default", + "Config": [ + { + "Subnet": "172.17.0.0/16" } + ] + }, + "Containers": { + "39b69226f9d79f5634485fb236a23b2fe4e96a0a94128390a7fbbcc167065867": { + "EndpointID": "ed2419a97c1d9954d05b46e462e7002ea552f216e9b136b80a7db8d98b442eda", + "MacAddress": "02:42:ac:11:00:02", + "IPv4Address": "172.17.0.2/16", + "IPv6Address": "" } + }, + "Options": { + "com.docker.network.bridge.default_bridge": "true", + "com.docker.network.bridge.enable_icc": "true", + "com.docker.network.bridge.enable_ip_masquerade": "true", + "com.docker.network.bridge.host_binding_ipv4": "0.0.0.0", + "com.docker.network.bridge.name": "docker0", + "com.docker.network.driver.mtu": "1500" } +} ``` Status Codes: @@ -2648,26 +2705,26 @@ Create a network **Example request**: - POST /networks/create HTTP/1.1 - Content-Type: application/json - ``` - { - "name":"isolated_nw", - "driver":"bridge" - } +POST /networks/create HTTP/1.1 +Content-Type: application/json + +{ + "Name":"isolated_nw", + "Driver":"bridge" +} ``` **Example response**: - HTTP/1.1 201 Created - Content-Type: application/json - ``` - { - "id": "22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30", - "warning": "" - } +HTTP/1.1 201 Created +Content-Type: application/json + +{ + "Id": "22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30", + "Warning": "" +} ``` Status Codes: @@ -2678,10 +2735,10 @@ Status Codes: JSON Parameters: -- **name** - The new network's name. this is a mandatory field -- **driver** - Name of the network driver to use. Defaults to `bridge` driver -- **options** - Network specific options to be used by the drivers -- **check_duplicate** - Requests daemon to check for networks with same name +- **Name** - The new network's name. this is a mandatory field +- **Driver** - Name of the network driver to use. Defaults to `bridge` driver +- **Options** - Network specific options to be used by the drivers +- **CheckDuplicate** - Requests daemon to check for networks with same name ### Connect a container to a network @@ -2691,18 +2748,18 @@ Connects a container to a network **Example request**: - POST /networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30/connect HTTP/1.1 - Content-Type: application/json - ``` - { - "container":"3613f73ba0e4" - } +POST /networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30/connect HTTP/1.1 +Content-Type: application/json + +{ + "Container":"3613f73ba0e4" +} ``` **Example response**: - HTTP/1.1 200 OK + HTTP/1.1 200 OK Status Codes: @@ -2721,18 +2778,18 @@ Disconnects a container from a network **Example request**: - POST /networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30/disconnect HTTP/1.1 - Content-Type: application/json - ``` - { - "container":"3613f73ba0e4" - } +POST /networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30/disconnect HTTP/1.1 +Content-Type: application/json + +{ + "Container":"3613f73ba0e4" +} ``` **Example response**: - HTTP/1.1 200 OK + HTTP/1.1 200 OK Status Codes: @@ -2741,7 +2798,7 @@ Status Codes: JSON Parameters: -- **container** - container-id/name to be disconnected from a network +- **Container** - container-id/name to be disconnected from a network ### Remove a network @@ -2751,11 +2808,11 @@ Instruct the driver to remove the network (`id`). **Example request**: - DELETE /networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30 HTTP/1.1 + DELETE /networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30 HTTP/1.1 **Example response**: - HTTP/1.1 204 No Content + HTTP/1.1 204 No Content Status Codes