diff options
Diffstat (limited to 'devdocs/docker/engine%2Freference%2Fcommandline%2Fservice_create%2Findex.html')
| -rw-r--r-- | devdocs/docker/engine%2Freference%2Fcommandline%2Fservice_create%2Findex.html | 229 |
1 files changed, 229 insertions, 0 deletions
diff --git a/devdocs/docker/engine%2Freference%2Fcommandline%2Fservice_create%2Findex.html b/devdocs/docker/engine%2Freference%2Fcommandline%2Fservice_create%2Findex.html new file mode 100644 index 00000000..c9a18312 --- /dev/null +++ b/devdocs/docker/engine%2Freference%2Fcommandline%2Fservice_create%2Findex.html @@ -0,0 +1,229 @@ +<h1>docker service create</h1> <p><br></p> <p>Create a new service</p> <p><span class="badge badge-info" data-toggle="tooltip" data-placement="right" title="This command works with the Swarm orchestrator.">Swarm</span> This command works with the Swarm orchestrator.</p> <h2 id="usage">Usage</h2> <div class="highlight"><pre class="highlight" data-language="">$ docker service create [OPTIONS] IMAGE [COMMAND] [ARG...] +</pre></div> <p>Refer to the <a href="#options">options section</a> for an overview of available <a href="#options"><code class="language-plaintext highlighter-rouge">OPTIONS</code></a> for this command.</p> <h2 id="description">Description</h2> <p name="extended-description">Creates a service as described by the specified parameters.</p> <blockquote> <p><strong>Note</strong></p> <p>This is a cluster management command, and must be executed on a swarm manager node. To learn about managers and workers, refer to the <a href="../../../swarm/index">Swarm mode section</a> in the documentation.</p> </blockquote> <p>For example uses of this command, refer to the <a href="#examples">examples section</a> below.</p> <h2 id="options">Options</h2> <table> <thead> <tr> <td>Name, shorthand</td> <td>Default</td> <td>Description</td> </tr> </thead> <tbody> <tr> <td><code class="language-plaintext highlighter-rouge">--cap-add</code></td> <td></td> <td> +<a href="https://docs.docker.com/engine/api/v1.41/" target="_blank" rel="noopener" class="_"><span class="badge badge-info" data-toggle="tooltip" title="Open the 1.24 API reference (in a new window)">API 1.41+</span></a><br>Add Linux capabilities</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--cap-drop</code></td> <td></td> <td> +<a href="https://docs.docker.com/engine/api/v1.41/" target="_blank" rel="noopener" class="_"><span class="badge badge-info" data-toggle="tooltip" title="Open the 1.24 API reference (in a new window)">API 1.41+</span></a><br>Drop Linux capabilities</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--config</code></td> <td></td> <td> +<a href="https://docs.docker.com/engine/api/v1.41/" target="_blank" rel="noopener" class="_"><span class="badge badge-info" data-toggle="tooltip" title="Open the 1.24 API reference (in a new window)">API 1.41+</span></a><br>Specify configurations to expose to the service</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--constraint</code></td> <td></td> <td>Placement constraints</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--container-label</code></td> <td></td> <td>Container labels</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--credential-spec</code></td> <td></td> <td>Credential spec for managed service account (Windows only)</td> </tr> <tr> <td> +<code class="language-plaintext highlighter-rouge">--detach</code> , <code class="language-plaintext highlighter-rouge">-d</code> +</td> <td></td> <td>Exit immediately instead of waiting for the service to converge</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--dns</code></td> <td></td> <td>Set custom DNS servers</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--dns-option</code></td> <td></td> <td>Set DNS options</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--dns-search</code></td> <td></td> <td>Set custom DNS search domains</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--endpoint-mode</code></td> <td><code class="language-plaintext highlighter-rouge">vip</code></td> <td>Endpoint mode (vip or dnsrr)</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--entrypoint</code></td> <td></td> <td>Overwrite the default ENTRYPOINT of the image</td> </tr> <tr> <td> +<code class="language-plaintext highlighter-rouge">--env</code> , <code class="language-plaintext highlighter-rouge">-e</code> +</td> <td></td> <td>Set environment variables</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--env-file</code></td> <td></td> <td>Read in a file of environment variables</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--generic-resource</code></td> <td></td> <td>User defined resources</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--group</code></td> <td></td> <td>Set one or more supplementary user groups for the container</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--health-cmd</code></td> <td></td> <td>Command to run to check health</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--health-interval</code></td> <td></td> <td>Time between running the check (ms|s|m|h)</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--health-retries</code></td> <td></td> <td>Consecutive failures needed to report unhealthy</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--health-start-period</code></td> <td></td> <td>Start period for the container to initialize before counting retries towards unstable (ms|s|m|h)</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--health-timeout</code></td> <td></td> <td>Maximum time to allow one check to run (ms|s|m|h)</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--host</code></td> <td></td> <td>Set one or more custom host-to-IP mappings (host:ip)</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--hostname</code></td> <td></td> <td>Container hostname</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--init</code></td> <td></td> <td>Use an init inside each service container to forward signals and reap processes</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--isolation</code></td> <td></td> <td>Service container isolation mode</td> </tr> <tr> <td> +<code class="language-plaintext highlighter-rouge">--label</code> , <code class="language-plaintext highlighter-rouge">-l</code> +</td> <td></td> <td>Service labels</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--limit-cpu</code></td> <td></td> <td>Limit CPUs</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--limit-memory</code></td> <td></td> <td>Limit Memory</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--limit-pids</code></td> <td></td> <td> +<a href="https://docs.docker.com/engine/api/v1.41/" target="_blank" rel="noopener" class="_"><span class="badge badge-info" data-toggle="tooltip" title="Open the 1.24 API reference (in a new window)">API 1.41+</span></a><span class="badge badge-info" data-toggle="tooltip" title="This option works for the Swarm orchestrator.">Swarm</span><br>Limit maximum number of processes (default 0 = unlimited)</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--log-driver</code></td> <td></td> <td>Logging driver for service</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--log-opt</code></td> <td></td> <td>Logging driver options</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--max-concurrent</code></td> <td></td> <td> +<a href="https://docs.docker.com/engine/api/v1.41/" target="_blank" rel="noopener" class="_"><span class="badge badge-info" data-toggle="tooltip" title="Open the 1.24 API reference (in a new window)">API 1.41+</span></a><br>Number of job tasks to run concurrently (default equal to --replicas)</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--mode</code></td> <td><code class="language-plaintext highlighter-rouge">replicated</code></td> <td>Service mode (replicated, global, replicated-job, or global-job)</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--mount</code></td> <td></td> <td>Attach a filesystem mount to the service</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--name</code></td> <td></td> <td>Service name</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--network</code></td> <td></td> <td>Network attachments</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--no-healthcheck</code></td> <td></td> <td>Disable any container-specified HEALTHCHECK</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--no-resolve-image</code></td> <td></td> <td>Do not query the registry to resolve image digest and supported platforms</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--placement-pref</code></td> <td></td> <td>Add a placement preference</td> </tr> <tr> <td> +<code class="language-plaintext highlighter-rouge">--publish</code> , <code class="language-plaintext highlighter-rouge">-p</code> +</td> <td></td> <td>Publish a port as a node port</td> </tr> <tr> <td> +<code class="language-plaintext highlighter-rouge">--quiet</code> , <code class="language-plaintext highlighter-rouge">-q</code> +</td> <td></td> <td>Suppress progress output</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--read-only</code></td> <td></td> <td>Mount the container's root filesystem as read only</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--replicas</code></td> <td></td> <td>Number of tasks</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--replicas-max-per-node</code></td> <td></td> <td> +<a href="https://docs.docker.com/engine/api/v1.40/" target="_blank" rel="noopener" class="_"><span class="badge badge-info" data-toggle="tooltip" title="Open the 1.24 API reference (in a new window)">API 1.40+</span></a><br>Maximum number of tasks per node (default 0 = unlimited)</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--reserve-cpu</code></td> <td></td> <td>Reserve CPUs</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--reserve-memory</code></td> <td></td> <td>Reserve Memory</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--restart-condition</code></td> <td></td> <td>Restart when condition is met ("none"|"on-failure"|"any") (default "any")</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--restart-delay</code></td> <td></td> <td>Delay between restart attempts (ns|us|ms|s|m|h) (default 5s)</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--restart-max-attempts</code></td> <td></td> <td>Maximum number of restarts before giving up</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--restart-window</code></td> <td></td> <td>Window used to evaluate the restart policy (ns|us|ms|s|m|h)</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--rollback-delay</code></td> <td></td> <td>Delay between task rollbacks (ns|us|ms|s|m|h) (default 0s)</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--rollback-failure-action</code></td> <td></td> <td>Action on rollback failure ("pause"|"continue") (default "pause")</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--rollback-max-failure-ratio</code></td> <td></td> <td>Failure rate to tolerate during a rollback (default 0)</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--rollback-monitor</code></td> <td></td> <td>Duration after each task rollback to monitor for failure (ns|us|ms|s|m|h) (default 5s)</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--rollback-order</code></td> <td></td> <td>Rollback order ("start-first"|"stop-first") (default "stop-first")</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--rollback-parallelism</code></td> <td><code class="language-plaintext highlighter-rouge">1</code></td> <td>Maximum number of tasks rolled back simultaneously (0 to roll back all at once)</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--secret</code></td> <td></td> <td>Specify secrets to expose to the service</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--stop-grace-period</code></td> <td></td> <td>Time to wait before force killing a container (ns|us|ms|s|m|h) (default 10s)</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--stop-signal</code></td> <td></td> <td>Signal to stop the container</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--sysctl</code></td> <td></td> <td> +<a href="https://docs.docker.com/engine/api/v1.40/" target="_blank" rel="noopener" class="_"><span class="badge badge-info" data-toggle="tooltip" title="Open the 1.24 API reference (in a new window)">API 1.40+</span></a><br>Sysctl options</td> </tr> <tr> <td> +<code class="language-plaintext highlighter-rouge">--tty</code> , <code class="language-plaintext highlighter-rouge">-t</code> +</td> <td></td> <td> +<a href="https://docs.docker.com/engine/api/v1.40/" target="_blank" rel="noopener" class="_"><span class="badge badge-info" data-toggle="tooltip" title="Open the 1.24 API reference (in a new window)">API 1.40+</span></a><br>Allocate a pseudo-TTY</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--ulimit</code></td> <td></td> <td> +<a href="https://docs.docker.com/engine/api/v1.41/" target="_blank" rel="noopener" class="_"><span class="badge badge-info" data-toggle="tooltip" title="Open the 1.24 API reference (in a new window)">API 1.41+</span></a><br>Ulimit options</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--update-delay</code></td> <td></td> <td>Delay between updates (ns|us|ms|s|m|h) (default 0s)</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--update-failure-action</code></td> <td></td> <td>Action on update failure ("pause"|"continue"|"rollback") (default "pause")</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--update-max-failure-ratio</code></td> <td></td> <td>Failure rate to tolerate during an update (default 0)</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--update-monitor</code></td> <td></td> <td>Duration after each task update to monitor for failure (ns|us|ms|s|m|h) (default 5s)</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--update-order</code></td> <td></td> <td>Update order ("start-first"|"stop-first") (default "stop-first")</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--update-parallelism</code></td> <td><code class="language-plaintext highlighter-rouge">1</code></td> <td>Maximum number of tasks updated simultaneously (0 to update all at once)</td> </tr> <tr> <td> +<code class="language-plaintext highlighter-rouge">--user</code> , <code class="language-plaintext highlighter-rouge">-u</code> +</td> <td></td> <td>Username or UID (format: <name|uid>[:<group|gid>])</td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">--with-registry-auth</code></td> <td></td> <td>Send registry authentication details to swarm agents</td> </tr> <tr> <td> +<code class="language-plaintext highlighter-rouge">--workdir</code> , <code class="language-plaintext highlighter-rouge">-w</code> +</td> <td></td> <td>Working directory inside the container</td> </tr> </tbody> </table> <h2 id="examples">Examples</h2> <h3 id="create-a-service">Create a service</h3> <div class="highlight"><pre class="highlight" data-language="">$ docker service create --name redis redis:3.0.6 + +dmu1ept4cxcfe8k8lhtux3ro3 + +$ docker service create --mode global --name redis2 redis:3.0.6 + +a8q9dasaafudfs8q8w32udass + +$ docker service ls + +ID NAME MODE REPLICAS IMAGE +dmu1ept4cxcf redis replicated 1/1 redis:3.0.6 +a8q9dasaafud redis2 global 1/1 redis:3.0.6 +</pre></div> <h4 id="create-a-service-using-an-image-on-a-private-registry">Create a service using an image on a private registry</h4> <p>If your image is available on a private registry which requires login, use the <code class="language-plaintext highlighter-rouge">--with-registry-auth</code> flag with <code class="language-plaintext highlighter-rouge">docker service create</code>, after logging in. If your image is stored on <code class="language-plaintext highlighter-rouge">registry.example.com</code>, which is a private registry, use a command like the following:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker login registry.example.com + +$ docker service create \ + --with-registry-auth \ + --name my_service \ + registry.example.com/acme/my_image:latest +</pre></div> <p>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 into the registry and pull the image.</p> <h3 id="create-a-service-with-5-replica-tasks---replicas">Create a service with 5 replica tasks (--replicas)</h3> <p>Use the <code class="language-plaintext highlighter-rouge">--replicas</code> flag to set the number of replica tasks for a replicated service. The following command creates a <code class="language-plaintext highlighter-rouge">redis</code> service with <code class="language-plaintext highlighter-rouge">5</code> replica tasks:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker service create --name redis --replicas=5 redis:3.0.6 + +4cdgfyky7ozwh3htjfw0d12qv +</pre></div> <p>The above command sets the <em>desired</em> number of tasks for the service. Even though the command returns immediately, actual scaling of the service may take some time. The <code class="language-plaintext highlighter-rouge">REPLICAS</code> column shows both the <em>actual</em> and <em>desired</em> number of replica tasks for the service.</p> <p>In the following example the desired state is <code class="language-plaintext highlighter-rouge">5</code> replicas, but the current number of <code class="language-plaintext highlighter-rouge">RUNNING</code> tasks is <code class="language-plaintext highlighter-rouge">3</code>:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker service ls + +ID NAME MODE REPLICAS IMAGE +4cdgfyky7ozw redis replicated 3/5 redis:3.0.7 +</pre></div> <p>Once all the tasks are created and <code class="language-plaintext highlighter-rouge">RUNNING</code>, the actual number of tasks is equal to the desired number:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker service ls + +ID NAME MODE REPLICAS IMAGE +4cdgfyky7ozw redis replicated 5/5 redis:3.0.7 +</pre></div> <h3 id="create-a-service-with-secrets">Create a service with secrets</h3> <p>Use the <code class="language-plaintext highlighter-rouge">--secret</code> flag to give a container access to a <a href="../secret_create/index">secret</a>.</p> <p>Create a service specifying a secret:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker service create --name redis --secret secret.json redis:3.0.6 + +4cdgfyky7ozwh3htjfw0d12qv +</pre></div> <p>Create a service specifying the secret, target, user/group ID, and mode:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker service create --name redis \ + --secret source=ssh-key,target=ssh \ + --secret source=app-key,target=app,uid=1000,gid=1001,mode=0400 \ + redis:3.0.6 + +4cdgfyky7ozwh3htjfw0d12qv +</pre></div> <p>To grant a service access to multiple secrets, use multiple <code class="language-plaintext highlighter-rouge">--secret</code> flags.</p> <p>Secrets are located in <code class="language-plaintext highlighter-rouge">/run/secrets</code> 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: <code class="language-plaintext highlighter-rouge">/run/secrets/ssh</code> and <code class="language-plaintext highlighter-rouge">/run/secrets/app</code> for each of the secret targets specified.</p> <h3 id="create-a-service-with-configs">Create a service with configs</h3> <p>Use the <code class="language-plaintext highlighter-rouge">--config</code> flag to give a container access to a <a href="../config_create/index">config</a>.</p> <p>Create a service with a config. The config will be mounted into <code class="language-plaintext highlighter-rouge">redis-config</code>, be owned by the user who runs the command inside the container (often <code class="language-plaintext highlighter-rouge">root</code>), and have file mode <code class="language-plaintext highlighter-rouge">0444</code> or world-readable. You can specify the <code class="language-plaintext highlighter-rouge">uid</code> and <code class="language-plaintext highlighter-rouge">gid</code> as numerical IDs or names. When using names, the provided group/user names must pre-exist in the container. The <code class="language-plaintext highlighter-rouge">mode</code> is specified as a 4-number sequence such as <code class="language-plaintext highlighter-rouge">0755</code>.</p> <div class="highlight"><pre class="highlight" data-language="">$ docker service create --name=redis --config redis-conf redis:3.0.6 +</pre></div> <p>Create a service with a config and specify the target location and file mode:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker service create --name redis \ + --config source=redis-conf,target=/etc/redis/redis.conf,mode=0400 redis:3.0.6 +</pre></div> <p>To grant a service access to multiple configs, use multiple <code class="language-plaintext highlighter-rouge">--config</code> flags.</p> <p>Configs are located in <code class="language-plaintext highlighter-rouge">/</code> 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.</p> <h3 id="create-a-service-with-a-rolling-update-policy">Create a service with a rolling update policy</h3> <div class="highlight"><pre class="highlight" data-language="">$ docker service create \ + --replicas 10 \ + --name redis \ + --update-delay 10s \ + --update-parallelism 2 \ + redis:3.0.6 +</pre></div> <p>When you run a <a href="../service_update/index">service update</a>, the scheduler updates a maximum of 2 tasks at a time, with <code class="language-plaintext highlighter-rouge">10s</code> between updates. For more information, refer to the <a href="../../../swarm/swarm-tutorial/rolling-update/index">rolling updates tutorial</a>.</p> <h3 id="set-environment-variables--e---env">Set environment variables (-e, --env)</h3> <p>This sets an environment variable for all tasks in a service. For example:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker service create \ + --name redis_2 \ + --replicas 5 \ + --env MYVAR=foo \ + redis:3.0.6 +</pre></div> <p>To specify multiple environment variables, specify multiple <code class="language-plaintext highlighter-rouge">--env</code> flags, each with a separate key-value pair.</p> <div class="highlight"><pre class="highlight" data-language="">$ docker service create \ + --name redis_2 \ + --replicas 5 \ + --env MYVAR=foo \ + --env MYVAR2=bar \ + redis:3.0.6 +</pre></div> <h3 id="create-a-service-with-specific-hostname---hostname">Create a service with specific hostname (--hostname)</h3> <p>This option sets the docker service containers hostname to a specific string. For example:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker service create --name redis --hostname myredis redis:3.0.6 +</pre></div> <h3 id="set-metadata-on-a-service--l---label">Set metadata on a service (-l, --label)</h3> <p>A label is a <code class="language-plaintext highlighter-rouge">key=value</code> pair that applies metadata to a service. To label a service with two labels:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker service create \ + --name redis_2 \ + --label com.example.foo="bar" + --label bar=baz \ + redis:3.0.6 +</pre></div> <p>For more information about labels, refer to <a href="https://docs.docker.com/config/labels-custom-metadata/">apply custom metadata</a>.</p> <h3 id="add-bind-mounts-volumes-or-memory-filesystems">Add bind mounts, volumes or memory filesystems</h3> <p>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 <em>data volumes</em> (often referred to simply as volumes), <em>bind mounts</em>, <em>tmpfs</em>, and <em>named pipes</em>.</p> <p>A <strong>bind mount</strong> 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 <code class="language-plaintext highlighter-rouge">/etc/resolv.conf</code> or a container might write logs to its host’s <code class="language-plaintext highlighter-rouge">/var/log/myContainerLogs</code> 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.</p> <p>A <strong>named volume</strong> 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 <em>volume driver</em> to create, manage, and mount volumes. You can back up or restore volumes using Docker commands.</p> <p>A <strong>tmpfs</strong> mounts a tmpfs inside a container for volatile data.</p> <p>A <strong>npipe</strong> mounts a named pipe from the host into the container.</p> <p>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.</p> <p>For more information about named volumes, see <a href="https://docs.docker.com/storage/volumes/">Data Volumes</a>.</p> <p>The following table describes options which apply to both bind mounts and named volumes in a service:</p> <table> <tr> <th>Option</th> <th>Required</th> <th>Description</th> </tr> <tr> <td><b>type</b></td> <td></td> <td> <p>The type of mount, can be either <tt>volume</tt>, <tt>bind</tt>, <tt>tmpfs</tt>, or <tt>npipe</tt>. Defaults to <tt>volume</tt> if no type is specified.</p> <ul> <li> +<tt>volume</tt>: mounts a <a href="../volume_create/index">managed volume</a> 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> <li> +<tt>npipe</tt>: mounts named pipe from the host into the container (Windows containers only).</li> </ul> </td> </tr> <tr> <td> +<b>src</b> or <b>source</b> +</td> <td>for <tt>type=bind</tt> and <tt>type=npipe</tt> +</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. Note that setting <tt>readonly</tt> for a bind-mount does not make its submounts <tt>readonly</tt> on the current Linux implementation. See also <tt>bind-nonrecursive</tt>.</p> <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> </td> </tr> </table> <h4 id="options-for-bind-mounts">Options for Bind Mounts</h4> <p>The following options can only be used for bind mounts (<code class="language-plaintext highlighter-rouge">type=bind</code>):</p> <table> <tr> <th>Option</th> <th>Description</th> </tr> <tr> <td><b>bind-propagation</b></td> <td> <p>See the <a href="#bind-propagation">bind propagation section</a>.</p> </td> </tr> <tr> <td><b>consistency</b></td> <td> <p>The consistency requirements for the mount; one of </p> <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 visible on the host.</li> </ul> </td> </tr> <tr> <td><b>bind-nonrecursive</b></td> <td> By default, submounts are recursively bind-mounted as well. However, this behavior can be confusing when a bind mount is configured with <tt>readonly</tt> option, because submounts are not mounted as read-only. Set <tt>bind-nonrecursive</tt> to disable recursive bind-mount.<br> <br> A value is optional:<br> <br> <ul> <li> +<tt>true</tt> or <tt>1</tt>: Disables recursive bind-mount.</li> <li> +<tt>false</tt> or <tt>0</tt>: Default if you do not provide a value. Enables recursive bind-mount.</li> </ul> </td> </tr> </table> <h5 id="bind-propagation">Bind propagation</h5> <p>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 <code class="language-plaintext highlighter-rouge">/mnt</code>, which is also mounted on <code class="language-plaintext highlighter-rouge">/tmp</code>. The propagation settings control whether a mount on <code class="language-plaintext highlighter-rouge">/tmp/a</code> would also be available on <code class="language-plaintext highlighter-rouge">/mnt/a</code>. Each propagation setting has a recursive counterpoint. In the case of recursion, consider that <code class="language-plaintext highlighter-rouge">/tmp/a</code> is also mounted as <code class="language-plaintext highlighter-rouge">/foo</code>. The propagation settings control whether <code class="language-plaintext highlighter-rouge">/mnt/a</code> and/or <code class="language-plaintext highlighter-rouge">/tmp/a</code> would exist.</p> <p>The <code class="language-plaintext highlighter-rouge">bind-propagation</code> option defaults to <code class="language-plaintext highlighter-rouge">rprivate</code> for both bind mounts and volume mounts, and is only configurable for bind mounts. In other words, named volumes do not support bind propagation.</p> <ul> <li> +<strong><code class="language-plaintext highlighter-rouge">shared</code></strong>: Sub-mounts of the original mount are exposed to replica mounts, and sub-mounts of replica mounts are also propagated to the original mount.</li> <li> +<strong><code class="language-plaintext highlighter-rouge">slave</code></strong>: 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.</li> <li> +<strong><code class="language-plaintext highlighter-rouge">private</code></strong>: 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.</li> <li> +<strong><code class="language-plaintext highlighter-rouge">rshared</code></strong>: The same as shared, but the propagation also extends to and from mount points nested within any of the original or replica mount points.</li> <li> +<strong><code class="language-plaintext highlighter-rouge">rslave</code></strong>: The same as <code class="language-plaintext highlighter-rouge">slave</code>, but the propagation also extends to and from mount points nested within any of the original or replica mount points.</li> <li> +<strong><code class="language-plaintext highlighter-rouge">rprivate</code></strong>: The default. The same as <code class="language-plaintext highlighter-rouge">private</code>, meaning that no mount points anywhere within the original or replica mount points propagate in either direction.</li> </ul> <p>For more information about bind propagation, see the <a href="https://www.kernel.org/doc/Documentation/filesystems/sharedsubtree.txt">Linux kernel documentation for shared subtree</a>.</p> <h4 id="options-for-named-volumes">Options for named volumes</h4> <p>The following options can only be used for named volumes (<code class="language-plaintext highlighter-rouge">type=volume</code>):</p> <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, <tt>volume-label=mylabel=hello-world,my-other-label=hello-mars</tt>. For more information about labels, refer to <a href="https://docs.docker.com/config/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 <tt>volume-nocopy</tt> to disable copying files from the container's filesystem to the volume and mount the empty volume.<br> <br> A value is optional:<br> <br> <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, <tt>volume-opt=some-option=some-value,volume-opt=some-other-option=some-other-value</tt>. For available options for a given driver, refer to that driver's documentation. </td> </tr> </table> <h4 id="options-for-tmpfs">Options for tmpfs</h4> <p>The following options can only be used for tmpfs mounts (<code class="language-plaintext highlighter-rouge">type=tmpfs</code>);</p> <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> <h4 id="differences-between---mount-and---volume">Differences between “--mount” and “--volume”</h4> <p>The <code class="language-plaintext highlighter-rouge">--mount</code> flag supports most options that are supported by the <code class="language-plaintext highlighter-rouge">-v</code> or <code class="language-plaintext highlighter-rouge">--volume</code> flag for <code class="language-plaintext highlighter-rouge">docker run</code>, with some important exceptions:</p> <ul> <li> <p>The <code class="language-plaintext highlighter-rouge">--mount</code> flag allows you to specify a volume driver and volume driver options <em>per volume</em>, without creating the volumes in advance. In contrast, <code class="language-plaintext highlighter-rouge">docker run</code> allows you to specify a single volume driver which is shared by all volumes, using the <code class="language-plaintext highlighter-rouge">--volume-driver</code> flag.</p> </li> <li> <p>The <code class="language-plaintext highlighter-rouge">--mount</code> flag allows you to specify custom metadata (“labels”) for a volume, before the volume is created.</p> </li> <li> <p>When you use <code class="language-plaintext highlighter-rouge">--mount</code> with <code class="language-plaintext highlighter-rouge">type=bind</code>, the host-path must refer to an <em>existing</em> 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.</p> </li> <li> <p>The <code class="language-plaintext highlighter-rouge">--mount</code> flag does not allow you to relabel a volume with <code class="language-plaintext highlighter-rouge">Z</code> or <code class="language-plaintext highlighter-rouge">z</code> flags, which are used for <code class="language-plaintext highlighter-rouge">selinux</code> labeling.</p> </li> </ul> <h4 id="create-a-service-using-a-named-volume">Create a service using a named volume</h4> <p>The following example creates a service that uses a named volume:</p> <div class="highlight"><pre class="highlight" data-language="">$ 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 +</pre></div> <p>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.</p> <p>When the task is started, the volume is mounted on <code class="language-plaintext highlighter-rouge">/path/in/container/</code> inside the container.</p> <p>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 <em>new</em> 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.</p> <h4 id="create-a-service-that-uses-an-anonymous-volume">Create a service that uses an anonymous volume</h4> <p>The following command creates a service with three replicas with an anonymous volume on <code class="language-plaintext highlighter-rouge">/path/in/container</code>:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker service create \ + --name my-service \ + --replicas 3 \ + --mount type=volume,destination=/path/in/container \ + nginx:alpine +</pre></div> <p>In this example, no name (<code class="language-plaintext highlighter-rouge">source</code>) 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.</p> <h4 id="create-a-service-that-uses-a-bind-mounted-host-directory">Create a service that uses a bind-mounted host directory</h4> <p>The following example bind-mounts a host directory at <code class="language-plaintext highlighter-rouge">/path/in/container</code> in the containers backing the service:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker service create \ + --name my-service \ + --mount type=bind,source=/path/on/host,destination=/path/in/container \ + nginx:alpine +</pre></div> <h3 id="set-service-mode---mode">Set service mode (--mode)</h3> <p>The service mode determines whether this is a <em>replicated</em> service or a <em>global</em> service. A replicated service runs as many tasks as specified, while a global service runs on each active node in the swarm.</p> <p>The following command creates a global service:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker service create \ + --name redis_2 \ + --mode global \ + redis:3.0.6 +</pre></div> <h3 id="specify-service-constraints---constraint">Specify service constraints (--constraint)</h3> <p>You can limit the set of nodes where a task can be scheduled by defining constraint expressions. Constraint expressions can either use a <em>match</em> (<code class="language-plaintext highlighter-rouge">==</code>) or <em>exclude</em> (<code class="language-plaintext highlighter-rouge">!=</code>) rule. Multiple constraints find nodes that satisfy every expression (AND match). Constraints can match node or Docker Engine labels as follows:</p> <table> <thead> <tr> <th>node attribute</th> <th>matches</th> <th>example</th> </tr> </thead> <tbody> <tr> <td><code class="language-plaintext highlighter-rouge">node.id</code></td> <td>Node ID</td> <td><code class="language-plaintext highlighter-rouge">node.id==2ivku8v2gvtg4</code></td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">node.hostname</code></td> <td>Node hostname</td> <td><code class="language-plaintext highlighter-rouge">node.hostname!=node-2</code></td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">node.role</code></td> <td>Node role (<code class="language-plaintext highlighter-rouge">manager</code>/<code class="language-plaintext highlighter-rouge">worker</code>)</td> <td><code class="language-plaintext highlighter-rouge">node.role==manager</code></td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">node.platform.os</code></td> <td>Node operating system</td> <td><code class="language-plaintext highlighter-rouge">node.platform.os==windows</code></td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">node.platform.arch</code></td> <td>Node architecture</td> <td><code class="language-plaintext highlighter-rouge">node.platform.arch==x86_64</code></td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">node.labels</code></td> <td>User-defined node labels</td> <td><code class="language-plaintext highlighter-rouge">node.labels.security==high</code></td> </tr> <tr> <td><code class="language-plaintext highlighter-rouge">engine.labels</code></td> <td>Docker Engine’s labels</td> <td><code class="language-plaintext highlighter-rouge">engine.labels.operatingsystem==ubuntu-14.04</code></td> </tr> </tbody> </table> <p><code class="language-plaintext highlighter-rouge">engine.labels</code> apply to Docker Engine labels like operating system, drivers, etc. Swarm administrators add <code class="language-plaintext highlighter-rouge">node.labels</code> for operational purposes by using the <a href="../node_update/index"><code class="language-plaintext highlighter-rouge">docker node update</code></a> command.</p> <p>For example, the following limits tasks for the redis service to nodes where the node type label equals queue:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker service create \ + --name redis_2 \ + --constraint node.platform.os==linux \ + --constraint node.labels.type==queue \ + redis:3.0.6 +</pre></div> <p>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.</p> <p>In the example below, no node satisfying the constraint was found, causing the service to not reconcile with the desired state:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker service create \ + --name web \ + --constraint node.labels.region==east \ + nginx:alpine + +lx1wrhhpmbbu0wuk0ybws30bc +overall progress: 0 out of 1 tasks +1/1: no suitable node (scheduling constraints not satisfied on 5 nodes) + +$ docker service ls +ID NAME MODE REPLICAS IMAGE PORTS +b6lww17hrr4e web replicated 0/1 nginx:alpine +</pre></div> <p>After adding the <code class="language-plaintext highlighter-rouge">region=east</code> label to a node in the cluster, the service reconciles, and the desired number of replicas are deployed:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker node update --label-add region=east yswe2dm4c5fdgtsrli1e8ya5l +yswe2dm4c5fdgtsrli1e8ya5l + +$ docker service ls +ID NAME MODE REPLICAS IMAGE PORTS +b6lww17hrr4e web replicated 1/1 nginx:alpine +</pre></div> <h3 id="specify-service-placement-preferences---placement-pref">Specify service placement preferences (--placement-pref)</h3> <p>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:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker service create \ + --replicas 9 \ + --name redis_2 \ + --placement-pref spread=node.labels.datacenter \ + redis:3.0.6 +</pre></div> <p>This uses <code class="language-plaintext highlighter-rouge">--placement-pref</code> with a <code class="language-plaintext highlighter-rouge">spread</code> strategy (currently the only supported strategy) to spread tasks evenly over the values of the <code class="language-plaintext highlighter-rouge">datacenter</code> node label. In this example, we assume that every node has a <code class="language-plaintext highlighter-rouge">datacenter</code> 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:</p> <ul> <li>Three nodes with <code class="language-plaintext highlighter-rouge">node.labels.datacenter=east</code> +</li> <li>Two nodes with <code class="language-plaintext highlighter-rouge">node.labels.datacenter=south</code> +</li> <li>One node with <code class="language-plaintext highlighter-rouge">node.labels.datacenter=west</code> +</li> </ul> <p>Since we are spreading over the values of the <code class="language-plaintext highlighter-rouge">datacenter</code> label and the service has 9 replicas, 3 replicas will end up in each datacenter. There are three nodes associated with the value <code class="language-plaintext highlighter-rouge">east</code>, so each one will get one of the three replicas reserved for this value. There are two nodes with the value <code class="language-plaintext highlighter-rouge">south</code>, and the three replicas for this value will be divided between them, with one receiving two replicas and another receiving just one. Finally, <code class="language-plaintext highlighter-rouge">west</code> has a single node that will get all three replicas reserved for <code class="language-plaintext highlighter-rouge">west</code>.</p> <p>If the nodes in one category (for example, those with <code class="language-plaintext highlighter-rouge">node.labels.datacenter=south</code>) 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.</p> <p>Both engine labels and node labels are supported by placement preferences. The example above uses a node label, because the label is referenced with <code class="language-plaintext highlighter-rouge">node.labels.datacenter</code>. To spread over the values of an engine label, use <code class="language-plaintext highlighter-rouge">--placement-pref spread=engine.labels.<labelname></code>.</p> <p>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 <code class="language-plaintext highlighter-rouge">--placement-pref</code> flag multiple times. The order is significant, and the placement preferences will be applied in the order given when making scheduling decisions.</p> <p>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):</p> <div class="highlight"><pre class="highlight" data-language="">$ docker service create \ + --replicas 9 \ + --name redis_2 \ + --placement-pref 'spread=node.labels.datacenter' \ + --placement-pref 'spread=node.labels.rack' \ + redis:3.0.6 +</pre></div> <p>When updating a service with <code class="language-plaintext highlighter-rouge">docker service update</code>, <code class="language-plaintext highlighter-rouge">--placement-pref-add</code> appends a new placement preference after all existing placement preferences. <code class="language-plaintext highlighter-rouge">--placement-pref-rm</code> removes an existing placement preference that matches the argument.</p> <h3 id="specify-memory-requirements-and-constraints-for-a-service---reserve-memory-and---limit-memory">Specify memory requirements and constraints for a service (--reserve-memory and --limit-memory)</h3> <p>If your service needs a minimum amount of memory in order to run correctly, you can use <code class="language-plaintext highlighter-rouge">--reserve-memory</code> 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.</p> <p>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.</p> <div class="highlight"><pre class="highlight" data-language="">$ docker service create --reserve-memory=4GB --name=too-big nginx:alpine +</pre></div> <p>The managers won’t schedule a set of containers on a single node whose combined reservations exceed the memory available on that node.</p> <p>After a task is scheduled and running, <code class="language-plaintext highlighter-rouge">--reserve-memory</code> does not enforce a memory limit. Use <code class="language-plaintext highlighter-rouge">--limit-memory</code> 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 <code class="language-plaintext highlighter-rouge">--limit-memory</code> is an upper limit.</p> <div class="highlight"><pre class="highlight" data-language="">$ docker service create --limit-memory=4GB --name=too-big nginx:alpine +</pre></div> <p>Using <code class="language-plaintext highlighter-rouge">--reserve-memory</code> and <code class="language-plaintext highlighter-rouge">--limit-memory</code> 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.</p> <p>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 <code class="language-plaintext highlighter-rouge">--reserve-memory</code> is greater than or equal to <code class="language-plaintext highlighter-rouge">--limit-memory</code>, Docker won’t schedule a service on a host that doesn’t have enough memory. <code class="language-plaintext highlighter-rouge">--limit-memory</code> will 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.</p> <p>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.</p> <p>In short, you can take a more conservative or more flexible approach:</p> <ul> <li> <p><strong>Conservative</strong>: 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.</p> </li> <li> <p><strong>Flexible</strong>: 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.</p> </li> </ul> <p>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.</p> <p>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 <code class="language-plaintext highlighter-rouge">cgroups</code> or other relevant operating system tools.</p> <h3 id="specify-maximum-replicas-per-node---replicas-max-per-node">Specify maximum replicas per node (--replicas-max-per-node)</h3> <p>Use the <code class="language-plaintext highlighter-rouge">--replicas-max-per-node</code> 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.</p> <p>One example where this can be useful is to balance tasks over a set of data centers together with <code class="language-plaintext highlighter-rouge">--placement-pref</code> and let <code class="language-plaintext highlighter-rouge">--replicas-max-per-node</code> setting make sure that replicas are not migrated to another datacenter during maintenance or datacenter failure.</p> <p>The example below illustrates this:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker service create \ + --name nginx \ + --replicas 2 \ + --replicas-max-per-node 1 \ + --placement-pref 'spread=node.labels.datacenter' \ + nginx +</pre></div> <h3 id="attach-a-service-to-an-existing-network---network">Attach a service to an existing network (--network)</h3> <p>You can use overlay networks to connect one or more services within the swarm.</p> <p>First, create an overlay network on a manager node the docker network create command:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker network create --driver overlay my-network + +etjpu59cykrptrgw0z0hk5snf +</pre></div> <p>After you create an overlay network in swarm mode, all manager nodes have access to the network.</p> <p>When you create a service and pass the <code class="language-plaintext highlighter-rouge">--network</code> flag to attach the service to the overlay network:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker service create \ + --replicas 3 \ + --network my-network \ + --name my-web \ + nginx + +716thylsndqma81j6kkkb5aus +</pre></div> <p>The swarm extends my-network to each node running the service.</p> <p>Containers on the same network can access each other using <a href="https://docs.docker.com/network/overlay/#container-discovery">service discovery</a>.</p> <p>Long form syntax of <code class="language-plaintext highlighter-rouge">--network</code> allows to specify list of aliases and driver options: <code class="language-plaintext highlighter-rouge">--network name=my-network,alias=web1,driver-opt=field1=value1</code></p> <h3 id="publish-service-ports-externally-to-the-swarm--p---publish">Publish service ports externally to the swarm (-p, --publish)</h3> <p>You can publish service ports to make them available externally to the swarm using the <code class="language-plaintext highlighter-rouge">--publish</code> flag. The <code class="language-plaintext highlighter-rouge">--publish</code> 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 (<code class="language-plaintext highlighter-rouge">:</code>).</p> <div class="highlight"><pre class="highlight" data-language="">$ docker service create --name my_web --replicas 3 --publish 8080:80 nginx +</pre></div> <p>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:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker service create --name my_web --replicas 3 --publish published=8080,target=80 nginx +</pre></div> <p>The options you can specify are:</p> <table> <thead> <tr> <th>Option</th> <th>Short syntax</th> <th>Long syntax</th> <th>Description</th> </tr> </thead> <tr> <td>published and target port</td> <td><tt>--publish 8080:80</tt></td> <td><tt>--publish published=8080,target=80</tt></td> <td><p> The target port within the container and the port to map it to on the nodes, using the routing mesh (<tt>ingress</tt>) or host-level networking. More options are available, later in this table. The key-value syntax is preferred, because it is somewhat self-documenting. </p></td> </tr> <tr> <td>mode</td> <td>Not possible to set using short syntax.</td> <td><tt>--publish published=8080,target=80,mode=host</tt></td> <td><p> The mode to use for binding the port, either <tt>ingress</tt> or <tt>host</tt>. Defaults to <tt>ingress</tt> to use the routing mesh. </p></td> </tr> <tr> <td>protocol</td> <td><tt>--publish 8080:80/tcp</tt></td> <td><tt>--publish published=8080,target=80,protocol=tcp</tt></td> <td><p> The protocol to use, <tt>tcp</tt> , <tt>udp</tt>, or <tt>sctp</tt>. Defaults to <tt>tcp</tt>. To bind a port for both protocols, specify the <tt>-p</tt> or <tt>--publish</tt> flag twice. </p></td> </tr> </table> <p>When you publish a service port using <code class="language-plaintext highlighter-rouge">ingress</code> 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 <code class="language-plaintext highlighter-rouge">host</code> 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 to <a href="../../../swarm/ingress/index">Use swarm mode routing mesh</a>.</p> <h3 id="provide-credential-specs-for-managed-service-accounts-windows-only">Provide credential specs for managed service accounts (Windows only)</h3> <p>This option is only used for services using Windows containers. The <code class="language-plaintext highlighter-rouge">--credential-spec</code> must be in the format <code class="language-plaintext highlighter-rouge">file://<filename></code> or <code class="language-plaintext highlighter-rouge">registry://<value-name></code>.</p> <p>When using the <code class="language-plaintext highlighter-rouge">file://<filename></code> format, the referenced file must be present in the <code class="language-plaintext highlighter-rouge">CredentialSpecs</code> subdirectory in the docker data directory, which defaults to <code class="language-plaintext highlighter-rouge">C:\ProgramData\Docker\</code> on Windows. For example, specifying <code class="language-plaintext highlighter-rouge">file://spec.json</code> loads <code class="language-plaintext highlighter-rouge">C:\ProgramData\Docker\CredentialSpecs\spec.json</code>.</p> <p>When using the <code class="language-plaintext highlighter-rouge">registry://<value-name></code> format, the credential spec is read from the Windows registry on the daemon’s host. The specified registry value must be located in:</p> <div class="highlight"><pre class="highlight" data-language="">HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Virtualization\Containers\CredentialSpecs +</pre></div> <h3 id="create-services-using-templates">Create services using templates</h3> <p>You can use templates for some flags of <code class="language-plaintext highlighter-rouge">service create</code>, using the syntax provided by the Go’s <a href="https://golang.org/pkg/text/template/">text/template</a> package.</p> <p>The supported flags are the following :</p> <ul> <li><code class="language-plaintext highlighter-rouge">--hostname</code></li> <li><code class="language-plaintext highlighter-rouge">--mount</code></li> <li><code class="language-plaintext highlighter-rouge">--env</code></li> </ul> <p>Valid placeholders for the Go template are listed below:</p> <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>.Node.Hostname</tt></td> <td>Node Hostname</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> <h4 id="template-example">Template example</h4> <p>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.</p> <div class="highlight"><pre class="highlight" data-language="">$ docker service create \ + --name hosttempl \ + --hostname="{{.Node.Hostname}}-{{.Node.ID}}-{{.Service.Name}}"\ + busybox top + +va8ew30grofhjoychbr6iot8c + +$ docker service ps va8ew30grofhjoychbr6iot8c + +ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS +wo41w8hg8qan hosttempl.1 busybox:latest@sha256:29f5d56d12684887bdfa50dcd29fc31eea4aaf4ad3bec43daf19026a7ce69912 2e7a8a9c4da2 Running Running about a minute ago + +$ docker inspect --format="{{.Config.Hostname}}" 2e7a8a9c4da2-wo41w8hg8qanxwjwsg4kxpprj-hosttempl + +x3ti0erg11rjpg64m75kej2mz-hosttempl +</pre></div> <h3 id="specify-isolation-mode-windows">Specify isolation mode (Windows)</h3> <p>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 <code class="language-plaintext highlighter-rouge">--isolation</code> flag:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker service create --name myservice --isolation=process microsoft/nanoserver +</pre></div> <p>Supported isolation modes on Windows are:</p> <ul> <li> +<code class="language-plaintext highlighter-rouge">default</code>: use default settings specified on the node running the task</li> <li> +<code class="language-plaintext highlighter-rouge">process</code>: use process isolation (Windows server only)</li> <li> +<code class="language-plaintext highlighter-rouge">hyperv</code>: use Hyper-V isolation</li> </ul> <h3 id="create-services-requesting-generic-resources">Create services requesting Generic Resources</h3> <p>You can narrow the kind of nodes your task can land on through the using the <code class="language-plaintext highlighter-rouge">--generic-resource</code> flag (if the nodes advertise these resources):</p> <div class="highlight"><pre class="highlight" data-language="">$ docker service create \ + --name cuda \ + --generic-resource "NVIDIA-GPU=2" \ + --generic-resource "SSD=1" \ + nvidia/cuda +</pre></div> <h3 id="running-as-a-job">Running as a job</h3> <p>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.</p> <p>Jobs are started by using one of two modes, <code class="language-plaintext highlighter-rouge">replicated-job</code> or <code class="language-plaintext highlighter-rouge">global-job</code></p> <div class="highlight"><pre class="highlight" data-language="">$ docker service create --name myjob \ + --mode replicated-job \ + bash "true" +</pre></div> <p>This command will run one Task, which will, using the <code class="language-plaintext highlighter-rouge">bash</code> image, execute the command <code class="language-plaintext highlighter-rouge">true</code>, which will return 0 and then exit.</p> <p>Though Jobs are ultimately a different kind of service, they a couple of caveats compared to other services:</p> <ul> <li>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.</li> <li>Jobs are never restarted on reaching the <code class="language-plaintext highlighter-rouge">Complete</code> state. This means that for jobs, setting <code class="language-plaintext highlighter-rouge">--restart-condition</code> to <code class="language-plaintext highlighter-rouge">any</code> is the same as setting it to <code class="language-plaintext highlighter-rouge">on-failure</code>.</li> </ul> <p>Jobs are available in both replicated and global modes.</p> <h4 id="replicated-jobs">Replicated Jobs</h4> <p>A replicated job is like a replicated service. Setting the <code class="language-plaintext highlighter-rouge">--replicas</code> flag will specify total number of iterations of a job to execute.</p> <p>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 <code class="language-plaintext highlighter-rouge">--max-concurrent</code> flag can be used:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker service create \ + --name mythrottledjob \ + --mode replicated-job \ + --replicas 10 \ + --max-concurrent 2 \ + bash "true" +</pre></div> <p>The above command will execute 10 Tasks in total, but only 2 of them will be run at any given time.</p> <h4 id="global-jobs">Global Jobs</h4> <p>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 <code class="language-plaintext highlighter-rouge">global-job</code>.</p> <p>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.</p> <h2 id="parent-command">Parent command</h2> <table> <thead> <tr> <th style="text-align: left">Command</th> <th style="text-align: left">Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: left"><a href="../service/index">docker service</a></td> <td style="text-align: left">Manage services</td> </tr> </tbody> </table> <h2 id="related-commands">Related commands</h2> <table> <thead> <tr> <td>Command</td> <td>Description</td> </tr> </thead> <tbody> <tr> <td><a href="index">docker service create</a></td> <td>Create a new service</td> </tr> <tr> <td><a href="../service_inspect/index">docker service inspect</a></td> <td>Display detailed information on one or more services</td> </tr> <tr> <td><a href="../service_logs/index">docker service logs</a></td> <td>Fetch the logs of a service or task</td> </tr> <tr> <td><a href="../service_ls/index">docker service ls</a></td> <td>List services</td> </tr> <tr> <td><a href="../service_ps/index">docker service ps</a></td> <td>List the tasks of one or more services</td> </tr> <tr> <td><a href="../service_rm/index">docker service rm</a></td> <td>Remove one or more services</td> </tr> <tr> <td><a href="../service_rollback/index">docker service rollback</a></td> <td>Revert changes to a service’s configuration</td> </tr> <tr> <td><a href="../service_scale/index">docker service scale</a></td> <td>Scale one or multiple replicated services</td> </tr> <tr> <td><a href="../service_update/index">docker service update</a></td> <td>Update a service</td> </tr> </tbody> </table> <div class="_attribution"> + <p class="_attribution-p"> + © 2019 Docker, Inc.<br>Licensed under the Apache License, Version 2.0.<br>Docker and the Docker logo are trademarks or registered trademarks of Docker, Inc. in the United States and/or other countries.<br>Docker, Inc. and other parties may also have trademark rights in other terms used herein.<br> + <a href="https://docs.docker.com/engine/reference/commandline/service_create/" class="_attribution-link">https://docs.docker.com/engine/reference/commandline/service_create/</a> + </p> +</div> |