From 0183b3bf8c8c54aa88d92d4de771494388ee267a Mon Sep 17 00:00:00 2001 From: Vincent Demeester Date: Sat, 10 Sep 2016 11:50:29 +0200 Subject: [PATCH] Merge pull request #26426 from sfsmithcha/carry_pry_25414 Carry pr 25414 (cherry picked from commit e6f76800f5880652382a6f9180bfdefe6aaad577) Signed-off-by: Misty Stanley-Jones --- docs/reference/commandline/service_create.md | 100 ++++++++++++++----- 1 file changed, 77 insertions(+), 23 deletions(-) diff --git a/docs/reference/commandline/service_create.md b/docs/reference/commandline/service_create.md index 5a0da6794b..8254252566 100644 --- a/docs/reference/commandline/service_create.md +++ b/docs/reference/commandline/service_create.md @@ -49,8 +49,8 @@ Options: -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. +Creates a service as described by the specified parameters. You must run this +command on a manager node. ## Examples @@ -65,10 +65,10 @@ ID NAME REPLICAS IMAGE COMMAND dmu1ept4cxcf redis 1/1 redis:3.0.6 ``` -### Create a service with 5 tasks +### Create a service with 5 replica tasks (--replicas) -You can set the number of tasks for a service using the `--replicas` option. The -following command creates a `redis` service with `5` tasks: +Use the `--replicas` flag to set the number of replica tasks for a replicated +service. The following command creates a `redis` service with `5` replica tasks: ```bash $ docker service create --name redis --replicas=5 redis:3.0.6 @@ -76,12 +76,12 @@ $ docker service create --name redis --replicas=5 redis:3.0.6 ``` 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 +though the command returns immediately, actual scaling of the service may take some time. The `REPLICAS` column shows both the *actual* and *desired* number -of tasks for the service. +of replica tasks for the service. -In the following example, the desired number of tasks is set to `5`, but the -*actual* number is `3` +In the following example the desired state is `5` replicas, but the current +number of `RUNNING` tasks is `3`: ```bash $ docker service ls @@ -89,8 +89,8 @@ 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: +Once all the tasks are created and `RUNNING`, the actual number of tasks is +equal to the desired number: ```bash $ docker service ls @@ -98,10 +98,8 @@ ID NAME REPLICAS IMAGE COMMAND 4cdgfyky7ozw redis 5/5 redis:3.0.7 ``` - ### Create a service with a rolling update policy - ```bash $ docker service create \ --replicas 10 \ @@ -111,10 +109,12 @@ $ docker service create \ 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. +When you run a [service update](service_update.md), the scheduler updates a +maximum of 2 tasks at a time, with `10s` between updates. For more information, +refer to the [rolling updates +tutorial](../../swarm/swarm-tutorial/rolling-update.md). -### Setting environment variables (-e --env) +### Set environment variables (-e, --env) This sets environmental variables for all tasks in a service. For example: @@ -122,7 +122,7 @@ This sets environmental variables for all tasks in a service. For example: $ docker service create --name redis_2 --replicas 5 --env MYVAR=foo redis:3.0.6 ``` -### Set metadata on a service (-l --label) +### 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: @@ -138,19 +138,22 @@ $ docker service create \ For more information about labels, refer to [apply custom metadata](../../userguide/labels-custom-metadata.md). -### Set service mode +### Set service mode (--mode) -You can set the service mode to "replicated" (default) or to "global". A -replicated service runs as many tasks as specified, while a global service -runs on each active node in the swarm. +You can set the service mode to "replicated" (default) or to "global". A +replicated service runs the number of replica tasks you specify. 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 +$ docker service create \ + --name redis_2 \ + --mode global \ + redis:3.0.6 ``` -### Specify service constraints +### Specify service constraints (--constraint) You can limit the set of nodes where a task can be scheduled by defining constraint expressions. Multiple constraints find nodes that satisfy every @@ -179,6 +182,57 @@ $ docker service create \ redis:3.0.6 ``` +### Attach a service to an existing network (--network) + +You can use overlay networks to connect one or more services within the swarm. + +First, create an overlay network on a manager node the docker network create +command: + +```bash +$ docker network create --driver overlay my-network + +etjpu59cykrptrgw0z0hk5snf +``` + +After you create an overlay network in swarm mode, all manager nodes have +access to the network. + +When you create a service and pass the --network flag to attach the service to +the overlay network: + +$ docker service create \ + --replicas 3 \ + --network my-network \ + --name my-web \ + nginx + +716thylsndqma81j6kkkb5aus +The swarm extends my-network to each node running the service. + +Containers on the same network can access each other using +[service discovery](../../swarm/networking.md#use-swarm-mode-service-discovery). + +### Publish service ports externally to the swarm (-p, --publish) + +You can publish service ports to make them available externally to the swarm +using the `--publish` flag: + +```bash +docker service create --publish : nginx +``` + +For example: + +```bash +docker service create --name my_web --replicas 3 --publish 8080:80 nginx +``` + +When you publish a service port, the swarm routing mesh makes the service +accessible at the target port on every node regardless if there is a task for +the service running on the node. For more information refer to +[Use swarm mode routing mesh](../../swarm/ingress.md). + ## Related information * [service inspect](service_inspect.md)