2016-10-14 22:30:36 +00:00
---
title: "service create"
description: "The service create command description and usage"
2016-11-03 22:48:30 +00:00
keywords: "service, create"
2016-10-14 22:30:36 +00:00
---
2016-06-17 23:51:17 +00:00
2016-10-19 17:25:45 +00:00
<!-- This file is maintained within the docker/docker Github
repository at https://github.com/docker/docker/. Make all
pull requests against that repo. If you see this file in
another repository, consider it read-only there, as it will
periodically be overwritten by the definitive file. Pull
requests which include edits to this file in other repositories
will be rejected.
-->
2016-06-17 23:51:17 +00:00
# service create
```Markdown
2016-07-07 18:43:18 +00:00
Usage: docker service create [OPTIONS] IMAGE [COMMAND] [ARG...]
2016-06-17 23:51:17 +00:00
Create a new service
Options:
2017-03-31 01:35:04 +00:00
--constraint list Placement constraints
--container-label list Container labels
-d, --detach Exit immediately instead of waiting for the service to converge (default true)
--dns list Set custom DNS servers
--dns-option list Set DNS options
--dns-search list Set custom DNS search domains
--endpoint-mode string Endpoint mode (vip or dnsrr) (default "vip")
--entrypoint command Overwrite the default ENTRYPOINT of the image
-e, --env list Set environment variables
--env-file list Read in a file of environment variables
--group list Set one or more supplementary user groups for the container
2017-02-16 00:04:30 +00:00
--health-cmd string Command to run to check health
2017-04-10 21:12:44 +00:00
--health-interval duration Time between running the check (ms|s|m|h)
2017-02-16 00:04:30 +00:00
--health-retries int Consecutive failures needed to report unhealthy
2017-04-10 21:12:44 +00:00
--health-start-period duration Start period for the container to initialize before counting retries towards unstable (ms|s|m|h)
--health-timeout duration Maximum time to allow one check to run (ms|s|m|h)
2017-02-16 00:04:30 +00:00
--help Print usage
2017-03-31 01:35:04 +00:00
--host list Set one or more custom host-to-IP mappings (host:ip)
2017-02-16 00:04:30 +00:00
--hostname string Container hostname
2017-03-31 01:35:04 +00:00
-l, --label list Service labels
--limit-cpu decimal Limit CPUs
2017-02-16 00:04:30 +00:00
--limit-memory bytes Limit Memory
--log-driver string Logging driver for service
2017-03-31 01:35:04 +00:00
--log-opt list Logging driver options
2017-02-16 00:04:30 +00:00
--mode string Service mode (replicated or global) (default "replicated")
--mount mount Attach a filesystem mount to the service
--name string Service name
2017-03-31 01:35:04 +00:00
--network list Network attachments
2017-02-16 00:04:30 +00:00
--no-healthcheck Disable any container-specified HEALTHCHECK
--placement-pref pref Add a placement preference
-p, --publish port Publish a port as a node port
2017-03-31 01:35:04 +00:00
-q, --quiet Suppress progress output
2017-02-16 00:04:30 +00:00
--read-only Mount the container's root filesystem as read only
--replicas uint Number of tasks
2017-03-31 01:35:04 +00:00
--reserve-cpu decimal Reserve CPUs
2017-02-16 00:04:30 +00:00
--reserve-memory bytes Reserve Memory
2017-03-31 01:35:04 +00:00
--restart-condition string Restart when condition is met ("none"|"on-failure"|"any") (default "any")
--restart-delay duration Delay between restart attempts (ns|us|ms|s|m|h) (default 5s)
2017-02-16 00:04:30 +00:00
--restart-max-attempts uint Maximum number of restarts before giving up
--restart-window duration Window used to evaluate the restart policy (ns|us|ms|s|m|h)
--rollback-delay duration Delay between task rollbacks (ns|us|ms|s|m|h) (default 0s)
--rollback-failure-action string Action on rollback failure ("pause"|"continue") (default "pause")
2017-03-31 01:35:04 +00:00
--rollback-max-failure-ratio float Failure rate to tolerate during a rollback (default 0)
--rollback-monitor duration Duration after each task rollback to monitor for failure (ns|us|ms|s|m|h) (default 5s)
2017-01-18 19:38:19 +00:00
--rollback-order string Rollback order ("start-first"|"stop-first") (default "stop-first")
2017-03-31 01:35:04 +00:00
--rollback-parallelism uint Maximum number of tasks rolled back simultaneously (0 to roll back all at once) (default 1)
2017-02-16 00:04:30 +00:00
--secret secret Specify secrets to expose to the service
2017-03-31 01:35:04 +00:00
--stop-grace-period duration Time to wait before force killing a container (ns|us|ms|s|m|h) (default 10s)
2017-02-16 00:04:30 +00:00
--stop-signal string Signal to stop the container
-t, --tty Allocate a pseudo-TTY
--update-delay duration Delay between updates (ns|us|ms|s|m|h) (default 0s)
--update-failure-action string Action on update failure ("pause"|"continue"|"rollback") (default "pause")
2017-03-31 01:35:04 +00:00
--update-max-failure-ratio float Failure rate to tolerate during an update (default 0)
--update-monitor duration Duration after each task update to monitor for failure (ns|us|ms|s|m|h) (default 5s)
2017-01-18 19:38:19 +00:00
--update-order string Update order ("start-first"|"stop-first") (default "stop-first")
2017-02-16 00:04:30 +00:00
--update-parallelism uint Maximum number of tasks updated simultaneously (0 to update all at once) (default 1)
-u, --user string Username or UID (format: < name | uid > [:< group | gid > ])
--with-registry-auth Send registry authentication details to swarm agents
-w, --workdir string Working directory inside the container
2016-06-17 23:51:17 +00:00
```
2017-02-07 23:42:48 +00:00
## Description
2016-09-08 19:10:04 +00:00
Creates a service as described by the specified parameters. You must run this
command on a manager node.
2016-06-17 23:51:17 +00:00
## Examples
### Create a service
```bash
$ docker service create --name redis redis:3.0.6
2017-02-07 23:42:48 +00:00
2016-06-17 23:51:17 +00:00
dmu1ept4cxcfe8k8lhtux3ro3
2016-10-25 03:39:53 +00:00
$ docker service create --mode global --name redis2 redis:3.0.6
2017-02-07 23:42:48 +00:00
2016-10-25 03:39:53 +00:00
a8q9dasaafudfs8q8w32udass
2016-06-17 23:51:17 +00:00
$ docker service ls
2017-02-07 23:42:48 +00:00
2016-10-25 03:39:53 +00:00
ID NAME MODE REPLICAS IMAGE
dmu1ept4cxcf redis replicated 1/1 redis:3.0.6
a8q9dasaafud redis2 global 1/1 redis:3.0.6
2016-06-17 23:51:17 +00:00
```
2016-09-08 19:10:04 +00:00
### Create a service with 5 replica tasks (--replicas)
2016-06-17 23:51:17 +00:00
2016-09-08 19:10:04 +00:00
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:
2016-06-17 23:51:17 +00:00
```bash
$ docker service create --name redis --replicas=5 redis:3.0.6
2017-02-07 23:42:48 +00:00
2016-06-17 23:51:17 +00:00
4cdgfyky7ozwh3htjfw0d12qv
```
The above command sets the *desired* number of tasks for the service. Even
2016-09-08 19:10:04 +00:00
though the command returns immediately, actual scaling of the service may take
2016-06-17 23:51:17 +00:00
some time. The `REPLICAS` column shows both the *actual* and *desired* number
2016-09-08 19:10:04 +00:00
of replica tasks for the service.
2016-06-17 23:51:17 +00:00
2016-09-08 19:10:04 +00:00
In the following example the desired state is `5` replicas, but the current
number of `RUNNING` tasks is `3` :
2016-06-17 23:51:17 +00:00
```bash
$ docker service ls
2017-02-07 23:42:48 +00:00
2016-10-25 03:39:53 +00:00
ID NAME MODE REPLICAS IMAGE
4cdgfyky7ozw redis replicated 3/5 redis:3.0.7
2016-06-17 23:51:17 +00:00
```
2016-09-08 19:10:04 +00:00
Once all the tasks are created and `RUNNING` , the actual number of tasks is
equal to the desired number:
2016-06-17 23:51:17 +00:00
```bash
$ docker service ls
2017-02-07 23:42:48 +00:00
2016-10-25 03:39:53 +00:00
ID NAME MODE REPLICAS IMAGE
4cdgfyky7ozw redis replicated 5/5 redis:3.0.7
2016-06-17 23:51:17 +00:00
```
2016-10-28 00:30:32 +00:00
### Create a service with secrets
2017-02-07 23:42:48 +00:00
2016-10-31 15:02:10 +00:00
Use the `--secret` flag to give a container access to a
2016-11-03 19:56:05 +00:00
[secret ](secret_create.md ).
Create a service specifying a secret:
```bash
$ docker service create --name redis --secret secret.json redis:3.0.6
2017-02-07 23:42:48 +00:00
2016-11-03 19:56:05 +00:00
4cdgfyky7ozwh3htjfw0d12qv
```
Create a service specifying the secret, target, user/group ID and mode:
2016-10-28 00:30:32 +00:00
```bash
2016-11-03 19:56:05 +00:00
$ docker service create --name redis \
--secret source=ssh-key,target=ssh \
2017-01-23 17:06:53 +00:00
--secret source=app-key,target=app,uid=1000,gid=1001,mode=0400 \
2016-11-03 19:56:05 +00:00
redis:3.0.6
2017-02-07 23:42:48 +00:00
2016-10-28 00:30:32 +00:00
4cdgfyky7ozwh3htjfw0d12qv
```
Secrets are located in `/run/secrets` in the container. If no target is
specified, the name of the secret will be used as the in memory file in the
container. If a target is specified, that will be the filename. In the
example above, two files will be created: `/run/secrets/ssh` and
`/run/secrets/app` for each of the secret targets specified.
2016-07-07 23:57:46 +00:00
### Create a service with a rolling update policy
2016-06-17 23:51:17 +00:00
```bash
$ docker service create \
--replicas 10 \
--name redis \
--update-delay 10s \
--update-parallelism 2 \
redis:3.0.6
```
2016-09-08 19:10:04 +00:00
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
2016-10-20 15:40:36 +00:00
tutorial](https://docs.docker.com/engine/swarm/swarm-tutorial/rolling-update/).
2016-06-17 23:51:17 +00:00
2016-09-08 19:10:04 +00:00
### Set environment variables (-e, --env)
2016-06-17 23:51:17 +00:00
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
```
2017-02-07 23:42:48 +00:00
### Create a service with specific hostname (--hostname)
This option sets the docker service containers hostname to a specific string.
For example:
2016-10-27 11:44:19 +00:00
```bash
$ docker service create --name redis --hostname myredis redis:3.0.6
```
2017-02-07 23:42:48 +00:00
2016-09-08 19:10:04 +00:00
### Set metadata on a service (-l, --label)
2016-06-17 23:51:17 +00:00
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
2016-10-20 15:40:36 +00:00
metadata](https://docs.docker.com/engine/userguide/labels-custom-metadata/).
2016-06-17 23:51:17 +00:00
2016-09-10 00:29:32 +00:00
### Add bind-mounts or volumes
Docker supports two different kinds of mounts, which allow containers to read to
or write from files or directories on other containers or the host operating
system. These types are _data volumes_ (often referred to simply as volumes) and
_bind-mounts_.
2017-02-07 23:42:48 +00:00
Additionally, Docker supports `tmpfs` mounts.
2016-11-08 05:32:21 +00:00
2016-09-10 00:29:32 +00:00
A **bind-mount** makes a file or directory on the host available to the
container it is mounted within. A bind-mount may be either read-only or
read-write. For example, a container might share its host's DNS information by
means of a bind-mount of the host's `/etc/resolv.conf` or a container might
write logs to its host's `/var/log/myContainerLogs` directory. If you use
bind-mounts and your host and containers have different notions of permissions,
access controls, or other such details, you will run into portability issues.
A **named volume** is a mechanism for decoupling persistent data needed by your
container from the image used to create the container and from the host machine.
Named volumes are created and managed by Docker, and a named volume persists
even when no container is currently using it. Data in named volumes can be
shared between a container and the host machine, as well as between multiple
containers. Docker uses a _volume driver_ to create, manage, and mount volumes.
You can back up or restore volumes using Docker commands.
2016-11-08 05:32:21 +00:00
A **tmpfs** mounts a tmpfs inside a container for volatile data.
2016-09-10 00:29:32 +00:00
Consider a situation where your image starts a lightweight web server. You could
use that image as a base image, copy in your website's HTML files, and package
that into another image. Each time your website changed, you'd need to update
the new image and redeploy all of the containers serving your website. A better
solution is to store the website in a named volume which is attached to each of
your web server containers when they start. To update the website, you just
update the named volume.
For more information about named volumes, see
[Data Volumes ](https://docs.docker.com/engine/tutorials/dockervolumes/ ).
The following table describes options which apply to both bind-mounts and named
volumes in a service:
2017-03-12 19:01:06 +00:00
< table >
< tr >
< th > Option< / th >
< th > Required< / th >
< th > Description< / th >
< / tr >
< tr >
< td > < b > types< / b > < / td >
< td > < / td >
< td >
< p > The type of mount, can be either < tt > volume< / tt > , < tt > bind< / tt > , or < tt > tmpfs< / tt > . Defaults to < tt > volume< / tt > if no type is specified.
< ul >
< li >< tt > volume</ tt > : mounts a [managed volume ](volume_create.md ) into the container.</ li >
< li > < tt > bind< / tt > : bind-mounts a directory or file from the host into the container.< / li >
< li > < tt > tmpfs< / tt > : mount a tmpfs in the container< / li >
< / ul > < / p >
< / td >
< / tr >
< tr >
< td > < b > src< / b > or < b > source< / b > < / td >
< td > for < tt > type=bind< / tt > only>< / td >
< td >
< ul >
< li >
< tt > type=volume< / tt > : < tt > src< / tt > is an optional way to specify the name of the volume (for example, < tt > src=my-volume< / tt > ).
If the named volume does not exist, it is automatically created. If no < tt > src< / tt > is specified, the volume is
assigned a random name which is guaranteed to be unique on the host, but may not be unique cluster-wide.
A randomly-named volume has the same lifecycle as its container and is destroyed when the < i > container< / i >
is destroyed (which is upon < tt > service update< / tt > , or when scaling or re-balancing the service)
< / li >
< li >
< tt > type=bind< / tt > : < tt > src< / tt > is required, and specifies an absolute path to the file or directory to bind-mount
(for example, < tt > src=/path/on/host/< / tt > ). An error is produced if the file or directory does not exist.
< / li >
< li >
< tt > type=tmpfs< / tt > : < tt > src< / tt > is not supported.
< / li >
< / ul >
< / td >
< / tr >
< tr >
< td > < p > < b > dst< / b > or < b > destination< / b > or < b > target< / b > < / p > < / td >
< td > yes< / td >
< td >
< p > Mount path inside the container, for example < tt > /some/path/in/container/< / tt > .
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.< / p >
< / td >
< / tr >
< tr >
< td > < p > < b > readonly< / b > or < b > ro< / b > < / p > < / td >
< td > < / td >
< td >
< p > The Engine mounts binds and volumes < tt > read-write< / tt > unless < tt > readonly< / tt > option
is given when mounting the bind or volume.
< ul >
< li > < tt > true< / tt > or < tt > 1< / tt > or no value: Mounts the bind or volume read-only.< / li >
< li > < tt > false< / tt > or < tt > 0< / tt > : Mounts the bind or volume read-write.< / li >
< / ul > < / p >
< / td >
< / tr >
2017-03-10 15:02:32 +00:00
< tr >
< td > < b > consistency< / b > < / td >
< td > < / td >
< td >
< p > The consistency requirements for the mount; one of
< ul >
< li > < tt > default< / tt > : Equivalent to < tt > consistent< / tt > .< / li >
< li > < tt > consistent< / tt > : Full consistency. The container runtime and the host maintain an identical view of the mount at all times.< / li >
< li > < tt > cached< / tt > : The host's view of the mount is authoritative. There may be delays before updates made on the host are visible within a container.< / li >
< li > < tt > delegated< / tt > : The container runtime's view of the mount is authoritative. There may be delays before updates made in a container are are visible on the host.< / li >
< / ul >
< / p >
< / td >
< / tr >
2017-03-12 19:01:06 +00:00
< / table >
2016-09-10 00:29:32 +00:00
#### Bind Propagation
Bind propagation refers to whether or not mounts created within a given
bind-mount or named volume can be propagated to replicas of that mount. Consider
a mount point `/mnt` , which is also mounted on `/tmp` . The propation settings
control whether a mount on `/tmp/a` would also be available on `/mnt/a` . Each
propagation setting has a recursive counterpoint. In the case of recursion,
consider that `/tmp/a` is also mounted as `/foo` . The propagation settings
control whether `/mnt/a` and/or `/tmp/a` would exist.
The `bind-propagation` option defaults to `rprivate` for both bind-mounts and
volume mounts, and is only configurable for bind-mounts. In other words, named
volumes do not support bind propagation.
- **`shared`**: Sub-mounts of the original mount are exposed to replica mounts,
and sub-mounts of replica mounts are also propagated to the
original mount.
- **`slave`**: similar to a shared mount, but only in one direction. If the
original mount exposes a sub-mount, the replica mount can see it.
However, if the replica mount exposes a sub-mount, the original
mount cannot see it.
- **`private`**: The mount is private. Sub-mounts within it are not exposed to
replica mounts, and sub-mounts of replica mounts are not
exposed to the original mount.
- **`rshared`**: The same as shared, but the propagation also extends to and from
mount points nested within any of the original or replica mount
points.
- **`rslave`**: The same as `slave` , but the propagation also extends to and from
mount points nested within any of the original or replica mount
points.
- **`rprivate`**: The default. The same as `private` , meaning that no mount points
anywhere within the original or replica mount points propagate
in either direction.
For more information about bind propagation, see the
[Linux kernel documentation for shared subtree ](https://www.kernel.org/doc/Documentation/filesystems/sharedsubtree.txt ).
#### Options for Named Volumes
2017-03-12 19:01:06 +00:00
2016-09-10 00:29:32 +00:00
The following options can only be used for named volumes (`type=volume`);
2016-08-15 21:51:15 +00:00
2017-03-12 19:01:06 +00:00
< table >
< tr >
< th > Option< / th >
< th > Description< / th >
< / tr >
< tr >
< td > < b > volume-driver< / b > < / td >
< td >
< p > Name of the volume-driver plugin to use for the volume. Defaults to
< tt > "local"< / tt > , to use the local volume driver to create the volume if the
volume does not exist.< / p >
< / td >
< / tr >
< tr >
< td > < b > volume-label< / b > < / td >
< td >
One or more custom metadata ("labels") to apply to the volume upon
creation. For example,
`volume-label=mylabel=hello-world,my-other-label=hello-mars` . For more
information about labels, refer to
< a href = "https://docs.docker.com/engine/userguide/labels-custom-metadata/" > apply custom metadata< / a > .
< / td >
< / tr >
< tr >
< td > < b > volume-nocopy< / b > < / td >
< td >
By default, if you attach an empty volume to a container, and files or
directories already existed at the mount-path in the container (< tt > dst< / tt > ),
the Engine copies those files and directories into the volume, allowing
the host to access them. Set `volume-nocopy` to disables copying files
from the container's filesystem to the volume and mount the empty volume.
A value is optional:
< ul >
< li > < tt > true< / tt > or < tt > 1< / tt > : Default if you do not provide a value. Disables copying.< / li >
< li > < tt > false< / tt > or < tt > 0< / tt > : Enables copying.< / li >
< / ul >
< / td >
< / tr >
< tr >
< td > < b > volume-opt< / b > < / td >
< td >
Options specific to a given volume driver, which will be passed to the
driver when creating the volume. Options are provided as a comma-separated
list of key/value pairs, for example,
2017-04-01 03:45:22 +00:00
< tt > volume-opt=some-option=some-value,volume-opt=some-other-option=some-other-value< / tt > .
2017-03-12 19:01:06 +00:00
For available options for a given driver, refer to that driver's
documentation.
< / td >
< / tr >
< / table >
2016-09-10 00:29:32 +00:00
2016-11-08 05:32:21 +00:00
#### Options for tmpfs
2017-03-12 19:01:06 +00:00
2016-11-08 05:32:21 +00:00
The following options can only be used for tmpfs mounts (`type=tmpfs`);
2017-03-12 19:01:06 +00:00
< table >
< tr >
< th > Option< / th >
< th > Description< / th >
< / tr >
< tr >
< td > < b > tmpfs-size< / b > < / td >
< td > Size of the tmpfs mount in bytes. Unlimited by default in Linux.< / td >
< / tr >
< tr >
< td > < b > tmpfs-mode< / b > < / td >
< td > File mode of the tmpfs in octal. (e.g. < tt > "700"< / tt > or < tt > "0700"< / tt > .) Defaults to < tt > "1777"< / tt > in Linux.< / td >
< / tr >
< / table >
2016-11-08 05:32:21 +00:00
2016-09-10 00:29:32 +00:00
#### Differences between "--mount" and "--volume"
2016-08-15 21:51:15 +00:00
2016-09-10 00:29:32 +00:00
The `--mount` flag supports most options that are supported by the `-v`
or `--volume` flag for `docker run` , with some important exceptions:
2016-08-15 21:51:15 +00:00
2016-09-10 00:29:32 +00:00
- The `--mount` flag allows you to specify a volume driver and volume driver
2017-02-07 23:42:48 +00:00
options *per volume* , without creating the volumes in advance. In contrast,
`docker run` allows you to specify a single volume driver which is shared
by all volumes, using the `--volume-driver` flag.
2016-08-15 21:51:15 +00:00
2016-09-10 00:29:32 +00:00
- The `--mount` flag allows you to specify custom metadata ("labels") for a volume,
2017-02-07 23:42:48 +00:00
before the volume is created.
2016-08-15 21:51:15 +00:00
2016-09-10 00:29:32 +00:00
- When you use `--mount` with `type=bind` , the host-path must refer to an *existing*
2017-02-07 23:42:48 +00:00
path on the host. The path will not be created for you and the service will fail
with an error if the path does not exist.
2016-08-15 21:51:15 +00:00
2016-09-10 00:29:32 +00:00
- The `--mount` flag does not allow you to relabel a volume with `Z` or `z` flags,
2017-02-07 23:42:48 +00:00
which are used for `selinux` labeling.
2016-08-15 21:51:15 +00:00
#### 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.
2016-09-10 00:29:32 +00:00
#### Create a service that uses an anonymous volume
2016-08-15 21:51:15 +00:00
2016-09-10 00:29:32 +00:00
The following command creates a service with three replicas with an anonymous
2016-08-15 21:51:15 +00:00
volume on `/path/in/container` :
```bash
$ docker service create \
--name my-service \
--replicas 3 \
--mount type=volume,destination=/path/in/container \
nginx:alpine
```
2016-09-10 00:29:32 +00:00
In this example, no name (`source`) is specified for the volume, so a new volume
is created for each task. This guarantees that each task gets its own volume,
and volumes are not shared between tasks. Anonymous volumes are removed after
the task using them is complete.
2016-08-15 21:51:15 +00:00
#### 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
```
2016-09-08 19:10:04 +00:00
### Set service mode (--mode)
2016-06-17 23:51:17 +00:00
2016-09-10 00:29:32 +00:00
The service mode determines whether this is a _replicated_ service or a _global_
service. A replicated service runs as many tasks as specified, while a global
2016-09-08 19:10:04 +00:00
service runs on each active node in the swarm.
2016-06-17 23:51:17 +00:00
2016-09-10 00:29:32 +00:00
The following command creates a global service:
2016-06-17 23:51:17 +00:00
```bash
2016-09-08 19:10:04 +00:00
$ docker service create \
--name redis_2 \
--mode global \
redis:3.0.6
2016-06-17 23:51:17 +00:00
```
2016-09-08 19:10:04 +00:00
### Specify service constraints (--constraint)
2016-07-07 23:57:46 +00:00
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:
2017-03-12 19:01:06 +00:00
< table >
< tr >
< th > node attribute< / th >
< th > matches< / th >
< th > example< / th >
< / tr >
< tr >
< td > < tt > node.id< / tt > < / td >
< td > Node ID< / td >
< td > < tt > node.id == 2ivku8v2gvtg4< / tt > < / td >
< / tr >
< tr >
< td > < tt > node.hostname< / tt > < / td >
< td > Node hostname< / td >
< td > < tt > node.hostname != node-2< / tt > < / td >
< / tr >
< tr >
2017-03-16 21:17:38 +00:00
< td > < tt > node.role< / tt > < / td >
< td > Node role< / td >
2017-03-12 19:01:06 +00:00
< td > < tt > node.role == manager< / tt > < / td >
< / tr >
< tr >
< td > < tt > node.labels< / tt > < / td >
< td > user defined node labels< / td >
< td > < tt > node.labels.security == high< / tt > < / td >
< / tr >
< tr >
< td > < tt > engine.labels< / tt > < / td >
< td > Docker Engine's labels< / td >
< td > < tt > engine.labels.operatingsystem == ubuntu 14.04< / tt > < / td >
< / tr >
< / table >
2016-07-07 23:57:46 +00:00
`engine.labels` apply to Docker Engine labels like operating system,
drivers, etc. Swarm administrators add `node.labels` for operational purposes by
2016-07-11 16:11:18 +00:00
using the [`docker node update` ](node_update.md ) command.
2016-07-07 23:57:46 +00:00
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 \
2016-07-14 16:38:37 +00:00
--constraint 'node.labels.type == queue' \
redis:3.0.6
2016-07-07 23:57:46 +00:00
```
2016-06-17 23:51:17 +00:00
2017-01-19 23:27:37 +00:00
### Specify service placement preferences (--placement-pref)
You can set up the service to divide tasks evenly over different categories of
nodes. One example of where this can be useful is to balance tasks over a set
of datacenters or availability zones. The example below illustrates this:
```bash
$ docker service create \
--replicas 9 \
--name redis_2 \
--placement-pref 'spread=node.labels.datacenter' \
redis:3.0.6
```
This uses `--placement-pref` with a `spread` strategy (currently the only
supported strategy) to spread tasks evenly over the values of the `datacenter`
node label. In this example, we assume that every node has a `datacenter` node
label attached to it. If there are three different values of this label among
nodes in the swarm, one third of the tasks will be placed on the nodes
associated with each value. This is true even if there are more nodes with one
value than another. For example, consider the following set of nodes:
- Three nodes with `node.labels.datacenter=east`
- Two nodes with `node.labels.datacenter=south`
- One node with `node.labels.datacenter=west`
Since we are spreading over the values of the `datacenter` label and the
service has 9 replicas, 3 replicas will end up in each datacenter. There are
three nodes associated with the value `east` , so each one will get one of the
three replicas reserved for this value. There are two nodes with the value
`south` , and the three replicas for this value will be divided between them,
with one receiving two replicas and another receiving just one. Finally, `west`
has a single node that will get all three replicas reserved for `west` .
If the nodes in one category (for example, those with
`node.labels.datacenter=south` ) can't handle their fair share of tasks due to
constraints or resource limitations, the extra tasks will be assigned to other
nodes instead, if possible.
Both engine labels and node labels are supported by placement preferences. The
example above uses a node label, because the label is referenced with
`node.labels.datacenter` . To spread over the values of an engine label, use
`--placement-pref spread=engine.labels.<labelname>` .
It is possible to add multiple placement preferences to a service. This
establishes a hierarchy of preferences, so that tasks are first divided over
one category, and then further divided over additional categories. One example
of where this may be useful is dividing tasks fairly between datacenters, and
then splitting the tasks within each datacenter over a choice of racks. To add
multiple placement preferences, specify the `--placement-pref` flag multiple
times. The order is significant, and the placement preferences will be applied
in the order given when making scheduling decisions.
The following example sets up a service with multiple placement preferences.
Tasks are spread first over the various datacenters, and then over racks
(as indicated by the respective labels):
```bash
$ docker service create \
--replicas 9 \
--name redis_2 \
--placement-pref 'spread=node.labels.datacenter' \
--placement-pref 'spread=node.labels.rack' \
redis:3.0.6
```
When updating a service with `docker service update` , `--placement-pref-add`
appends a new placement preference after all existing placement preferences.
`--placement-pref-rm` removes an existing placement preference that matches the
argument.
2016-09-08 19:10:04 +00:00
### Attach a service to an existing network (--network)
2016-08-04 16:56:59 +00:00
2016-09-08 19:10:04 +00:00
You can use overlay networks to connect one or more services within the swarm.
2016-08-04 16:56:59 +00:00
2016-09-08 19:10:04 +00:00
First, create an overlay network on a manager node the docker network create
command:
2016-08-04 16:56:59 +00:00
2016-09-08 19:10:04 +00:00
```bash
$ docker network create --driver overlay my-network
etjpu59cykrptrgw0z0hk5snf
2016-08-04 16:56:59 +00:00
```
2016-09-08 19:10:04 +00:00
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:
2016-08-04 16:56:59 +00:00
2016-09-19 11:57:39 +00:00
```bash
2016-09-08 19:10:04 +00:00
$ docker service create \
--replicas 3 \
--network my-network \
--name my-web \
nginx
716thylsndqma81j6kkkb5aus
2016-09-19 11:57:39 +00:00
```
2016-09-08 19:10:04 +00:00
The swarm extends my-network to each node running the service.
2016-08-04 16:56:59 +00:00
2016-09-08 19:10:04 +00:00
Containers on the same network can access each other using
2016-10-20 15:40:36 +00:00
[service discovery ](https://docs.docker.com/engine/swarm/networking/#use-swarm-mode-service-discovery ).
2016-08-04 16:56:59 +00:00
2016-09-08 19:10:04 +00:00
### Publish service ports externally to the swarm (-p, --publish)
2016-08-04 16:56:59 +00:00
2016-09-08 19:10:04 +00:00
You can publish service ports to make them available externally to the swarm
using the `--publish` flag:
2016-08-04 16:56:59 +00:00
2016-09-08 19:10:04 +00:00
```bash
2016-09-19 11:57:39 +00:00
$ docker service create --publish < TARGET-PORT > :< SERVICE-PORT > nginx
2016-09-08 19:10:04 +00:00
```
2016-08-04 16:56:59 +00:00
2016-09-08 19:10:04 +00:00
For example:
2016-08-04 16:56:59 +00:00
2016-09-08 19:10:04 +00:00
```bash
2016-09-19 11:57:39 +00:00
$ docker service create --name my_web --replicas 3 --publish 8080:80 nginx
2016-08-04 16:56:59 +00:00
```
2016-09-08 19:10:04 +00:00
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
2016-10-20 15:40:36 +00:00
[Use swarm mode routing mesh ](https://docs.docker.com/engine/swarm/ingress/ ).
2016-09-08 19:10:04 +00:00
2016-12-14 19:00:41 +00:00
### Publish a port for TCP only or UDP only
2016-11-28 23:31:43 +00:00
By default, when you publish a port, it is a TCP port. You can
specifically publish a UDP port instead of or in addition to a TCP port. When
you publish both TCP and UDP ports, Docker 1.12.2 and earlier require you to
add the suffix `/tcp` for TCP ports. Otherwise it is optional.
#### TCP only
The following two commands are equivalent.
```bash
$ docker service create --name dns-cache -p 53:53 dns-cache
$ docker service create --name dns-cache -p 53:53/tcp dns-cache
```
#### TCP and UDP
```bash
$ docker service create --name dns-cache -p 53:53/tcp -p 53:53/udp dns-cache
```
#### UDP only
```bash
$ docker service create --name dns-cache -p 53:53/udp dns-cache
```
2016-11-18 14:28:01 +00:00
### Create services using templates
You can use templates for some flags of `service create` , using the syntax
2017-02-02 05:53:37 +00:00
provided by the Go's [text/template ](http://golang.org/pkg/text/template/ ) package.
2016-11-18 14:28:01 +00:00
The supported flags are the following :
- `--hostname`
- `--mount`
- `--env`
Valid placeholders for the Go template are listed below:
2017-03-12 19:01:06 +00:00
< table >
< tr >
< th > Placeholder< / th >
< th > Description< / th >
< / tr >
< tr >
< td > < tt > .Service.ID< / tt > < / td >
< td > Service ID< / td >
< / tr >
< tr >
< td > < tt > .Service.Name< / tt > < / td >
< td > Service name< / td >
< / tr >
< tr >
< td > < tt > .Service.Labels< / tt > < / td >
< td > Service labels< / td >
< / tr >
< tr >
< td > < tt > .Node.ID< / tt > < / td >
< td > Node ID< / td >
< / tr >
< tr >
< td > < tt > .Task.ID< / tt > < / td >
< td > Task ID< / td >
< / tr >
< tr >
< td > < tt > .Task.Name< / tt > < / td >
< td > Task name< / td >
< / tr >
< tr >
< td > < tt > .Task.Slot< / tt > < / td >
< td > Task slot< / td >
< / tr >
< / table >
2016-11-18 14:28:01 +00:00
#### Template example
In this example, we are going to set the template of the created containers based on the
service's name and the node's ID where it sits.
```bash
2017-02-07 23:42:48 +00:00
$ docker service create --name hosttempl \
2017-03-02 01:14:15 +00:00
--hostname="{{.Node.ID}}-{{.Service.Name}}"\
2017-02-07 23:42:48 +00:00
busybox top
2016-11-18 14:28:01 +00:00
va8ew30grofhjoychbr6iot8c
2016-12-13 12:30:58 +00:00
2016-11-18 14:28:01 +00:00
$ docker service ps va8ew30grofhjoychbr6iot8c
2017-02-07 23:42:48 +00:00
2016-12-13 12:30:58 +00:00
ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS
wo41w8hg8qan hosttempl.1 busybox:latest@sha256:29f5d56d12684887bdfa50dcd29fc31eea4aaf4ad3bec43daf19026a7ce69912 2e7a8a9c4da2 Running Running about a minute ago
2017-02-07 23:42:48 +00:00
$ docker inspect --format="{{.Config.Hostname}}" hosttempl.1.wo41w8hg8qanxwjwsg4kxpprj
2016-11-18 14:28:01 +00:00
x3ti0erg11rjpg64m75kej2mz-hosttempl
```
2017-02-07 23:42:48 +00:00
## Related commands
2016-06-17 23:51:17 +00:00
* [service inspect ](service_inspect.md )
2016-12-14 11:30:09 +00:00
* [service logs ](service_logs.md )
2016-06-17 23:51:17 +00:00
* [service ls ](service_ls.md )
* [service rm ](service_rm.md )
* [service scale ](service_scale.md )
2016-07-19 21:01:31 +00:00
* [service ps ](service_ps.md )
2016-06-17 23:51:17 +00:00
* [service update ](service_update.md )
2016-08-15 21:51:15 +00:00
< style > table tr > td : first-child { white-space : nowrap ; } < / style >