# service create ```Markdown Usage: docker service create [OPTIONS] IMAGE [COMMAND] [ARG...] Create a new service Options: --constraint value Placement constraints (default []) --container-label value Service container labels (default []) --endpoint-mode string Endpoint mode (vip or dnsrr) -e, --env value Set environment variables (default []) --group-add value Add additional user groups to the container (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) --log-driver string Logging driver for service --log-opt value Logging driver options (default []) --mode string Service mode (replicated or global) (default "replicated") --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 evaluate 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-failure-action string Action on update failure (pause|continue) (default "pause") --update-parallelism uint Maximum number of tasks updated simultaneously (0 to update all at once) (default 1) -u, --user string Username or UID (format: [:]) --with-registry-auth Send registry authentication details to Swarm agents -w, --workdir string Working directory inside the container ``` Creates a service as described by the specified parameters. You must run this command on 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 replica tasks (--replicas) 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 4cdgfyky7ozwh3htjfw0d12qv ``` The above command sets the *desired* number of tasks for the service. Even 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 replica tasks for the service. In the following example the desired state is `5` replicas, but the current number of `RUNNING` tasks 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 and `RUNNING`, 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 policy ```bash $ docker service create \ --replicas 10 \ --name redis \ --update-delay 10s \ --update-parallelism 2 \ redis:3.0.6 ``` 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). ### Set 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). ### Add volumes or bind-mounts The following table describes the options for defining mounts in a service: | Option | Required | Description |:----------------------|:------------------|:-------------------------------------------------------------------------------------------------------------------- | **type** | | The type of mount, can be either "volume", or "bind". Defaults to "volume" if no type is specified. | **src** | `bind` only | | **source** | | Alias for `src`. | **dst** | yes | Mount path inside the container, for example `/some/path/in/container/`. If the path does not exist in the container's filesystem, the Engine creates a directory at the specified location before mounting the volume or bind-mount. | **destination** | | Alias for `dst`. | **target** | | Alias for `dst`. | **readonly** | | By default, the Engine mounts binds and volumes `read-write`. Pass the `readonly` option to mount the bind or volume `read-only` in the container.

A value is optional: | **ro** | | Alias for `readonly`. The following options can only be used for bind-mounts (`type=bind`); | Option | Description |:----------------------|:-------------------------------------------------------------------------------------------------------------------- | **bind-propagation** | Bind propagation options to set on the mount at runtime. Valid options are `shared`, `slave`, `private`, `rshared`, `rslave`, and `rprivate`. Defaults to `rprivate` if not specified. For volumes, bind propagation is not configurable, and also defaults to `rprivate`. The following options can only be used for named volumes (`type=volume`); | Option | Description |:----------------------|:-------------------------------------------------------------------------------------------------------------------- | **volume-driver** | Name of the volume-driver plugin to use for the volume. Defaults to the ``"local"`` volume driver to create the volume if it does not exist. | **volume-label** | Custom metadata ("labels") to apply to the volume upon creation. Labels are provided as comma-separated list of key/value pairs, for example, `volume-label=hello=world`. For more information about labels, refer to [apply custom metadata](../../userguide/labels-custom-metadata.md). | **volume-nocopy** | By default, if you attach an empty volume to a container, the Engine propagates the files and directories that are present at the mount-path (`dst`) inside the container into the volume. Set `volume-nocopy` to disables copying files from the container's filesystem to the volume and mount the empty volume.

A value is optional: | **volume-opt** | Volume driver-specific options to use when creating the volume. Options are provided as comma-separated list of key/value pairs, for example, `volume-opt=some-option=some-value,some-other-option=some-other-value`. For available options, refer to the documentation of the volume driver that is used. #### Differences between "--mount" and "--volume" The `--mount` flag features most options that are supported by the `-v` / `--volume` flag for `docker run`. There are some differences; - The `--mount` flag allows specifying a volume driver, and volume driver options *per volume*, without having to create volumes in advance. When using `docker run`, only a single volume driver can be specified (using the `--volume-driver` flag), which is shared by all volumes. - The `--mount` flag allows specifying custom metadata ("labels") for the volume, without having to create the volume out of band. - When using `type=bind`, the host-path must refer to an *existing* path on the host, and is not automatically created if the path does not exist. If the specified path does not exist on the host, an error is produced, and the service will fail to be deployed succesfully. - The `--mount` flag does not allow you to relabel volumes with `Z` or `z` #### Create a service using a named volume The following example creates a service that uses a named volume: ```bash $ docker service create \ --name my-service \ --replicas 3 \ --mount type=volume,source=my-volume,destination=/path/in/container,volume-label="color=red",volume-label="shape=round" \ nginx:alpine ``` For each replica of the service, the engine requests a volume named "my-volume" from the default ("local") volume driver where the task is deployed. If the volume does not exist, the engine creates a new volume and applies the "color" and "shape" labels. When the task is started, the volume is mounted on `/path/in/container/` inside the container. Be aware that the default ("local") volume is a locally scoped volume driver. This means that depending on where a task is deployed, either that task gets a *new* volume named "my-volume", or shares the same "my-volume" with other tasks of the same service. Multiple containers writing to a single shared volume can cause data corruption if the software running inside the container is not designed to handle concurrent processes writing to the same location. Also take into account that containers can be re-scheduled by the Swarm orchestrator and be deployed on a different node. #### Create a service that uses an anonymous (ephemeral) volume The following command creates a service with three replicas with an anonymous volume on `/path/in/container`: ```bash $ docker service create \ --name my-service \ --replicas 3 \ --mount type=volume,destination=/path/in/container \ nginx:alpine ``` In this example, no name (`source`) is specified for the volume, hence a new, *randomly named* volume is created for each task. This guarantees that each task gets its own volume, and volumes are not shared between tasks. Unnamed volumes are considered "ephemeral", and are destroyed when the container is destroyed. #### Create a service that uses a bind-mounted host directory The following example bind-mounts a host directory at `/path/in/container` in the containers backing the service: ```bash $ docker service create \ --name my-service \ --mount type=bind,source=/path/on/host,destination=/path/in/container \ nginx:alpine ``` ### Set service mode (--mode) 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 ``` ### 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 expression (AND match). Constraints can match node or Docker Engine labels as follows: | node attribute | matches | example | |:----------------|:--------------------------|:------------------------------------------------| | node.id | node ID | `node.id == 2ivku8v2gvtg4` | | node.hostname | node hostname | `node.hostname != node-2` | | node.role | node role: manager | `node.role == manager` | | node.labels | user defined node labels | `node.labels.security == high` | | engine.labels | Docker Engine's labels | `engine.labels.operatingsystem == ubuntu 14.04` | `engine.labels` apply to Docker Engine labels like operating system, drivers, etc. Swarm administrators add `node.labels` for operational purposes by using the [`docker node update`](node_update.md) command. For example, the following limits tasks for the redis service to nodes where the node type label equals queue: ```bash $ docker service create \ --name redis_2 \ --constraint 'node.labels.type == queue' \ 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) * [service ls](service_ls.md) * [service rm](service_rm.md) * [service scale](service_scale.md) * [service ps](service_ps.md) * [service update](service_update.md)