diff options
Diffstat (limited to 'devdocs/docker/compose%2Fcompose-file%2Fdeploy%2Findex.html')
| -rw-r--r-- | devdocs/docker/compose%2Fcompose-file%2Fdeploy%2Findex.html | 126 |
1 files changed, 126 insertions, 0 deletions
diff --git a/devdocs/docker/compose%2Fcompose-file%2Fdeploy%2Findex.html b/devdocs/docker/compose%2Fcompose-file%2Fdeploy%2Findex.html new file mode 100644 index 00000000..ac3b0330 --- /dev/null +++ b/devdocs/docker/compose%2Fcompose-file%2Fdeploy%2Findex.html @@ -0,0 +1,126 @@ +<h1>Compose file deploy reference</h1> + +<p>Compose specification is a platform-neutral way to define multi-container applications. A Compose implementation supporting deployment of application model MAY require some additional metadata as the Compose application model is way too abstract to reflect actual infrastructure needs per service, or lifecycle constraints.</p> <p>Compose Specification Deployment allows users to declare additional metadata on services so Compose implementations get relevant data to allocate adequate resources on platform and configure them to match user’s needs.</p> <h2 id="definitions">Definitions</h2> <p>Compose Specification is extended to support an OPTIONAL <code class="language-plaintext highlighter-rouge">deploy</code> subsection on services. This section define runtime requirements for a service.</p> <h3 id="endpoint_mode">endpoint_mode</h3> <p><code class="language-plaintext highlighter-rouge">endpoint_mode</code> specifies a service discovery method for external clients connecting to a service. Default and available values are platform specific, anyway the Compose specification define two canonical values:</p> <ul> <li> <p><code class="language-plaintext highlighter-rouge">endpoint_mode: vip</code>: Assigns the service a virtual IP (VIP) that acts as the front end for clients to reach the service on a network. Platform routes requests between the client and nodes running the service, without client knowledge of how many nodes are participating in the service or their IP addresses or ports.</p> </li> <li> <p><code class="language-plaintext highlighter-rouge">endpoint_mode: dnsrr</code>: Platform sets up DNS entries for the service such that a DNS query for the service name returns a list of IP addresses (DNS round-robin), and the client connects directly to one of these.</p> </li> </ul> <div class="highlight"><pre class="highlight" data-language="">services: + frontend: + image: awesome/webapp + ports: + - "8080:80" + deploy: + mode: replicated + replicas: 2 + endpoint_mode: vip +</pre></div> <h3 id="labels">labels</h3> <p><code class="language-plaintext highlighter-rouge">labels</code> specifies metadata for the service. These labels MUST <em>only</em> be set on the service and <em>not</em> on any containers for the service. This assumes the platform has some native concept of “service” that can match Compose application model.</p> <div class="highlight"><pre class="highlight" data-language="">services: + frontend: + image: awesome/webapp + deploy: + labels: + com.example.description: "This label will appear on the web service" +</pre></div> <h3 id="mode">mode</h3> <p><code class="language-plaintext highlighter-rouge">mode</code> define the replication model used to run the service on platform. Either <code class="language-plaintext highlighter-rouge">global</code> (exactly one container per physical node) or <code class="language-plaintext highlighter-rouge">replicated</code> (a specified number of containers). The default is <code class="language-plaintext highlighter-rouge">replicated</code>.</p> <div class="highlight"><pre class="highlight" data-language="">services: + frontend: + image: awesome/webapp + deploy: + mode: global +</pre></div> <h3 id="placement">placement</h3> <p><code class="language-plaintext highlighter-rouge">placement</code> specifies constraints and preferences for platform to select a physical node to run service containers.</p> <h4 id="constraints">constraints</h4> <p><code class="language-plaintext highlighter-rouge">constraints</code> defines a REQUIRED property the platform’s node MUST fulfill to run service container. Can be set either by a list or a map with string values.</p> <div class="highlight"><pre class="highlight" data-language="">deploy: + placement: + constraints: + - disktype=ssd +</pre></div> <div class="highlight"><pre class="highlight" data-language="">deploy: + placement: + constraints: + disktype: ssd +</pre></div> <h4 id="preferences">preferences</h4> <p><code class="language-plaintext highlighter-rouge">preferences</code> defines a property the platform’s node SHOULD fulfill to run service container. Can be set either by a list or a map with string values.</p> <div class="highlight"><pre class="highlight" data-language="">deploy: + placement: + preferences: + - datacenter=us-east +</pre></div> <div class="highlight"><pre class="highlight" data-language="">deploy: + placement: + preferences: + datacenter: us-east +</pre></div> <h3 id="replicas">replicas</h3> <p>If the service is <code class="language-plaintext highlighter-rouge">replicated</code> (which is the default), <code class="language-plaintext highlighter-rouge">replicas</code> specifies the number of containers that SHOULD be running at any given time.</p> <div class="highlight"><pre class="highlight" data-language="">services: + frontend: + image: awesome/webapp + deploy: + mode: replicated + replicas: 6 +</pre></div> <h3 id="resources">resources</h3> <p><code class="language-plaintext highlighter-rouge">resources</code> configures physical resource constraints for container to run on platform. Those constraints can be configured as a:</p> <ul> <li> +<code class="language-plaintext highlighter-rouge">limits</code>: The platform MUST prevent container to allocate more</li> <li> +<code class="language-plaintext highlighter-rouge">reservations</code>: The platform MUST guarantee container can allocate at least the configured amount</li> </ul> <div class="highlight"><pre class="highlight" data-language="">services: + frontend: + image: awesome/webapp + deploy: + resources: + limits: + cpus: '0.50' + memory: 50M + pids: 1 + reservations: + cpus: '0.25' + memory: 20M +</pre></div> <h4 id="cpus">cpus</h4> <p><code class="language-plaintext highlighter-rouge">cpus</code> configures a limit or reservation for how much of the available CPU resources (as number of cores) a container can use.</p> <h4 id="memory">memory</h4> <p><code class="language-plaintext highlighter-rouge">memory</code> configures a limit or reservation on the amount of memory a container can allocate, set as a string expressing a <a href="../index#specifying-byte-values">byte value</a>.</p> <h4 id="pids">pids</h4> <p><code class="language-plaintext highlighter-rouge">pids</code> tunes a container’s PIDs limit, set as an integer.</p> <h4 id="devices">devices</h4> <p><code class="language-plaintext highlighter-rouge">devices</code> configures reservations of the devices a container can use. It contains a list of reservations, each set as an object with the following parameters: <code class="language-plaintext highlighter-rouge">capabilities</code>, <code class="language-plaintext highlighter-rouge">driver</code>, <code class="language-plaintext highlighter-rouge">count</code>, <code class="language-plaintext highlighter-rouge">device_ids</code> and <code class="language-plaintext highlighter-rouge">options</code>.</p> <p>Devices are reserved using a list of capabilities, making <code class="language-plaintext highlighter-rouge">capabilities</code> the only required field. A device MUST satisfy all the requested capabilities for a successful reservation.</p> <h5 id="capabilities">capabilities</h5> <p><code class="language-plaintext highlighter-rouge">capabilities</code> are set as a list of strings, expressing both generic and driver specific capabilities. The following generic capabilities are recognized today:</p> <ul> <li> +<code class="language-plaintext highlighter-rouge">gpu</code>: Graphics accelerator</li> <li> +<code class="language-plaintext highlighter-rouge">tpu</code>: AI accelerator</li> </ul> <p>To avoid name clashes, driver specific capabilities MUST be prefixed with the driver name. For example, reserving an nVidia CUDA-enabled accelerator might look like this:</p> <div class="highlight"><pre class="highlight" data-language="">deploy: + resources: + reservations: + devices: + - capabilities: ["nvidia-compute"] +</pre></div> <h5 id="driver">driver</h5> <p>A different driver for the reserved device(s) can be requested using <code class="language-plaintext highlighter-rouge">driver</code> field. The value is specified as a string.</p> <div class="highlight"><pre class="highlight" data-language="">deploy: + resources: + reservations: + devices: + - capabilities: ["nvidia-compute"] + driver: nvidia +</pre></div> <h5 id="count">count</h5> <p>If <code class="language-plaintext highlighter-rouge">count</code> is set to <code class="language-plaintext highlighter-rouge">all</code> or not specified, Compose implementations MUST reserve all devices that satisfy the requested capabilities. Otherwise, Compose implementations MUST reserve at least the number of devices specified. The value is specified as an integer.</p> <div class="highlight"><pre class="highlight" data-language="">deploy: + resources: + reservations: + devices: + - capabilities: ["tpu"] + count: 2 +</pre></div> <p><code class="language-plaintext highlighter-rouge">count</code> and <code class="language-plaintext highlighter-rouge">device_ids</code> fields are exclusive. Compose implementations MUST return an error if both are specified.</p> <h5 id="device_ids">device_ids</h5> <p>If <code class="language-plaintext highlighter-rouge">device_ids</code> is set, Compose implementations MUST reserve devices with the specified IDs providing they satisfy the requested capabilities. The value is specified as a list of strings.</p> <div class="highlight"><pre class="highlight" data-language="">deploy: + resources: + reservations: + devices: + - capabilities: ["gpu"] + device_ids: ["GPU-f123d1c9-26bb-df9b-1c23-4a731f61d8c7"] +</pre></div> <p><code class="language-plaintext highlighter-rouge">count</code> and <code class="language-plaintext highlighter-rouge">device_ids</code> fields are exclusive. Compose implementations MUST return an error if both are specified.</p> <h5 id="options">options</h5> <p>Driver specific options can be set with <code class="language-plaintext highlighter-rouge">options</code> as key-value pairs.</p> <div class="highlight"><pre class="highlight" data-language="">deploy: + resources: + reservations: + devices: + - capabilities: ["gpu"] + driver: gpuvendor + options: + virtualization: false +</pre></div> <h3 id="restart_policy">restart_policy</h3> <p><code class="language-plaintext highlighter-rouge">restart_policy</code> configures if and how to restart containers when they exit. If <code class="language-plaintext highlighter-rouge">restart_policy</code> is not set, Compose implementations MUST consider <code class="language-plaintext highlighter-rouge">restart</code> field set by service configuration.</p> <ul> <li> +<code class="language-plaintext highlighter-rouge">condition</code>: One of <code class="language-plaintext highlighter-rouge">none</code>, <code class="language-plaintext highlighter-rouge">on-failure</code> or <code class="language-plaintext highlighter-rouge">any</code> (default: <code class="language-plaintext highlighter-rouge">any</code>).</li> <li> +<code class="language-plaintext highlighter-rouge">delay</code>: How long to wait between restart attempts, specified as a <a href="../index#specifying-durations">duration</a> (default: 0).</li> <li> +<code class="language-plaintext highlighter-rouge">max_attempts</code>: How many times to attempt to restart a container before giving up (default: never give up). If the restart does not succeed within the configured <code class="language-plaintext highlighter-rouge">window</code>, this attempt doesn’t count toward the configured <code class="language-plaintext highlighter-rouge">max_attempts</code> value. For example, if <code class="language-plaintext highlighter-rouge">max_attempts</code> is set to ‘2’, and the restart fails on the first attempt, more than two restarts MUST be attempted.</li> <li> +<code class="language-plaintext highlighter-rouge">window</code>: How long to wait before deciding if a restart has succeeded, specified as a <a href="../index#specifying-durations">duration</a> (default: decide immediately).</li> </ul> <div class="highlight"><pre class="highlight" data-language="">deploy: + restart_policy: + condition: on-failure + delay: 5s + max_attempts: 3 + window: 120s +</pre></div> <h3 id="rollback_config">rollback_config</h3> <p><code class="language-plaintext highlighter-rouge">rollback_config</code> configures how the service should be rollbacked in case of a failing update.</p> <ul> <li> +<code class="language-plaintext highlighter-rouge">parallelism</code>: The number of containers to rollback at a time. If set to 0, all containers rollback simultaneously.</li> <li> +<code class="language-plaintext highlighter-rouge">delay</code>: The time to wait between each container group’s rollback (default 0s).</li> <li> +<code class="language-plaintext highlighter-rouge">failure_action</code>: What to do if a rollback fails. One of <code class="language-plaintext highlighter-rouge">continue</code> or <code class="language-plaintext highlighter-rouge">pause</code> (default <code class="language-plaintext highlighter-rouge">pause</code>)</li> <li> +<code class="language-plaintext highlighter-rouge">monitor</code>: Duration after each task update to monitor for failure <code class="language-plaintext highlighter-rouge">(ns|us|ms|s|m|h)</code> (default 0s).</li> <li> +<code class="language-plaintext highlighter-rouge">max_failure_ratio</code>: Failure rate to tolerate during a rollback (default 0).</li> <li> +<code class="language-plaintext highlighter-rouge">order</code>: Order of operations during rollbacks. One of <code class="language-plaintext highlighter-rouge">stop-first</code> (old task is stopped before starting new one), or <code class="language-plaintext highlighter-rouge">start-first</code> (new task is started first, and the running tasks briefly overlap) (default <code class="language-plaintext highlighter-rouge">stop-first</code>).</li> </ul> <h3 id="update_config">update_config</h3> <p><code class="language-plaintext highlighter-rouge">update_config</code> configures how the service should be updated. Useful for configuring rolling updates.</p> <ul> <li> +<code class="language-plaintext highlighter-rouge">parallelism</code>: The number of containers to update at a time.</li> <li> +<code class="language-plaintext highlighter-rouge">delay</code>: The time to wait between updating a group of containers.</li> <li> +<code class="language-plaintext highlighter-rouge">failure_action</code>: What to do if an update fails. One of <code class="language-plaintext highlighter-rouge">continue</code>, <code class="language-plaintext highlighter-rouge">rollback</code>, or <code class="language-plaintext highlighter-rouge">pause</code> (default: <code class="language-plaintext highlighter-rouge">pause</code>).</li> <li> +<code class="language-plaintext highlighter-rouge">monitor</code>: Duration after each task update to monitor for failure <code class="language-plaintext highlighter-rouge">(ns|us|ms|s|m|h)</code> (default 0s).</li> <li> +<code class="language-plaintext highlighter-rouge">max_failure_ratio</code>: Failure rate to tolerate during an update.</li> <li> +<code class="language-plaintext highlighter-rouge">order</code>: Order of operations during updates. One of <code class="language-plaintext highlighter-rouge">stop-first</code> (old task is stopped before starting new one), or <code class="language-plaintext highlighter-rouge">start-first</code> (new task is started first, and the running tasks briefly overlap) (default <code class="language-plaintext highlighter-rouge">stop-first</code>).</li> </ul> <div class="highlight"><pre class="highlight" data-language="">deploy: + update_config: + parallelism: 2 + delay: 10s + order: stop-first +</pre></div> +<p><a href="https://docs.docker.com/search/?q=fig">fig</a>, <a href="https://docs.docker.com/search/?q=composition">composition</a>, <a href="https://docs.docker.com/search/?q=compose">compose</a>, <a href="https://docs.docker.com/search/?q=docker">docker</a></p> +<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/compose/compose-file/deploy/" class="_attribution-link">https://docs.docker.com/compose/compose-file/deploy/</a> + </p> +</div> |