Initial Services docs

Signed-off-by: Dave Tucker <dt@docker.com>
Signed-off-by: Madhu Venugopal <madhu@docker.com>

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.
 

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