From cca990c67a3132d46e0157878507138aa2c6d2e5 Mon Sep 17 00:00:00 2001 From: Madhu Venugopal Date: Thu, 18 Jun 2015 11:48:08 -0700 Subject: [PATCH] Network UI / API docs Signed-off-by: Madhu Venugopal --- experimental/networking.md | 72 +++++++++ experimental/networking_api.md | 287 +++++++++++++++++++++++++++++++++ 2 files changed, 359 insertions(+) create mode 100644 experimental/networking.md create mode 100644 experimental/networking_api.md diff --git a/experimental/networking.md b/experimental/networking.md new file mode 100644 index 0000000000..f3bd66b615 --- /dev/null +++ b/experimental/networking.md @@ -0,0 +1,72 @@ +# Experimental: Networking and Services + +In this feature: + +- `network` become a first class objects in the Docker UI + +This is an experimental feature. For information on installing and using experimental features, see [the experimental feature overview](experimental.md). + +## Using Networks + + Usage: docker network [OPTIONS] COMMAND [OPTIONS] [arg...] + + Commands: + create Create a network + rm Remove a network + ls List all networks + info Display information of a network + + Run 'docker network COMMAND --help' for more information on a command. + + --help=false Print usage + +The `docker network` command is used to manage Networks. + +To create a network, `docker network create foo`. You can also specify a driver +if you have loaded a networking plugin e.g `docker network create -d foo` + + $ docker network create foo + aae601f43744bc1f57c515a16c8c7c4989a2cad577978a32e6910b799a6bccf6 + $ docker network create -d overlay bar + d9989793e2f5fe400a58ef77f706d03f668219688ee989ea68ea78b990fa2406 + +`docker network ls` is used to display the currently configured networks + + $ docker network ls + NETWORK ID NAME TYPE + d367e613ff7f none null + bd61375b6993 host host + cc455abccfeb bridge bridge + aae601f43744 foo bridge + d9989793e2f5 bar overlay + +To get detailed information on a network, you can use the `docker network info` +command. + + $ docker network info foo + Network Id: aae601f43744bc1f57c515a16c8c7c4989a2cad577978a32e6910b799a6bccf6 + Name: foo + Type: null + +If you no longer have need of a network, you can delete it with `docker network rm` + + $ docker network rm bar + bar + $ docker network ls + NETWORK ID NAME TYPE + aae601f43744 foo bridge + d367e613ff7f none null + bd61375b6993 host host + cc455abccfeb bridge bridge + + +Currently the only way this network can be used to connect container is via default network-mode. +Docker daemon supports a configuration flag `--default-network` which takes configuration value of format `NETWORK:DRIVER`, where, +`NETWORK` is the name of the network created using the `docker network create` command and +`DRIVER` represents the in-built drivers such as bridge, overlay, container, host and none. or Remote drivers via Network Plugins. +When a container is created and if the network mode (`--net`) is not specified, then this default network will be used to connect +the container. If `--default-network` is not specified, the default network will be the `bridge` driver. + +Send us feedback and comments on [#](https://github.com/docker/docker/issues/?), +or on the usual Google Groups (docker-user, docker-dev) and IRC channels. + diff --git a/experimental/networking_api.md b/experimental/networking_api.md new file mode 100644 index 0000000000..7af86b77d0 --- /dev/null +++ b/experimental/networking_api.md @@ -0,0 +1,287 @@ +# Networking API + +### List networks + +`GET /networks` + +List networks + +**Example request**: + + GET /networks HTTP/1.1 + +**Example response**: + + HTTP/1.1 200 OK + Content-Type: application/json + + [ + { + "name": "none", + "id": "8e4e55c6863ef4241c548c1c6fc77289045e9e5d5b5e4875401a675326981898", + "type": "null", + "endpoints": [] + }, + { + "name": "host", + "id": "062b6d9ea7913fde549e2d186ff0402770658f8c4e769958e1b943ff4e675011", + "type": "host", + "endpoints": [] + }, + { + "name": "bridge", + "id": "a87dd9a9d58f030962df1c15fb3fa142fbd9261339de458bc89be1895cef2c70", + "type": "bridge", + "endpoints": [] + } + ] + +Query Parameters: + +- **name** – Filter results with the given name +- **partial-id** – Filter results using the partial network ID + +Status Codes: + +- **200** – no error +- **400** – bad parameter +- **500** – server error + +### Create a Network + +`POST /networks` + +**Example request** + + POST /networks HTTP/1.1 + Content-Type: application/json + + { + "name": "foo", + "network_type": "", + "options": {} + } + +**Example Response** + + HTTP/1.1 200 OK + "32fbf63200e2897f5de72cb2a4b653e4b1a523b15116e96e3d73f7849e583653", + +Status Codes: + +- **200** – no error +- **400** – bad request +- **500** – server error + +### Get a network + +`GET /networks/` + +Get a network + +**Example request**: + + GET /networks/32fbf63200e2897f5de72cb2a4b653e4b1a523b15116e96e3d73f7849e583653 HTTP/1.1 + +**Example response**: + + HTTP/1.1 200 OK + Content-Type: application/json + + { + "name": "foo", + "id": "32fbf63200e2897f5de72cb2a4b653e4b1a523b15116e96e3d73f7849e583653", + "type": "bridge", + "endpoints": [] + } + +Status Codes: + +- **200** – no error +- **404** – not found +- **500** – server error + +### List a networks endpoints + +`GET /networks//endpoints` + +**Example request** + + GET /networks/32fbf63200e2897f5de72cb2a4b653e4b1a523b15116e96e3d73f7849e583653/endpoints HTTP/1.1 + +**Example Response** + + HTTP/1.1 200 OK + Content-Type: application/json + + [ + { + "id": "7e0c116b882ee489a8a5345a2638c0129099aa47f4ba114edde34e75c1e4ae0d", + "name": "/lonely_pasteur", + "network": "foo" + } + ] + +Query Parameters: + +- **name** – Filter results with the given name +- **partial-id** – Filter results using the partial network ID + +Status Codes: + +- **200** – no error +- **400** – bad parameter +- **500** – server error + +### Create an endpoint on a network + +`POST /networks//endpoints` + +**Example request** + + POST /networks/32fbf63200e2897f5de72cb2a4b653e4b1a523b15116e96e3d73f7849e583653/endpoints HTTP/1.1 + Content-Type: application/json + + { + "name": "baz", + "exposed_ports": [ + { + "proto": 6, + "port": 8080 + } + ], + "port_mapping": null + } + +**Example Response** + + HTTP/1.1 200 OK + Content-Type: application/json + + "b18b795af8bad85cdd691ff24ffa2b08c02219d51992309dd120322689d2ab5a" + +Status Codes: + +- **200** – no error +- **400** – bad parameter +- **500** – server error + +### Get an endpoint + +`GET /networks//endpoints/` + +**Example request** + + GET /networks/32fbf63200e2897f5de72cb2a4b653e4b1a523b15116e96e3d73f7849e583653/endpoints/b18b795af8bad85cdd691ff24ffa2b08c02219d51992309dd120322689d2ab5a HTTP/1.1 + +**Example Response** + + HTTP/1.1 200 OK + Content-Type: application/json + + { + "id": "b18b795af8bad85cdd691ff24ffa2b08c02219d51992309dd120322689d2ab5a", + "name": "baz", + "network": "foo" + } + +Status Codes: + +- **200** – no error +- **404** - not found +- **500** – server error + +### Join an endpoint to a container + +`POST /networks//endpoints//containers` + +**Example request** + + POST /networks/32fbf63200e2897f5de72cb2a4b653e4b1a523b15116e96e3d73f7849e583653//endpoints/b18b795af8bad85cdd691ff24ffa2b08c02219d51992309dd120322689d2ab5a/containers HTTP/1.1 + Content-Type: application/json + + { + "container_id": "e76f406417031bd24c17aeb9bb2f5968b628b9fb6067da264b234544754bf857", + "host_name": null, + "domain_name": null, + "hosts_path": null, + "resolv_conf_path": null, + "dns": null, + "extra_hosts": null, + "parent_updates": null, + "use_default_sandbox": true + } + +**Example response** + + HTTP/1.1 200 OK + Content-Type: application/json + + "/var/run/docker/netns/e76f40641703" + + +Status Codes: + +- **200** – no error +- **400** – bad parameter +- **404** - not found +- **500** – server error + +### Detach an endpoint from a container + +`DELETE /networks//endpoints//containers/` + +**Example request** + + DELETE /networks/32fbf63200e2897f5de72cb2a4b653e4b1a523b15116e96e3d73f7849e583653/endpoints/b18b795af8bad85cdd691ff24ffa2b08c02219d51992309dd120322689d2ab5a/containers/e76f406417031bd24c17aeb9bb2f5968b628b9fb6067da264b234544754bf857 HTTP/1.1 + Content-Type: application/json + +**Example response** + + HTTP/1.1 200 OK + +Status Codes: + +- **200** – no error +- **400** – bad parameter +- **404** - not found +- **500** – server error + + +### Delete an endpoint + +`DELETE /networks//endpoints/` + +**Example request** + + DELETE /networks/32fbf63200e2897f5de72cb2a4b653e4b1a523b15116e96e3d73f7849e583653/endpoints/b18b795af8bad85cdd691ff24ffa2b08c02219d51992309dd120322689d2ab5a HTTP/1.1 + +**Example Response** + + HTTP/1.1 200 OK + +Status Codes: + +- **200** – no error +- **404** - not found +- **500** – server error + +### Delete a network + +`DELETE /networks/` + +Delete a network + +**Example request**: + + DELETE /networks/0984d158bd8ae108e4d6bc8fcabedf51da9a174b32cc777026d4a29045654951 HTTP/1.1 + +**Example response**: + + HTTP/1.1 200 OK + +Status Codes: + +- **200** – no error +- **404** – not found +- **500** – server error