Add initial "service" docs

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

docs/reference/commandline/index.md

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

docs/reference/commandline/service_create.md

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

docs/reference/commandline/service_inspect.md

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

docs/reference/commandline/service_ls.md

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

docs/reference/commandline/service_rm.md

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

docs/reference/commandline/service_scale.md

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

docs/reference/commandline/service_tasks.md

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

docs/reference/commandline/service_update.md

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