beenull/moby
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Add initial "service" docs

Browse source 
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
(cherry picked from commit f565bc7ec9)
This commit is contained in:
Sebastiaan van Stijn 2016-06-17 16:51:17 -07:00 committed by Tibor Vass
parent d1c91b41e1
commit d5c89ec65e
8 changed files with 729 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

9
docs/reference/commandline/index.md
View file

@ -105,3 +105,12 @@ You start the Docker daemon with the command line. How you start the daemon affe
* [swarm leave](swarm_leave.md)
* [swarm update](swarm_update.md)
### Swarm service commands
* [service create](service_create.md)
* [service inspect](service_inspect.md)
* [service ls](service_ls.md)
* [service rm](service_rm.md)
* [service scale](service_scale.md)
* [service tasks](service_tasks.md)
* [service update](service_update.md)

157
docs/reference/commandline/service_create.md Normal file
View file

@ -0,0 +1,157 @@
<!--[metadata]>
+++
title = "service create"
description = "The service create command description and usage"
keywords = ["service, create"]
[menu.main]
parent = "smn_cli"
+++
<![end-metadata]-->
**Warning:** this command is part of the Swarm management feature introduced in Docker 1.12, and might be subject to non backward-compatible changes.
# service create
```Markdown
Usage: docker service create [OPTIONS] IMAGE [COMMAND] [ARG...]
Create a new service
Options:
--constraint value Placement constraints (default [])
--endpoint-mode string Endpoint mode(Valid values: VIP, DNSRR)
-e, --env value Set environment variables (default [])
--help Print usage
-l, --label value Service labels (default [])
--limit-cpu value Limit CPUs (default 0.000)
--limit-memory value Limit Memory (default 0 B)
--mode string Service mode (replicated or global) (default "replicated")
-m, --mount value Attach a mount to the service
--name string Service name
--network value Network attachments (default [])
-p, --publish value Publish a port as a node port (default [])
--replicas value Number of tasks (default none)
--reserve-cpu value Reserve CPUs (default 0.000)
--reserve-memory value Reserve Memory (default 0 B)
--restart-condition string Restart when condition is met (none, on_failure, or any)
--restart-delay value Delay between restart attempts (default none)
--restart-max-attempts value Maximum number of restarts before giving up (default none)
--restart-window value Window used to evalulate the restart policy (default none)
--stop-grace-period value Time to wait before force killing a container (default none)
--update-delay duration Delay between updates
--update-parallelism uint Maximum number of tasks updated simultaneously
-u, --user string Username or UID
-w, --workdir string Working directory inside the container
```
Creates a service as described by the specified parameters. This command has to
be run targeting a manager node.
## Examples
### Create a service
```bash
$ docker service create --name redis redis:3.0.6
dmu1ept4cxcfe8k8lhtux3ro3
$ docker service ls
ID NAME REPLICAS IMAGE COMMAND
dmu1ept4cxcf redis 1/1 redis:3.0.6
```
### Create a service with 5 tasks
You can set the number of tasks for a service using the `--replicas` option. The
following command creates a `redis` service with `5` tasks:
```bash
$ docker service create --name redis --replicas=5 redis:3.0.6
4cdgfyky7ozwh3htjfw0d12qv
```
The above command sets the *desired* number of tasks for the service. Even
though the command returns directly, actual scaling of the service may take
some time. The `REPLICAS` column shows both the *actual* and *desired* number
of tasks for the service.
In the following example, the desired number of tasks is set to `5`, but the
*actual* number is `3`
```bash
$ docker service ls
ID NAME REPLICAS IMAGE COMMAND
4cdgfyky7ozw redis 3/5 redis:3.0.7
```
Once all the tasks are created, the actual number of tasks is equal to the
desired number:
```bash
$ docker service ls
ID NAME REPLICAS IMAGE COMMAND
4cdgfyky7ozw redis 5/5 redis:3.0.7
```
### Create a service with a rolling update constraints
```bash
$ docker service create \
--replicas 10 \
--name redis \
--update-delay 10s \
--update-parallelism 2 \
redis:3.0.6
```
When this service is [updated](service_update.md), a rolling update will update
tasks in batches of `2`, with `10s` between batches.
### Setting environment variables (-e --env)
This sets environmental variables for all tasks in a service. For example:
```bash
$ docker service create --name redis_2 --replicas 5 --env MYVAR=foo redis:3.0.6
```
### Set metadata on a service (-l --label)
A label is a `key=value` pair that applies metadata to a service. To label a
service with two labels:
```bash
$ docker service create \
--name redis_2 \
--label com.example.foo="bar"
--label bar=baz \
redis:3.0.6
```
For more information about labels, refer to [apply custom
metadata](../../userguide/labels-custom-metadata.md)
### Service mode
Is this a replicated service or a global service. A replicated service runs as
many tasks as specified, while a global service runs on each active node in the
swarm.
The following command creates a "global" service:
```bash
$ docker service create --name redis_2 --mode global redis:3.0.6
```
## Related information
* [service inspect](service_inspect.md)
* [service ls](service_ls.md)
* [service rm](service_rm.md)
* [service scale](service_scale.md)
* [service tasks](service_tasks.md)
* [service update](service_update.md)

158
docs/reference/commandline/service_inspect.md Normal file
View file

@ -0,0 +1,158 @@
<!--[metadata]>
+++
title = "service inspect"
description = "The service inspect command description and usage"
keywords = ["service, inspect"]
[menu.main]
parent = "smn_cli"
+++
<![end-metadata]-->
**Warning:** this command is part of the Swarm management feature introduced in Docker 1.12, and might be subject to non backward-compatible changes.
# service inspect
```Markdown
Usage: docker service inspect [OPTIONS] SERVICE [SERVICE...]
Inspect a service
Options:
-f, --format string Format the output using the given go template
--help Print usage
-p, --pretty Print the information in a human friendly format.
```
Inspects the specified service. This command has to be run targeting a manager
node.
By default, this renders all results in a JSON array. If a format is specified,
the given template will be executed for each result.
Go's [text/template](http://golang.org/pkg/text/template/) package
describes all the details of the format.
## Examples
### Inspecting a service by name or ID
You can inspect a service, either by its *name*, or *ID*
For example, given the following service;
```bash
$ docker service ls
ID NAME REPLICAS IMAGE COMMAND
dmu1ept4cxcf redis 3/3 redis:3.0.6
```
Both `docker service inspect redis`, and `docker service inspect dmu1ept4cxcf`
produce the same result:
```bash
$ docker service inspect redis
[
{
"ID": "dmu1ept4cxcfe8k8lhtux3ro3",
"Version": {
"Index": 12
},
"CreatedAt": "2016-06-17T18:44:02.558012087Z",
"UpdatedAt": "2016-06-17T18:44:02.558012087Z",
"Spec": {
"Name": "redis",
"TaskTemplate": {
"ContainerSpec": {
"Image": "redis:3.0.6"
},
"Resources": {
"Limits": {},
"Reservations": {}
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": {}
},
"Mode": {
"Replicated": {
"Replicas": 1
}
},
"UpdateConfig": {},
"EndpointSpec": {
"Mode": "vip"
}
},
"Endpoint": {
"Spec": {}
}
}
]
```
```bash
$ docker service inspect dmu1ept4cxcf
[
{
"ID": "dmu1ept4cxcfe8k8lhtux3ro3",
"Version": {
"Index": 12
},
...
}
]
```
### Inspect a service using pretty-print
You can print the inspect output in a human-readable format instead of the default
JSON output, by using the `--pretty` option:
```bash
$ docker service inspect --pretty frontend
ID: c8wgl7q4ndfd52ni6qftkvnnp
Name: frontend
Labels:
- org.example.projectname=demo-app
Mode: REPLICATED
Replicas: 5
Placement:
Strategy: Spread
UpdateConfig:
Parallelism: 0
ContainerSpec:
Image: nginx:alpine
Resources:
Reservations:
Limits:
Ports:
Name =
Protocol = tcp
TargetPort = 443
PublishedPort = 4443
```
### Finding the number of tasks running as part of a service
The `--format` option can be used to obtain specific information about a
service. For example, the following command outputs the number of replicas
of the "redis" service.
```bash
$ docker service inspect --format='{{.Spec.Mode.Replicated.Replicas}}' redis
10
```
## Related information
* [service create](service_create.md)
* [service ls](service_ls.md)
* [service rm](service_rm.md)
* [service scale](service_scale.md)
* [service tasks](service_tasks.md)
* [service update](service_update.md)

112
docs/reference/commandline/service_ls.md Normal file
View file

@ -0,0 +1,112 @@
<!--[metadata]>
+++
title = "service ls"
description = "The service ls command description and usage"
keywords = ["service, ls"]
[menu.main]
parent = "smn_cli"
+++
<![end-metadata]-->
**Warning:** this command is part of the Swarm management feature introduced in Docker 1.12, and might be subject to non backward-compatible changes.
# service ls
```Markdown
docker service ls --help
Usage: docker service ls [OPTIONS]
List services
Aliases:
ls, list
Options:
-f, --filter value Filter output based on conditions provided
--help Print usage
-q, --quiet Only display IDs
```
This command when run targeting a manager, lists services are running in the
swarm.
On a manager node:
```bash
ID NAME REPLICAS IMAGE COMMAND
c8wgl7q4ndfd frontend 5/5 nginx:alpine
dmu1ept4cxcf redis 3/3 redis:3.0.6
```
The `REPLICAS` column shows both the *actual* and *desired* number of tasks for
the service.
## Filtering
The filtering flag (`-f` or `--filter`) format is of "key=value". If there is more
than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`)
The currently supported filters are:
* [id](#id)
* [label](#label)
* [name](#name)
#### ID
The `id` filter matches all or part of a service's id.
```bash
$ docker service ls -f "id=0bcjw"
ID NAME REPLICAS IMAGE COMMAND
0bcjwfh8ychr redis 1/1 redis:3.0.6
```
#### Label
The `label` filter matches services based on the presence of a `label` alone or
a `label` and a value.
The following filter matches all services with a `project` label regardless of
its value:
```bash
$ docker service ls --filter label=project
ID NAME REPLICAS IMAGE COMMAND
01sl1rp6nj5u frontend2 1/1 nginx:alpine
36xvvwwauej0 frontend 5/5 nginx:alpine
74nzcxxjv6fq backend 3/3 redis:3.0.6
```
The following filter matches only services with the `project` label with the
`project-a` value.
```bash
$ docker service ls --filter label=project=project-a
ID NAME REPLICAS IMAGE COMMAND
36xvvwwauej0 frontend 5/5 nginx:alpine
74nzcxxjv6fq backend 3/3 redis:3.0.6
```
#### Name
The `name` filter matches on all or part of a tasks's name.
The following filter matches services with a name containing `redis`.
```bash
$ docker service ls --filter name=redis
ID NAME REPLICAS IMAGE COMMAND
0bcjwfh8ychr redis 1/1 redis:3.0.6
```
## Related information
* [service create](service_create.md)
* [service inspect](service_inspect.md)
* [service rm](service_rm.md)
* [service scale](service_scale.md)
* [service tasks](service_tasks.md)
* [service update](service_update.md)

51
docs/reference/commandline/service_rm.md Normal file
View file

@ -0,0 +1,51 @@
<!--[metadata]>
+++
title = "service rm"
description = "The service rm command description and usage"
keywords = ["service, rm"]
[menu.main]
parent = "smn_cli"
+++
<![end-metadata]-->
**Warning:** this command is part of the Swarm management feature introduced in Docker 1.12, and might be subject to non backward-compatible changes.
# service rm
```Markdown
Usage: docker service rm [OPTIONS] SERVICE
Remove a service
Aliases:
rm, remove
Options:
--help Print usage
```
Removes the specified services from the swarm. This command has to be run
targeting a manager node.
For example, to remove the redis service:
```bash
$ docker service rm redis
redis
$ docker service ls
ID NAME SCALE IMAGE COMMAND
```
> **Warning**: Unlike `docker rm`, this command does not ask for confirmation
> before removing a running service.
## Related information
* [service create](service_create.md)
* [service inspect](service_inspect.md)
* [service ls](service_ls.md)
* [service scale](service_scale.md)
* [service tasks](service_tasks.md)
* [service update](service_update.md)

79
docs/reference/commandline/service_scale.md Normal file
View file

@ -0,0 +1,79 @@
<!--[metadata]>
+++
title = "service scale"
description = "The service scale command description and usage"
keywords = ["service, scale"]
[menu.main]
parent = "smn_cli"
+++
<![end-metadata]-->
**Warning:** this command is part of the Swarm management feature introduced in Docker 1.12, and might be subject to non backward-compatible changes.
# service scale
Usage: docker service scale SERVICE=REPLICAS [SERVICE=REPLICAS...]
Scale one or multiple services
Options:
--help Print usage
## Examples
### Scale a service
If you scale a service, you set the *desired* number of replicas. Even though
the command returns directly, actual scaling of the service may take some time.
For example, the following command scales the "frontend" service to 50 tasks.
```bash
$ docker service scale frontend=50
frontend scaled to 50
```
Directly afterwards, run `docker service ls`, to see the actual number of
replicas
```bash
$ docker service ls --filter name=frontend
ID NAME REPLICAS IMAGE COMMAND
3pr5mlvu3fh9 frontend 15/50 nginx:alpine
```
You can also scale a service using the [`docker service update`](service_update.md)
command. The following commands are therefore equivalent:
```bash
$ docker service scale frontend=50
$ docker service update --replicas=50 frontend
```
### Scale multiple services
The `docker service scale` command allows you to set the desired number of
tasks for multiple services at once. The following example scales both the
backend and frontend services:
```bash
$ docker service scale backend=3 frontend=5
backend scaled to 3
frontend scaled to 5
$ docker service ls
ID NAME REPLICAS IMAGE COMMAND
3pr5mlvu3fh9 frontend 5/5 nginx:alpine
74nzcxxjv6fq backend 3/3 redis:3.0.6
```
## Related information
* [service create](service_create.md)
* [service inspect](service_inspect.md)
* [service ls](service_ls.md)
* [service rm](service_rm.md)
* [service tasks](service_tasks.md)
* [service update](service_update.md)

95
docs/reference/commandline/service_tasks.md Normal file
View file

@ -0,0 +1,95 @@
<!--[metadata]>
+++
title = "service tasks"
description = "The service tasks command description and usage"
keywords = ["service, tasks"]
[menu.main]
parent = "smn_cli"
+++
<![end-metadata]-->
**Warning:** this command is part of the Swarm management feature introduced in Docker 1.12, and might be subject to non backward-compatible changes.
# service tasks
```Markdown
Usage: docker service tasks [OPTIONS] SERVICE
List the tasks of a service
Options:
-a, --all Display all tasks
-f, --filter value Filter output based on conditions provided
--help Print usage
-n, --no-resolve Do not map IDs to Names
```
Lists the tasks that are running as part of the specified service. This command
has to be run targeting a manager node.
## Examples
### Listing the tasks that are part of a service
The following command shows all the tasks that are part of the `redis` service:
```bash
$ docker service tasks redis
ID NAME SERVICE IMAGE LAST STATE DESIRED STATE NODE
0qihejybwf1x5vqi8lgzlgnpq redis.1 redis redis:3.0.6 Running 8 seconds Running manager1
bk658fpbex0d57cqcwoe3jthu redis.2 redis redis:3.0.6 Running 9 seconds Running worker2
5ls5s5fldaqg37s9pwayjecrf redis.3 redis redis:3.0.6 Running 9 seconds Running worker1
8ryt076polmclyihzx67zsssj redis.4 redis redis:3.0.6 Running 9 seconds Running worker1
1x0v8yomsncd6sbvfn0ph6ogc redis.5 redis redis:3.0.6 Running 8 seconds Running manager1
71v7je3el7rrw0osfywzs0lko redis.6 redis redis:3.0.6 Running 9 seconds Running worker2
4l3zm9b7tfr7cedaik8roxq6r redis.7 redis redis:3.0.6 Running 9 seconds Running worker2
9tfpyixiy2i74ad9uqmzp1q6o redis.8 redis redis:3.0.6 Running 9 seconds Running worker1
3w1wu13yuplna8ri3fx47iwad redis.9 redis redis:3.0.6 Running 8 seconds Running manager1
8eaxrb2fqpbnv9x30vr06i6vt redis.10 redis redis:3.0.6 Running 8 seconds Running manager1
```
## Filtering
The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there
is more than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bif=baz"`).
Multiple filter flags are combined as an `OR` filter. For example,
`-f type=custom -f type=builtin` returns both `custom` and `builtin` networks.
The currently supported filters are:
* [id](#id)
* [name](#name)
#### ID
The `id` filter matches on all or a prefix of a task's ID.
```bash
$ docker service tasks -f "id=8" redis
ID NAME SERVICE IMAGE LAST STATE DESIRED STATE NODE
8ryt076polmclyihzx67zsssj redis.4 redis redis:3.0.6 Running 4 minutes Running worker1
8eaxrb2fqpbnv9x30vr06i6vt redis.10 redis redis:3.0.6 Running 4 minutes Running manager1
```
#### Name
The `name` filter matches on task names.
```bash
$ docker service tasks -f "name=redis.1" redis
ID NAME SERVICE IMAGE DESIRED STATE LAST STATE NODE
0qihejybwf1x5vqi8lgzlgnpq redis.1 redis redis:3.0.6 Running Running 8 seconds manager1
```
## Related information
* [service create](service_create.md)
* [service inspect](service_inspect.md)
* [service ls](service_ls.md)
* [service rm](service_rm.md)
* [service scale](service_scale.md)
* [service update](service_update.md)

68
docs/reference/commandline/service_update.md Normal file
View file

@ -0,0 +1,68 @@
<!--[metadata]>
+++
title = "service update"
description = "The service update command description and usage"
keywords = ["service, update"]
[menu.main]
parent = "smn_cli"
+++
<![end-metadata]-->
**Warning:** this command is part of the Swarm management feature introduced in Docker 1.12, and might be subject to non backward-compatible changes.
# service update
```Markdown
Usage: docker service update [OPTIONS] SERVICE
Update a service
Options:
--arg value Service command args (default [])
--command value Service command (default [])
--constraint value Placement constraints (default [])
--endpoint-mode string Endpoint mode(Valid values: VIP, DNSRR)
-e, --env value Set environment variables (default [])
--help Print usage
--image string Service image tag
-l, --label value Service labels (default [])
--limit-cpu value Limit CPUs (default 0.000)
--limit-memory value Limit Memory (default 0 B)
--mode string Service mode (replicated or global) (default "replicated")
-m, --mount value Attach a mount to the service
--name string Service name
--network value Network attachments (default [])
-p, --publish value Publish a port as a node port (default [])
--replicas value Number of tasks (default none)
--reserve-cpu value Reserve CPUs (default 0.000)
--reserve-memory value Reserve Memory (default 0 B)
--restart-condition string Restart when condition is met (none, on_failure, or any)
--restart-delay value Delay between restart attempts (default none)
--restart-max-attempts value Maximum number of restarts before giving up (default none)
--restart-window value Window used to evalulate the restart policy (default none)
--stop-grace-period value Time to wait before force killing a container (default none)
--update-delay duration Delay between updates
--update-parallelism uint Maximum number of tasks updated simultaneously
-u, --user string Username or UID
-w, --workdir string Working directory inside the container
```
Updates a service as described by the specified parameters. This command has to be run targeting a manager node.
The parameters are the same as [`docker service create`](service_create.md). Please look at the description there
for further information.
## Examples
### Update a service
```bash
$ docker service update --limit-cpu 2 redis
```
## Related information
* [service create](service_create.md)
* [service inspect](service_inspect.md)
* [service tasks](service_tasks.md)
* [service ls](service_ls.md)
* [service rm](service_rm.md)