diff --git a/experimental/networking.md b/experimental/networking.md index f3bd66b6..15372325 100644 --- a/experimental/networking.md +++ b/experimental/networking.md @@ -2,7 +2,10 @@ In this feature: -- `network` become a first class objects in the Docker UI +- `network` and `service` become a first class objects in the Docker UI +- You can create networks and attach containers to them +- We introduce the concept of `services` + - This is an entry-point in to a given network that is also published via Service Discovery This is an experimental feature. For information on installing and using experimental features, see [the experimental feature overview](experimental.md). @@ -59,14 +62,53 @@ If you no longer have need of a network, you can delete it with `docker network 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. +## Using Services + + Usage: docker service COMMAND [OPTIONS] [arg...] + + Commands: + publish Publish a service + unpublish Remove a service + attach Attach a backend (container) to the service + detach Detach the backend from the service + ls Lists all services + info Display information about a service + + Run 'docker service COMMAND --help' for more information on a command. + + --help=false Print usage + +Assuming we want to publish a service from container `a0ebc12d3e48` on network `foo` as `my-service` we would use the following command: + + $ docker service publish my-service.foo + ec56fd74717d00f968c26675c9a77707e49ae64b8e54832ebf78888eb116e428 + $ docker service attach a0ebc12d3e48 my-service.foo + +This would make the container `a0ebc12d3e48` accessible as `my-service` on network `foo`. Any other container in network `foo` can use DNS to resolve the address of `my-service` + +This can also be acheived by using the `--publish-service` flag for `docker run`: + + docker run -itd --publish-service db.foo postgres + +`db.foo` in this instance means "place the container on network `foo`, and allow other hosts on `foo` to discover it under the name `db`" + +We can see the current services using the `docker service ls` command + + $ docker service ls + SERVICE ID NAME NETWORK PROVIDER + ec56fd74717d my-service foo a0ebc12d3e48 + +To remove the a service: + + $ docker service detach a0ebc12d3e48 my-service.foo + $ docker service unpublish my-service.foo + 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 index 7af86b77..829c1587 100644 --- a/experimental/networking_api.md +++ b/experimental/networking_api.md @@ -285,3 +285,205 @@ Status Codes: - **200** – no error - **404** – not found - **500** – server error + +# Services API + +### Publish a Service + +`POST /services` + +Publish a service + +**Example Request** + + POST /services HTTP/1.1 + Content-Type: application/json + + { + "name": "bar", + "network_name": "foo", + "exposed_ports": null, + "port_mapping": null + } + +**Example Response** + + HTTP/1.1 200 OK + Content-Type: application/json + + "0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff" + +Status Codes: + +- **200** – no error +- **400** – bad parameter +- **500** – server error + +### Get a Service + +`GET /services/0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff` + +Get a service + +**Example Request**: + + GET /services/0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff HTTP/1.1 + +**Example Response**: + + HTTP/1.1 200 OK + Content-Type: application/json + + { + "name": "bar", + "id": "0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff", + "network": "foo" + } + +Status Codes: + +- **200** – no error +- **400** – bad parameter +- **404** - not found +- **500** – server error + +### Attach a backend to a service + +`POST /services/0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff/backend` + +Attach a backend to a service + +**Example Request**: + + POST /services/0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff/backend HTTP/1.1 + Content-Type: application/json + + { + "container_id": "98c5241f9475e9efc17e7198e931fb48166010b80f96d48df204e251378ca547", + "host_name": "", + "domain_name": "", + "hosts_path": "", + "resolv_conf_path": "", + "dns": null, + "extra_hosts": null, + "parent_updates": null, + "use_default_sandbox": false + } + +**Example Response**: + + HTTP/1.1 200 OK + Content-Type: application/json + + "/var/run/docker/netns/98c5241f9475" + +Status Codes: + +- **200** – no error +- **400** – bad parameter +- **500** – server error + +### Get Backends for a Service + +Get all backends for a given service + +**Example Request** + + GET /services/0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff/backend HTTP/1.1 + +**Example Response** + + HTTP/1.1 200 OK + Content-Type: application/json + + [ + { + "id": "98c5241f9475e9efc17e7198e931fb48166010b80f96d48df204e251378ca547" + } + ] + +Status Codes: + +- **200** – no error +- **400** – bad parameter +- **500** – server error + +### List Services + +`GET /services` + +List services + +**Example request**: + + GET /services HTTP/1.1 + +**Example response**: + + HTTP/1.1 200 OK + Content-Type: application/json + + [ + { + "name": "/stupefied_stallman", + "id": "c826b26bf736fb4a77db33f83562e59f9a770724e259ab9c3d50d948f8233ae4", + "network": "bridge" + }, + { + "name": "bar", + "id": "0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff", + "network": "foo" + } + ] + +Query Parameters: + +- **name** – Filter results with the given name +- **partial-id** – Filter results using the partial network ID +- **network** - Filter results by the given network + +Status Codes: + +- **200** – no error +- **400** – bad parameter +- **500** – server error + +### Detach a Backend from a Service + +`DELETE /services/0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff/backend/98c5241f9475e9efc17e7198e931fb48166010b80f96d48df204e251378ca547` + +Detach a backend from a service + +**Example Request** + + DELETE /services/0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff/backend/98c5241f9475e9efc17e7198e931fb48166010b80f96d48df204e251378ca547 HTTP/1.1 + +**Example Response** + + HTTP/1.1 200 OK + +Status Codes: + +- **200** – no error +- **400** – bad parameter +- **500** – server error + +### Un-Publish a Service + +`DELETE /services/0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff` + +Unpublish a service + +**Example Request** + + DELETE /services/0aee0899e6c5e903cf3ef2bdc28a1c9aaf639c8c8c331fa4ae26344d9e32c1ff HTTP/1.1 + +**Example Response** + + HTTP/1.1 200 OK + +Status Codes: + +- **200** – no error +- **400** – bad parameter +- **500** – server error