Initial Services docs

Signed-off-by: Dave Tucker <dt@docker.com>
Signed-off-by: Madhu Venugopal <madhu@docker.com>
This commit is contained in:
Dave Tucker 2015-05-21 01:41:08 +01:00 committed by Tibor Vass
parent c1571b2a74
commit b06c14eda9
2 changed files with 247 additions and 3 deletions

View File

@ -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.

View File

@ -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