command: docker service create short: Create a new service long: |- Creates a service as described by the specified parameters. You must run this command on a manager node. usage: docker service create [OPTIONS] IMAGE [COMMAND] [ARG...] pname: docker service plink: docker_service.yaml options: - option: config value_type: config description: Specify configurations to expose to the service deprecated: false min_api_version: "1.30" experimental: false experimentalcli: false kubernetes: false swarm: false - option: constraint value_type: list description: Placement constraints deprecated: false experimental: false experimentalcli: false kubernetes: false swarm: false - option: container-label value_type: list description: Container labels deprecated: false experimental: false experimentalcli: false kubernetes: false swarm: false - option: credential-spec value_type: credential-spec description: Credential spec for managed service account (Windows only) deprecated: false min_api_version: "1.29" experimental: false experimentalcli: false kubernetes: false swarm: false - option: detach shorthand: d value_type: bool default_value: "false" description: | Exit immediately instead of waiting for the service to converge deprecated: false min_api_version: "1.29" experimental: false experimentalcli: false kubernetes: false swarm: false - option: dns value_type: list description: Set custom DNS servers deprecated: false min_api_version: "1.25" experimental: false experimentalcli: false kubernetes: false swarm: false - option: dns-option value_type: list description: Set DNS options deprecated: false min_api_version: "1.25" experimental: false experimentalcli: false kubernetes: false swarm: false - option: dns-search value_type: list description: Set custom DNS search domains deprecated: false min_api_version: "1.25" experimental: false experimentalcli: false kubernetes: false swarm: false - option: endpoint-mode value_type: string default_value: vip description: Endpoint mode (vip or dnsrr) deprecated: false experimental: false experimentalcli: false kubernetes: false swarm: false - option: entrypoint value_type: command description: Overwrite the default ENTRYPOINT of the image deprecated: false experimental: false experimentalcli: false kubernetes: false swarm: false - option: env shorthand: e value_type: list description: Set environment variables deprecated: false experimental: false experimentalcli: false kubernetes: false swarm: false - option: env-file value_type: list description: Read in a file of environment variables deprecated: false experimental: false experimentalcli: false kubernetes: false swarm: false - option: generic-resource value_type: list description: User defined resources deprecated: false experimental: false experimentalcli: false kubernetes: false swarm: false - option: group value_type: list description: Set one or more supplementary user groups for the container deprecated: false min_api_version: "1.25" experimental: false experimentalcli: false kubernetes: false swarm: false - option: health-cmd value_type: string description: Command to run to check health deprecated: false min_api_version: "1.25" experimental: false experimentalcli: false kubernetes: false swarm: false - option: health-interval value_type: duration description: Time between running the check (ms|s|m|h) deprecated: false min_api_version: "1.25" experimental: false experimentalcli: false kubernetes: false swarm: false - option: health-retries value_type: int default_value: "0" description: Consecutive failures needed to report unhealthy deprecated: false min_api_version: "1.25" experimental: false experimentalcli: false kubernetes: false swarm: false - option: health-start-period value_type: duration description: | Start period for the container to initialize before counting retries towards unstable (ms|s|m|h) deprecated: false min_api_version: "1.29" experimental: false experimentalcli: false kubernetes: false swarm: false - option: health-timeout value_type: duration description: Maximum time to allow one check to run (ms|s|m|h) deprecated: false min_api_version: "1.25" experimental: false experimentalcli: false kubernetes: false swarm: false - option: host value_type: list description: Set one or more custom host-to-IP mappings (host:ip) deprecated: false min_api_version: "1.25" experimental: false experimentalcli: false kubernetes: false swarm: false - option: hostname value_type: string description: Container hostname deprecated: false min_api_version: "1.25" experimental: false experimentalcli: false kubernetes: false swarm: false - option: init value_type: bool default_value: "false" description: | Use an init inside each service container to forward signals and reap processes deprecated: false min_api_version: "1.37" experimental: false experimentalcli: false kubernetes: false swarm: false - option: isolation value_type: string description: Service container isolation mode deprecated: false min_api_version: "1.35" experimental: false experimentalcli: false kubernetes: false swarm: false - option: label shorthand: l value_type: list description: Service labels deprecated: false experimental: false experimentalcli: false kubernetes: false swarm: false - option: limit-cpu value_type: decimal description: Limit CPUs deprecated: false experimental: false experimentalcli: false kubernetes: false swarm: false - option: limit-memory value_type: bytes default_value: "0" description: Limit Memory deprecated: false experimental: false experimentalcli: false kubernetes: false swarm: false - option: log-driver value_type: string description: Logging driver for service deprecated: false experimental: false experimentalcli: false kubernetes: false swarm: false - option: log-opt value_type: list description: Logging driver options deprecated: false experimental: false experimentalcli: false kubernetes: false swarm: false - option: mode value_type: string default_value: replicated description: Service mode (replicated or global) deprecated: false experimental: false experimentalcli: false kubernetes: false swarm: false - option: mount value_type: mount description: Attach a filesystem mount to the service deprecated: false experimental: false experimentalcli: false kubernetes: false swarm: false - option: name value_type: string description: Service name deprecated: false experimental: false experimentalcli: false kubernetes: false swarm: false - option: network value_type: network description: Network attachments deprecated: false experimental: false experimentalcli: false kubernetes: false swarm: false - option: no-healthcheck value_type: bool default_value: "false" description: Disable any container-specified HEALTHCHECK deprecated: false min_api_version: "1.25" experimental: false experimentalcli: false kubernetes: false swarm: false - option: no-resolve-image value_type: bool default_value: "false" description: | Do not query the registry to resolve image digest and supported platforms deprecated: false min_api_version: "1.30" experimental: false experimentalcli: false kubernetes: false swarm: false - option: placement-pref value_type: pref description: Add a placement preference deprecated: false min_api_version: "1.28" experimental: false experimentalcli: false kubernetes: false swarm: false - option: publish shorthand: p value_type: port description: Publish a port as a node port deprecated: false experimental: false experimentalcli: false kubernetes: false swarm: false - option: quiet shorthand: q value_type: bool default_value: "false" description: Suppress progress output deprecated: false experimental: false experimentalcli: false kubernetes: false swarm: false - option: read-only value_type: bool default_value: "false" description: Mount the container's root filesystem as read only deprecated: false min_api_version: "1.28" experimental: false experimentalcli: false kubernetes: false swarm: false - option: replicas value_type: uint description: Number of tasks deprecated: false experimental: false experimentalcli: false kubernetes: false swarm: false - option: reserve-cpu value_type: decimal description: Reserve CPUs deprecated: false experimental: false experimentalcli: false kubernetes: false swarm: false - option: reserve-memory value_type: bytes default_value: "0" description: Reserve Memory deprecated: false experimental: false experimentalcli: false kubernetes: false swarm: false - option: restart-condition value_type: string description: | Restart when condition is met ("none"|"on-failure"|"any") (default "any") deprecated: false experimental: false experimentalcli: false kubernetes: false swarm: false - option: restart-delay value_type: duration description: Delay between restart attempts (ns|us|ms|s|m|h) (default 5s) deprecated: false experimental: false experimentalcli: false kubernetes: false swarm: false - option: restart-max-attempts value_type: uint description: Maximum number of restarts before giving up deprecated: false experimental: false experimentalcli: false kubernetes: false swarm: false - option: restart-window value_type: duration description: Window used to evaluate the restart policy (ns|us|ms|s|m|h) deprecated: false experimental: false experimentalcli: false kubernetes: false swarm: false - option: rollback-delay value_type: duration default_value: 0s description: Delay between task rollbacks (ns|us|ms|s|m|h) (default 0s) deprecated: false min_api_version: "1.28" experimental: false experimentalcli: false kubernetes: false swarm: false - option: rollback-failure-action value_type: string description: | Action on rollback failure ("pause"|"continue") (default "pause") deprecated: false min_api_version: "1.28" experimental: false experimentalcli: false kubernetes: false swarm: false - option: rollback-max-failure-ratio value_type: float default_value: "0" description: Failure rate to tolerate during a rollback (default 0) deprecated: false min_api_version: "1.28" experimental: false experimentalcli: false kubernetes: false swarm: false - option: rollback-monitor value_type: duration default_value: 0s description: | Duration after each task rollback to monitor for failure (ns|us|ms|s|m|h) (default 5s) deprecated: false min_api_version: "1.28" experimental: false experimentalcli: false kubernetes: false swarm: false - option: rollback-order value_type: string description: | Rollback order ("start-first"|"stop-first") (default "stop-first") deprecated: false min_api_version: "1.29" experimental: false experimentalcli: false kubernetes: false swarm: false - option: rollback-parallelism value_type: uint64 default_value: "1" description: | Maximum number of tasks rolled back simultaneously (0 to roll back all at once) deprecated: false min_api_version: "1.28" experimental: false experimentalcli: false kubernetes: false swarm: false - option: secret value_type: secret description: Specify secrets to expose to the service deprecated: false min_api_version: "1.25" experimental: false experimentalcli: false kubernetes: false swarm: false - option: stop-grace-period value_type: duration description: | Time to wait before force killing a container (ns|us|ms|s|m|h) (default 10s) deprecated: false experimental: false experimentalcli: false kubernetes: false swarm: false - option: stop-signal value_type: string description: Signal to stop the container deprecated: false min_api_version: "1.28" experimental: false experimentalcli: false kubernetes: false swarm: false - option: tty shorthand: t value_type: bool default_value: "false" description: Allocate a pseudo-TTY deprecated: false min_api_version: "1.25" experimental: false experimentalcli: false kubernetes: false swarm: false - option: update-delay value_type: duration default_value: 0s description: Delay between updates (ns|us|ms|s|m|h) (default 0s) deprecated: false experimental: false experimentalcli: false kubernetes: false swarm: false - option: update-failure-action value_type: string description: | Action on update failure ("pause"|"continue"|"rollback") (default "pause") deprecated: false experimental: false experimentalcli: false kubernetes: false swarm: false - option: update-max-failure-ratio value_type: float default_value: "0" description: Failure rate to tolerate during an update (default 0) deprecated: false min_api_version: "1.25" experimental: false experimentalcli: false kubernetes: false swarm: false - option: update-monitor value_type: duration default_value: 0s description: | Duration after each task update to monitor for failure (ns|us|ms|s|m|h) (default 5s) deprecated: false min_api_version: "1.25" experimental: false experimentalcli: false kubernetes: false swarm: false - option: update-order value_type: string description: | Update order ("start-first"|"stop-first") (default "stop-first") deprecated: false min_api_version: "1.29" experimental: false experimentalcli: false kubernetes: false swarm: false - option: update-parallelism value_type: uint64 default_value: "1" description: | Maximum number of tasks updated simultaneously (0 to update all at once) deprecated: false experimental: false experimentalcli: false kubernetes: false swarm: false - option: user shorthand: u value_type: string description: 'Username or UID (format: [:])' deprecated: false experimental: false experimentalcli: false kubernetes: false swarm: false - option: with-registry-auth value_type: bool default_value: "false" description: Send registry authentication details to swarm agents deprecated: false experimental: false experimentalcli: false kubernetes: false swarm: false - option: workdir shorthand: w value_type: string description: Working directory inside the container deprecated: false experimental: false experimentalcli: false kubernetes: false swarm: false examples: "### Create a service\n\n```bash\n$ docker service create --name redis redis:3.0.6\n\ndmu1ept4cxcfe8k8lhtux3ro3\n\n$ docker service create --mode global --name redis2 redis:3.0.6\n\na8q9dasaafudfs8q8w32udass\n\n$ docker service ls\n\nID NAME MODE REPLICAS IMAGE\ndmu1ept4cxcf \ redis replicated 1/1 redis:3.0.6\na8q9dasaafud redis2 global 1/1 \ redis:3.0.6\n```\n\n#### Create a service using an image on a private registry\n\nIf your image is available on a private registry which requires login, use the\n`--with-registry-auth` flag with `docker service create`, after logging in. If\nyour image is stored on `registry.example.com`, which is a private registry, use\na command like the following:\n\n```bash\n$ docker login registry.example.com\n\n$ docker service create \\\n --with-registry-auth \\\n --name my_service \\\n registry.example.com/acme/my_image:latest\n```\n\nThis passes the login token from your local client to the swarm nodes where the\nservice is deployed, using the encrypted WAL logs. With this information, the\nnodes are able to log into the registry and pull the image.\n\n### Create a service with 5 replica tasks (--replicas)\n\nUse the `--replicas` flag to set the number of replica tasks for a replicated\nservice. The following command creates a `redis` service with `5` replica tasks:\n\n```bash\n$ docker service create --name redis --replicas=5 redis:3.0.6\n\n4cdgfyky7ozwh3htjfw0d12qv\n```\n\nThe above command sets the *desired* number of tasks for the service. Even\nthough the command returns immediately, actual scaling of the service may take\nsome time. The `REPLICAS` column shows both the *actual* and *desired* number\nof replica tasks for the service.\n\nIn the following example the desired state is `5` replicas, but the current\nnumber of `RUNNING` tasks is `3`:\n\n```bash\n$ docker service ls\n\nID NAME MODE REPLICAS \ IMAGE\n4cdgfyky7ozw redis replicated 3/5 redis:3.0.7\n```\n\nOnce all the tasks are created and `RUNNING`, the actual number of tasks is\nequal to the desired number:\n\n```bash\n$ docker service ls\n\nID NAME MODE REPLICAS \ IMAGE\n4cdgfyky7ozw redis replicated 5/5 redis:3.0.7\n```\n\n### Create a service with secrets\n\nUse the `--secret` flag to give a container access to a\n[secret](secret_create.md).\n\nCreate a service specifying a secret:\n\n```bash\n$ docker service create --name redis --secret secret.json redis:3.0.6\n\n4cdgfyky7ozwh3htjfw0d12qv\n```\n\nCreate a service specifying the secret, target, user/group ID, and mode:\n\n```bash\n$ docker service create --name redis \\\n --secret source=ssh-key,target=ssh \\\n \ --secret source=app-key,target=app,uid=1000,gid=1001,mode=0400 \\\n redis:3.0.6\n\n4cdgfyky7ozwh3htjfw0d12qv\n```\n\nTo grant a service access to multiple secrets, use multiple `--secret` flags.\n\nSecrets are located in `/run/secrets` in the container. If no target is\nspecified, the name of the secret will be used as the in memory file in the\ncontainer. If a target is specified, that will be the filename. In the\nexample above, two files will be created: `/run/secrets/ssh` and\n`/run/secrets/app` for each of the secret targets specified.\n\n### Create a service with a rolling update policy\n\n```bash\n$ docker service create \\\n --replicas 10 \\\n --name redis \\\n --update-delay 10s \\\n \ --update-parallelism 2 \\\n redis:3.0.6\n```\n\nWhen you run a [service update](service_update.md), the scheduler updates a\nmaximum of 2 tasks at a time, with `10s` between updates. For more information,\nrefer to the [rolling updates\ntutorial](https://docs.docker.com/engine/swarm/swarm-tutorial/rolling-update/).\n\n### Set environment variables (-e, --env)\n\nThis sets an environmental variable for all tasks in a service. For example:\n\n```bash\n$ docker service create \\\n --name redis_2 \\\n --replicas 5 \\\n --env MYVAR=foo \\\n redis:3.0.6\n```\n\nTo specify multiple environment variables, specify multiple `--env` flags, each\nwith a separate key-value pair.\n\n```bash\n$ docker service create \\\n --name redis_2 \\\n --replicas 5 \\\n --env MYVAR=foo \\\n --env MYVAR2=bar \\\n redis:3.0.6\n```\n\n### Create a service with specific hostname (--hostname)\n\nThis option sets the docker service containers hostname to a specific string.\nFor example:\n\n```bash\n$ docker service create --name redis --hostname myredis redis:3.0.6\n```\n\n### Set metadata on a service (-l, --label)\n\nA label is a `key=value` pair that applies metadata to a service. To label a\nservice with two labels:\n\n```bash\n$ docker service create \\\n --name redis_2 \\\n --label com.example.foo=\"bar\"\n --label bar=baz \\\n \ redis:3.0.6\n```\n\nFor more information about labels, refer to [apply custom\nmetadata](https://docs.docker.com/engine/userguide/labels-custom-metadata/).\n\n### Add bind mounts, volumes or memory filesystems\n\nDocker supports three different kinds of mounts, which allow containers to read\nfrom or write to files or directories, either on the host operating system, or\non memory filesystems. These types are _data volumes_ (often referred to simply\nas volumes), _bind mounts_, and _tmpfs_.\n\nA **bind mount** makes a file or directory on the host available to the\ncontainer it is mounted within. A bind mount may be either read-only or\nread-write. For example, a container might share its host's DNS information by\nmeans of a bind mount of the host's `/etc/resolv.conf` or a container might\nwrite logs to its host's `/var/log/myContainerLogs` directory. If you use\nbind mounts and your host and containers have different notions of permissions,\naccess controls, or other such details, you will run into portability issues.\n\nA **named volume** is a mechanism for decoupling persistent data needed by your\ncontainer from the image used to create the container and from the host machine.\nNamed volumes are created and managed by Docker, and a named volume persists\neven when no container is currently using it. Data in named volumes can be\nshared between a container and the host machine, as well as between multiple\ncontainers. Docker uses a _volume driver_ to create, manage, and mount volumes.\nYou can back up or restore volumes using Docker commands.\n\nA **tmpfs** mounts a tmpfs inside a container for volatile data.\n\nConsider a situation where your image starts a lightweight web server. You could\nuse that image as a base image, copy in your website's HTML files, and package\nthat into another image. Each time your website changed, you'd need to update\nthe new image and redeploy all of the containers serving your website. A better\nsolution is to store the website in a named volume which is attached to each of\nyour web server containers when they start. To update the website, you just\nupdate the named volume.\n\nFor more information about named volumes, see\n[Data Volumes](https://docs.docker.com/engine/tutorials/dockervolumes/).\n\nThe following table describes options which apply to both bind mounts and named\nvolumes in a service:\n\n\n \n \n \n \n \ \n \n \n \n \n \n \n \ \n \n \ \n \n \n \n \ \n \n \n \n \n \n \n \ \n \n \n \n \n \ \n
OptionRequiredDescription
types\n

The type of mount, can be either volume, bind, or tmpfs. Defaults to volume if no type is specified.\n

    \n
  • volume: mounts a managed volume\n into the container.
  • bind:\n bind-mounts a directory or file from the host into the container.
    • \n
  • tmpfs: mount a tmpfs in the container
    • \n

\n
src or sourcefor type=bind only>\n
    \n
  • \n type=volume: src is an optional way to specify the name of the volume (for example, src=my-volume).\n \ If the named volume does not exist, it is automatically created. If no src is specified, the volume is\n assigned a random name which is guaranteed to be unique on the host, but may not be unique cluster-wide.\n A randomly-named volume has the same lifecycle as its container and is destroyed when the container\n is destroyed (which is upon service update, or when scaling or re-balancing the service)\n
    • \n
  • \n type=bind: src is required, and specifies an absolute path to the file or directory to bind-mount\n (for example, src=/path/on/host/). An error is produced if the file or directory does not exist.\n
    • \n
  • \n \ type=tmpfs: src is not supported.\n
    • \n
\n \

dst or destination or target

yes\n

Mount path inside the container, for example /some/path/in/container/.\n If the path does not exist in the container's filesystem, the Engine creates\n a directory at the specified location before mounting the volume or bind mount.

\n

readonly or ro

\n

The Engine mounts binds and volumes read-write unless readonly option\n is given when mounting the bind or volume.\n

    \n
  • true or 1 or no value: Mounts the bind or volume read-only.
    • \n
  • false or 0: Mounts the bind or volume read-write.
    • \n

\n
consistency\n

The consistency requirements for the mount; one of\n

    \n
  • default: Equivalent to consistent.
    • \n
  • consistent: Full consistency. The container runtime and the host maintain an identical view of the mount at all times.
    • \n
  • cached: The host's view of the mount is authoritative. There may be delays before updates made on the host are visible within a container.
    • \n
  • delegated: The container runtime's view of the mount is authoritative. There may be delays before updates made in a container are visible on the host.
    • \n
\n

\n
\n\n#### Bind Propagation\n\nBind propagation refers to whether or not mounts created within a given\nbind mount or named volume can be propagated to replicas of that mount. Consider\na mount point `/mnt`, which is also mounted on `/tmp`. The propation settings\ncontrol whether a mount on `/tmp/a` would also be available on `/mnt/a`. Each\npropagation setting has a recursive counterpoint. In the case of recursion,\nconsider that `/tmp/a` is also mounted as `/foo`. The propagation settings\ncontrol whether `/mnt/a` and/or `/tmp/a` would exist.\n\nThe `bind-propagation` option defaults to `rprivate` for both bind mounts and\nvolume mounts, and is only configurable for bind mounts. In other words, named\nvolumes do not support bind propagation.\n\n- **`shared`**: Sub-mounts of the original mount are exposed to replica mounts,\n and sub-mounts of replica mounts are also propagated to the\n original mount.\n- **`slave`**: similar to a shared mount, but only in one direction. If the\n original mount exposes a sub-mount, the replica mount can see it.\n However, if the replica mount exposes a sub-mount, the original\n mount cannot see it.\n- **`private`**: The mount is private. Sub-mounts within it are not exposed to\n replica mounts, and sub-mounts of replica mounts are not\n \ exposed to the original mount.\n- **`rshared`**: The same as shared, but the propagation also extends to and from\n mount points nested within any of the original or replica mount\n points.\n- **`rslave`**: The same as `slave`, but the propagation also extends to and from\n mount points nested within any of the original or replica mount\n points.\n- **`rprivate`**: The default. The same as `private`, meaning that no mount points\n \ anywhere within the original or replica mount points propagate\n \ in either direction.\n\nFor more information about bind propagation, see the\n[Linux kernel documentation for shared subtree](https://www.kernel.org/doc/Documentation/filesystems/sharedsubtree.txt).\n\n#### Options for Named Volumes\n\nThe following options can only be used for named volumes (`type=volume`):\n\n\n\n \n \n \n \ \n \n \n \n \n \n \n \n \n \n \n \ \n \n \n \ \n \n \n
OptionDescription
volume-driver\n

Name of the volume-driver plugin to use for the volume. Defaults to\n \"local\", to use the local volume driver to create the volume if the\n volume does not exist.

\n
volume-label\n \ One or more custom metadata (\"labels\") to apply to the volume upon\n creation. For example,\n volume-label=mylabel=hello-world,my-other-label=hello-mars. For more\n information about labels, refer to\n apply custom metadata.\n
volume-nocopy\n By default, if you attach an empty volume to a container, and files or\n directories already existed at the mount-path in the container (dst),\n \ the Engine copies those files and directories into the volume, allowing\n \ the host to access them. Set volume-nocopy to disable copying files\n \ from the container's filesystem to the volume and mount the empty volume.
\n\n A value is optional:\n\n
    \n
  • true or 1: Default if you do not provide a value. Disables copying.
    • \n
  • false or 0: Enables copying.
    • \n
\n
volume-opt\n Options specific to a given volume driver, which will be passed to the\n driver when creating the volume. Options are provided as a comma-separated\n list of key/value pairs, for example,\n \ volume-opt=some-option=some-value,volume-opt=some-other-option=some-other-value.\n \ For available options for a given driver, refer to that driver's\n documentation.\n \
\n\n\n#### Options for tmpfs\n\nThe following options can only be used for tmpfs mounts (`type=tmpfs`);\n\n\n\n \n \n \ \n \n \n \n \n \n \n \ \n \n \n
OptionDescription
tmpfs-sizeSize of the tmpfs mount in bytes. Unlimited by default in Linux.
tmpfs-modeFile mode of the tmpfs in octal. (e.g. \"700\" or \"0700\".) Defaults to \"1777\" in Linux.
\n\n\n#### Differences between \"--mount\" and \"--volume\"\n\nThe `--mount` flag supports most options that are supported by the `-v`\nor `--volume` flag for `docker run`, with some important exceptions:\n\n- The `--mount` flag allows you to specify a volume driver and volume driver\n options *per volume*, without creating the volumes in advance. In contrast,\n `docker run` allows you to specify a single volume driver which is shared\n by all volumes, using the `--volume-driver` flag.\n\n- The `--mount` flag allows you to specify custom metadata (\"labels\") for a volume,\n before the volume is created.\n\n- When you use `--mount` with `type=bind`, the host-path must refer to an *existing*\n path on the host. The path will not be created for you and the service will fail\n with an error if the path does not exist.\n\n- The `--mount` flag does not allow you to relabel a volume with `Z` or `z` flags,\n \ which are used for `selinux` labeling.\n\n#### Create a service using a named volume\n\nThe following example creates a service that uses a named volume:\n\n```bash\n$ docker service create \\\n --name my-service \\\n --replicas 3 \\\n --mount type=volume,source=my-volume,destination=/path/in/container,volume-label=\"color=red\",volume-label=\"shape=round\" \\\n nginx:alpine\n```\n\nFor each replica of the service, the engine requests a volume named \"my-volume\"\nfrom the default (\"local\") volume driver where the task is deployed. If the\nvolume does not exist, the engine creates a new volume and applies the \"color\"\nand \"shape\" labels.\n\nWhen the task is started, the volume is mounted on `/path/in/container/` inside\nthe container.\n\nBe aware that the default (\"local\") volume is a locally scoped volume driver.\nThis means that depending on where a task is deployed, either that task gets a\n*new* volume named \"my-volume\", or shares the same \"my-volume\" with other tasks\nof the same service. Multiple containers writing to a single shared volume can\ncause data corruption if the software running inside the container is not\ndesigned to handle concurrent processes writing to the same location. Also take\ninto account that containers can be re-scheduled by the Swarm orchestrator and\nbe deployed on a different node.\n\n#### Create a service that uses an anonymous volume\n\nThe following command creates a service with three replicas with an anonymous\nvolume on `/path/in/container`:\n\n```bash\n$ docker service create \\\n --name my-service \\\n --replicas 3 \\\n --mount type=volume,destination=/path/in/container \\\n nginx:alpine\n```\n\nIn this example, no name (`source`) is specified for the volume, so a new volume\nis created for each task. This guarantees that each task gets its own volume,\nand volumes are not shared between tasks. Anonymous volumes are removed after\nthe task using them is complete.\n\n#### Create a service that uses a bind-mounted host directory\n\nThe following example bind-mounts a host directory at `/path/in/container` in\nthe containers backing the service:\n\n```bash\n$ docker service create \\\n --name my-service \\\n --mount type=bind,source=/path/on/host,destination=/path/in/container \\\n nginx:alpine\n```\n\n### Set service mode (--mode)\n\nThe service mode determines whether this is a _replicated_ service or a _global_\nservice. A replicated service runs as many tasks as specified, while a global\nservice runs on each active node in the swarm.\n\nThe following command creates a global service:\n\n```bash\n$ docker service create \\\n --name redis_2 \\\n --mode global \\\n redis:3.0.6\n```\n\n### Specify service constraints (--constraint)\n\nYou can limit the set of nodes where a task can be scheduled by defining\nconstraint expressions. Multiple constraints find nodes that satisfy every\nexpression (AND match). Constraints can match node or Docker Engine labels as\nfollows:\n\n\n\n \n \n \ \n \n \n \n \n \ \n \n \n \n \ \n \n \n \ \n \n \n \n \n \ \n \n \n \n \ \n \n \n \n \ \n \n \n
node attributematchesexample
node.idNode IDnode.id==2ivku8v2gvtg4
node.hostnameNode hostnamenode.hostname!=node-2
node.roleNode rolenode.role==manager
node.labelsuser defined node labelsnode.labels.security==high
engine.labelsDocker Engine's labelsengine.labels.operatingsystem==ubuntu 14.04
\n\n\n`engine.labels` apply to Docker Engine labels like operating system,\ndrivers, etc. Swarm administrators add `node.labels` for operational purposes by\nusing the [`docker node update`](node_update.md) command.\n\nFor example, the following limits tasks for the redis service to nodes where the\nnode type label equals queue:\n\n```bash\n$ docker service create \\\n --name redis_2 \\\n --constraint 'node.labels.type == queue' \\\n redis:3.0.6\n```\n\n### Specify service placement preferences (--placement-pref)\n\nYou can set up the service to divide tasks evenly over different categories of\nnodes. One example of where this can be useful is to balance tasks over a set\nof datacenters or availability zones. The example below illustrates this:\n\n```bash\n$ docker service create \\\n --replicas 9 \\\n --name redis_2 \\\n --placement-pref 'spread=node.labels.datacenter' \\\n \ redis:3.0.6\n```\n\nThis uses `--placement-pref` with a `spread` strategy (currently the only\nsupported strategy) to spread tasks evenly over the values of the `datacenter`\nnode label. In this example, we assume that every node has a `datacenter` node\nlabel attached to it. If there are three different values of this label among\nnodes in the swarm, one third of the tasks will be placed on the nodes\nassociated with each value. This is true even if there are more nodes with one\nvalue than another. For example, consider the following set of nodes:\n\n- Three nodes with `node.labels.datacenter=east`\n- Two nodes with `node.labels.datacenter=south`\n- One node with `node.labels.datacenter=west`\n\nSince we are spreading over the values of the `datacenter` label and the\nservice has 9 replicas, 3 replicas will end up in each datacenter. There are\nthree nodes associated with the value `east`, so each one will get one of the\nthree replicas reserved for this value. There are two nodes with the value\n`south`, and the three replicas for this value will be divided between them,\nwith one receiving two replicas and another receiving just one. Finally, `west`\nhas a single node that will get all three replicas reserved for `west`.\n\nIf the nodes in one category (for example, those with\n`node.labels.datacenter=south`) can't handle their fair share of tasks due to\nconstraints or resource limitations, the extra tasks will be assigned to other\nnodes instead, if possible.\n\nBoth engine labels and node labels are supported by placement preferences. The\nexample above uses a node label, because the label is referenced with\n`node.labels.datacenter`. To spread over the values of an engine label, use\n`--placement-pref spread=engine.labels.`.\n\nIt is possible to add multiple placement preferences to a service. This\nestablishes a hierarchy of preferences, so that tasks are first divided over\none category, and then further divided over additional categories. One example\nof where this may be useful is dividing tasks fairly between datacenters, and\nthen splitting the tasks within each datacenter over a choice of racks. To add\nmultiple placement preferences, specify the `--placement-pref` flag multiple\ntimes. The order is significant, and the placement preferences will be applied\nin the order given when making scheduling decisions.\n\nThe following example sets up a service with multiple placement preferences.\nTasks are spread first over the various datacenters, and then over racks\n(as indicated by the respective labels):\n\n```bash\n$ docker service create \\\n --replicas 9 \\\n --name redis_2 \\\n --placement-pref 'spread=node.labels.datacenter' \\\n \ --placement-pref 'spread=node.labels.rack' \\\n redis:3.0.6\n```\n\nWhen updating a service with `docker service update`, `--placement-pref-add`\nappends a new placement preference after all existing placement preferences.\n`--placement-pref-rm` removes an existing placement preference that matches the\nargument.\n\n### Attach a service to an existing network (--network)\n\nYou can use overlay networks to connect one or more services within the swarm.\n\nFirst, create an overlay network on a manager node the docker network create\ncommand:\n\n```bash\n$ docker network create --driver overlay my-network\n\netjpu59cykrptrgw0z0hk5snf\n```\n\nAfter you create an overlay network in swarm mode, all manager nodes have\naccess to the network.\n\nWhen you create a service and pass the `--network` flag to attach the service to\nthe overlay network:\n\n```bash\n$ docker service create \\\n --replicas 3 \\\n --network my-network \\\n --name my-web \\\n nginx\n\n716thylsndqma81j6kkkb5aus\n```\n\nThe swarm extends my-network to each node running the service.\n\nContainers on the same network can access each other using\n[service discovery](https://docs.docker.com/engine/swarm/networking/#use-swarm-mode-service-discovery).\n\nLong form syntax of `--network` allows to specify list of aliases and driver options: \ \n`--network name=my-network,alias=web1,driver-opt=field1=value1`\n\n### Publish service ports externally to the swarm (-p, --publish)\n\nYou can publish service ports to make them available externally to the swarm\nusing the `--publish` flag. The `--publish` flag can take two different styles\nof arguments. The short version is positional, and allows you to specify the\npublished port and target port separated by a colon.\n\n```bash\n$ docker service create --name my_web --replicas 3 --publish 8080:80 nginx\n```\n\nThere is also a long format, which is easier to read and allows you to specify\nmore options. The long format is preferred. You cannot specify the service's\nmode when using the short format. Here is an example of using the long format\nfor the same service as above:\n\n```bash\n$ docker service create --name my_web --replicas 3 --publish published=8080,target=80 nginx\n```\n\nThe options you can specify are:\n\n\n\n\n \n \n \ \n \n\n\n\n \n \n \n \n\n\n \n \n \n \ \n\n\n \ \n \n \n \n\n
OptionShort syntaxLong syntaxDescription
published and target port--publish 8080:80--publish published=8080,target=80

\n The target port within the container and the port to map it to on the\n nodes, using the routing mesh (ingress) or host-level networking.\n More options are available, later in this table. The key-value syntax is\n preferred, because it is somewhat self-documenting.\n \

modeNot possible to set using short syntax.--publish published=8080,target=80,mode=host

\n The mode to use for binding the port, either ingress or host.\n Defaults to ingress to use the routing mesh.\n

protocol--publish 8080:80/tcp--publish published=8080,target=80,protocol=tcp

\n The protocol to use, tcp , udp, or sctp. Defaults to\n tcp. To bind a port for both protocols, specify the -p or\n --publish flag twice.\n

\n\nWhen you publish a service port using `ingress` mode, the swarm routing mesh\nmakes the service accessible at the published port on every node regardless if\nthere is a task for the service running on the node. If you use `host` mode,\nthe port is only bound on nodes where the service is running, and a given port\non a node can only be bound once. You can only set the publication mode using\nthe long syntax. For more information refer to\n[Use swarm mode routing mesh](https://docs.docker.com/engine/swarm/ingress/).\n\n### Provide credential specs for managed service accounts (Windows only)\n\nThis option is only used for services using Windows containers. The\n`--credential-spec` must be in the format `file://` or\n`registry://`.\n\nWhen using the `file://` format, the referenced file must be\npresent in the `CredentialSpecs` subdirectory in the docker data directory,\nwhich defaults to `C:\\ProgramData\\Docker\\` on Windows. For example,\nspecifying `file://spec.json` loads `C:\\ProgramData\\Docker\\CredentialSpecs\\spec.json`.\n\nWhen using the `registry://` format, the credential spec is\nread from the Windows registry on the daemon's host. The specified\nregistry value must be located in:\n\n HKLM\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\Virtualization\\Containers\\CredentialSpecs\n\n\n### Create services using templates\n\nYou can use templates for some flags of `service create`, using the syntax\nprovided by the Go's [text/template](http://golang.org/pkg/text/template/) package.\n\nThe supported flags are the following :\n\n- `--hostname`\n- `--mount`\n- `--env`\n\nValid placeholders for the Go template are listed below:\n\n\n\n \ \n \n \n \n \n \n \ \n \n \n \n \ \n \n \n \n \ \n \n \n \n \n \n \n \n \n \ \n \n \n \n \n \ \n \n \n \n \n \ \n \n \n
PlaceholderDescription
.Service.IDService ID
.Service.NameService name
.Service.LabelsService labels
.Node.IDNode ID
.Node.HostnameNode Hostname
.Task.IDTask ID
.Task.NameTask name
.Task.SlotTask slot
\n\n\n#### Template example\n\nIn this example, we are going to set the template of the created containers based on the\nservice's name, the node's ID and hostname where it sits.\n\n```bash\n$ docker service create --name hosttempl \\\n --hostname=\"{{.Node.Hostname}}-{{.Node.ID}}-{{.Service.Name}}\"\\\n \ busybox top\n\nva8ew30grofhjoychbr6iot8c\n\n$ docker service ps va8ew30grofhjoychbr6iot8c\n\nID NAME IMAGE NODE \ DESIRED STATE CURRENT STATE ERROR PORTS\nwo41w8hg8qan \ hosttempl.1 busybox:latest@sha256:29f5d56d12684887bdfa50dcd29fc31eea4aaf4ad3bec43daf19026a7ce69912 \ 2e7a8a9c4da2 Running Running about a minute ago\n\n$ docker inspect --format=\"{{.Config.Hostname}}\" 2e7a8a9c4da2-wo41w8hg8qanxwjwsg4kxpprj-hosttempl\n\nx3ti0erg11rjpg64m75kej2mz-hosttempl\n```\n\n### Specify isolation mode (Windows)\n\nBy default, tasks scheduled on Windows nodes are run using the default isolation mode\nconfigured for this particular node. To force a specific isolation mode, you can use\nthe `--isolation` flag:\n\n```bash\n$ docker service create --name myservice --isolation=process microsoft/nanoserver\n```\n\nSupported isolation modes on Windows are:\n- `default`: use default settings specified on the node running the task\n- `process`: use process isolation (Windows server only)\n- `hyperv`: use Hyper-V isolation\n\n### Create services requesting Generic Resources\n\nYou can narrow the kind of nodes your task can land on through the using the\n`--generic-resource` flag (if the nodes advertise these resources):\n\n```bash\n$ docker service create --name cuda \\\n --generic-resource \"NVIDIA-GPU=2\" \\\n \ --generic-resource \"SSD=1\" \\\n nvidia/cuda\n```" deprecated: false min_api_version: "1.24" experimental: false experimentalcli: false kubernetes: false swarm: true