docker service create (original) (raw)

SwarmThis command works with the Swarm orchestrator.

Creates a service as described by the specified parameters.

Note

This is a cluster management command, and must be executed on a swarm manager node. To learn about managers and workers, refer to theSwarm mode section in the documentation.

Create a service

Create a service using an image on a private registry (--with-registry-auth)

If your image is available on a private registry which requires login, use the--with-registry-auth flag with docker service create, after logging in. If your image is stored on registry.example.com, which is a private registry, use a command like the following:

This passes the login token from your local client to the swarm nodes where the service is deployed, using the encrypted WAL logs. With this information, the nodes are able to log in to the registry and pull the image.

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:

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:

Once all the tasks are created and RUNNING, the actual number of tasks is equal to the desired number:

Create a service with secrets (--secret)

Use the --secret flag to give a container access to asecret.

Create a service specifying a secret:

Create a service specifying the secret, target, user/group ID, and mode:

To grant a service access to multiple secrets, use multiple --secret flags.

Secrets are located in /run/secrets in the container if no target is specified. If no target is specified, the name of the secret is used as the in memory file in the container. If a target is specified, that is used as the filename. In the example above, two files are created: /run/secrets/ssh and/run/secrets/app for each of the secret targets specified.

Create a service with configs (--config)

Use the --config flag to give a container access to aconfig.

Create a service with a config. The config will be mounted into redis-config, be owned by the user who runs the command inside the container (often root), and have file mode 0444 or world-readable. You can specify the uid and gidas numerical IDs or names. When using names, the provided group/user names must pre-exist in the container. The mode is specified as a 4-number sequence such as 0755.

Create a service with a config and specify the target location and file mode:

To grant a service access to multiple configs, use multiple --config flags.

Configs are located in / in the container if no target is specified. If no target is specified, the name of the config is used as the name of the file in the container. If a target is specified, that is used as the filename.

Create a service with a rolling update policy

When you run aservice update, the scheduler updates a maximum of 2 tasks at a time, with 10s between updates. For more information, refer to therolling updates tutorial.

Set environment variables (-e, --env)

This sets an environment variable for all tasks in a service. For example:

To specify multiple environment variables, specify multiple --env flags, each with a separate key-value pair.

Create a service with specific hostname (--hostname)

This option sets the docker service containers hostname to a specific string. For example:

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:

For more information about labels, refer toapply custom metadata.

Add bind mounts, volumes or memory filesystems (--mount)

Docker supports three different kinds of mounts, which allow containers to read from or write to files or directories, either on the host operating system, or on memory filesystems. These types are data volumes (often referred to simply as volumes), bind mounts, tmpfs, and named pipes.

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.

A tmpfs mounts a tmpfs inside a container for volatile data.

A npipe mounts a named pipe from the host into the container.

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, seeData Volumes.

The following table describes options which apply to both bind mounts and named volumes in a service:

Options for bind mounts

The following options can only be used for bind mounts (type=bind):

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 propagation 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 theLinux kernel documentation for shared subtree.

Options for named volumes

The following options can only be used for named volumes (type=volume):

Options for tmpfs

The following options can only be used for tmpfs mounts (type=tmpfs);

Differences between "--mount" and "--volume"

The --mount flag supports most options that are supported by the -vor --volume flag for docker run, with some important exceptions:

• The --mount flag allows you to specify a volume driver and volume driver 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.
• The --mount flag allows you to specify custom metadata ("labels") for a volume, before the volume is created.
• When you use --mount with type=bind, the host-path must refer to an _existing_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.
• The --mount flag does not allow you to relabel a volume with Z or z flags, which are used for selinux labeling.

Create a service using a named volume

The following example creates a service that uses a named volume:

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 volume

The following command creates a service with three replicas with an anonymous volume on /path/in/container:

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.

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:

Set service mode (--mode)

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 service runs on each active node in the swarm.

The following command creates a global service:

Specify service constraints (--constraint)

You can limit the set of nodes where a task can be scheduled by defining constraint expressions. Constraint expressions can either use a match (==) or exclude (!=) rule. Multiple constraints find nodes that satisfy every expression (AND match). Constraints can match node or Docker Engine labels as follows:

engine.labels apply to Docker Engine labels like operating system, drivers, etc. Swarm administrators add node.labels for operational purposes by using thedocker node update command.

For example, the following limits tasks for the redis service to nodes where the node type label equals queue:

If the service constraints exclude all nodes in the cluster, a message is printed that no suitable node is found, but the scheduler will start a reconciliation loop and deploy the service once a suitable node becomes available.

In the example below, no node satisfying the constraint was found, causing the service to not reconcile with the desired state:

After adding the region=east label to a node in the cluster, the service reconciles, and the desired number of replicas are deployed:

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:

This uses --placement-pref with a spread strategy (currently the only supported strategy) to spread tasks evenly over the values of the datacenternode 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 valuesouth, and the three replicas for this value will be divided between them, with one receiving two replicas and another receiving just one. Finally, westhas a single node that will get all three replicas reserved for west.

If the nodes in one category (for example, those withnode.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 withnode.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):

When updating a service with docker service update, --placement-pref-addappends a new placement preference after all existing placement preferences.--placement-pref-rm removes an existing placement preference that matches the argument.

Specify memory requirements and constraints for a service (--reserve-memory and --limit-memory)

If your service needs a minimum amount of memory in order to run correctly, you can use --reserve-memory to specify that the service should only be scheduled on a node with this much memory available to reserve. If no node is available that meets the criteria, the task is not scheduled, but remains in a pending state.

The following example requires that 4GB of memory be available and reservable on a given node before scheduling the service to run on that node.

The managers won't schedule a set of containers on a single node whose combined reservations exceed the memory available on that node.

After a task is scheduled and running, --reserve-memory does not enforce a memory limit. Use --limit-memory to ensure that a task uses no more than a given amount of memory on a node. This example limits the amount of memory used by the task to 4GB. The task will be scheduled even if each of your nodes has only 2GB of memory, because --limit-memory is an upper limit.

Using --reserve-memory and --limit-memory does not guarantee that Docker will not use more memory on your host than you want. For instance, you could create many services, the sum of whose memory usage could exhaust the available memory.

You can prevent this scenario from exhausting the available memory by taking into account other (non-containerized) software running on the host as well. If--reserve-memory is greater than or equal to --limit-memory, Docker won't schedule a service on a host that doesn't have enough memory. --limit-memorywill limit the service's memory to stay within that limit, so if every service has a memory-reservation and limit set, Docker services will be less likely to saturate the host. Other non-service containers or applications running directly on the Docker host could still exhaust memory.

There is a downside to this approach. Reserving memory also means that you may not make optimum use of the memory available on the node. Consider a service that under normal circumstances uses 100MB of memory, but depending on load can "peak" at 500MB. Reserving 500MB for that service (to guarantee can have 500MB for those "peaks") results in 400MB of memory being wasted most of the time.

In short, you can take a more conservative or more flexible approach:

• Conservative: reserve 500MB, and limit to 500MB. Basically you're now treating the service containers as VMs, and you may be losing a big advantage containers, which is greater density of services per host.
• Flexible: limit to 500MB in the assumption that if the service requires more than 500MB, it is malfunctioning. Reserve something between the 100MB "normal" requirement and the 500MB "peak" requirement". This assumes that when this service is at "peak", other services or non-container workloads probably won't be.

The approach you take depends heavily on the memory-usage patterns of your workloads. You should test under normal and peak conditions before settling on an approach.

On Linux, you can also limit a service's overall memory footprint on a given host at the level of the host operating system, using cgroups or other relevant operating system tools.

Specify maximum replicas per node (--replicas-max-per-node)

Use the --replicas-max-per-node flag to set the maximum number of replica tasks that can run on a node. The following command creates a nginx service with 2 replica tasks but only one replica task per node.

One example where this can be useful is to balance tasks over a set of data centers together with --placement-prefand let --replicas-max-per-node setting make sure that replicas are not migrated to another datacenter during maintenance or datacenter failure.

The example below illustrates this:

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:

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:

The swarm extends my-network to each node running the service.

Containers on the same network can access each other usingservice discovery.

Long form syntax of --network allows to specify list of aliases and driver options:--network name=my-network,alias=web1,driver-opt=field1=value1

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. The --publish flag can take two different styles of arguments. The short version is positional, and allows you to specify the published port and target port separated by a colon (:).

There is also a long format, which is easier to read and allows you to specify more options. The long format is preferred. You cannot specify the service's mode when using the short format. Here is an example of using the long format for the same service as above:

The options you can specify are:

When you publish a service port using ingress mode, the swarm routing mesh makes the service accessible at the published port on every node regardless if there is a task for the service running on the node. If you use host mode, the port is only bound on nodes where the service is running, and a given port on a node can only be bound once. You can only set the publication mode using the long syntax. For more information refer toUse swarm mode routing mesh.

Provide credential specs for managed service accounts (--credentials-spec)

This option is only used for services using Windows containers. The--credential-spec must be in the format file://<filename> orregistry://<value-name>.

When using the file://<filename> format, the referenced file must be present in the CredentialSpecs subdirectory in the docker data directory, which defaults to C:\ProgramData\Docker\ on Windows. For example, specifying file://spec.json loads C:\ProgramData\Docker\CredentialSpecs\spec.json.

When using the registry://<value-name> format, the credential spec is read from the Windows registry on the daemon's host. The specified registry value must be located in:

HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Virtualization\Containers\CredentialSpecs

Create services using templates

You can use templates for some flags of service create, using the syntax provided by the Go'stext/template package.

The supported flags are the following :

• --hostname
• --mount
• --env

Valid placeholders for the Go template are listed below:

Template example

In this example, we are going to set the template of the created containers based on the service's name, the node's ID and hostname where it sits.

Specify isolation mode on Windows (--isolation)

By default, tasks scheduled on Windows nodes are run using the default isolation mode configured for this particular node. To force a specific isolation mode, you can use the --isolation flag:

Supported isolation modes on Windows are:

• default: use default settings specified on the node running the task
• process: use process isolation (Windows server only)
• hyperv: use Hyper-V isolation

Create services requesting Generic Resources (--generic-resources)

You can narrow the kind of nodes your task can land on through the using the--generic-resource flag (if the nodes advertise these resources):

Running as a job

Jobs are a special kind of service designed to run an operation to completion and then stop, as opposed to running long-running daemons. When a Task belonging to a job exits successfully (return value 0), the Task is marked as "Completed", and is not run again.

Jobs are started by using one of two modes, replicated-job or global-job

This command will run one Task, which will, using the bash image, execute the command true, which will return 0 and then exit.

Though Jobs are ultimately a different kind of service, they a couple of caveats compared to other services:

• None of the update or rollback configuration options are valid. Jobs can be updated, but cannot be rolled out or rolled back, making these configuration options moot.
• Jobs are never restarted on reaching the Complete state. This means that for jobs, setting --restart-condition to any is the same as setting it toon-failure.

Jobs are available in both replicated and global modes.

Replicated Jobs

A replicated job is like a replicated service. Setting the --replicas flag will specify total number of iterations of a job to execute.

By default, all replicas of a replicated job will launch at once. To control the total number of replicas that are executing simultaneously at any one time, the --max-concurrent flag can be used:

The above command will execute 10 Tasks in total, but only 2 of them will be run at any given time.

Global Jobs

Global jobs are like global services, in that a Task is executed once on each node matching placement constraints. Global jobs are represented by the mode global-job.

Note that after a Global job is created, any new Nodes added to the cluster will have a Task from that job started on them. The Global Job does not as a whole have a "done" state, except insofar as every Node meeting the job's constraints has a Completed task.