new repository

1 files changed, 151 insertions, 0 deletions

diff --git a/devdocs/docker/compose%2Fcompose-file%2Fcompose-versioning%2Findex.html b/devdocs/docker/compose%2Fcompose-file%2Fcompose-versioning%2Findex.html
new file mode 100644
index 00000000..2a8d7ac1
--- /dev/null
+++ b/devdocs/docker/compose%2Fcompose-file%2Fcompose-versioning%2Findex.html
@@ -0,0 +1,151 @@
+<h1>Compose file versions and upgrading</h1>
+
+<p>The Compose file is a <a href="https://yaml.org">YAML</a> file defining services, networks, and volumes for a Docker application.</p> <p>The Compose file formats are now described in these references, specific to each version.</p> <table> <thead> <tr> <th style="text-align: left"><strong>Reference file</strong></th> <th style="text-align: left"><strong>What changed in this version</strong></th> </tr> </thead> <tbody> <tr> <td style="text-align: left">
+<a href="../index">Compose Specification</a> (most current, and recommended)</td> <td style="text-align: left"><a href="index#versioning">Versioning</a></td> </tr> <tr> <td style="text-align: left"><a href="../compose-file-v3/index">Version 3</a></td> <td style="text-align: left"><a href="#version-3">Version 3 updates</a></td> </tr> <tr> <td style="text-align: left"><a href="../compose-file-v2/index">Version 2</a></td> <td style="text-align: left"><a href="#version-2">Version 2 updates</a></td> </tr> <tr> <td style="text-align: left">Version 1 (Deprecated)</td> <td style="text-align: left"><a href="#version-1-deprecated">Version 1 updates</a></td> </tr> </tbody> </table> <p>The topics below explain the differences among the versions, Docker Engine compatibility, and <a href="#upgrading">how to upgrade</a>.</p> <h2 id="compatibility-matrix">Compatibility matrix</h2> <p>There are several versions of the Compose file format – 1, 2, 2.x, and 3.x</p> <p>This table shows which Compose file versions support specific Docker releases.</p> <table> <thead> <tr> <th><strong>Compose file format</strong></th> <th><strong>Docker Engine release</strong></th> </tr> </thead> <tbody> <tr> <td>Compose specification</td> <td>19.03.0+</td> </tr> <tr> <td>3.8</td> <td>19.03.0+</td> </tr> <tr> <td>3.7</td> <td>18.06.0+</td> </tr> <tr> <td>3.6</td> <td>18.02.0+</td> </tr> <tr> <td>3.5</td> <td>17.12.0+</td> </tr> <tr> <td>3.4</td> <td>17.09.0+</td> </tr> <tr> <td>3.3</td> <td>17.06.0+</td> </tr> <tr> <td>3.2</td> <td>17.04.0+</td> </tr> <tr> <td>3.1</td> <td>1.13.1+</td> </tr> <tr> <td>3.0</td> <td>1.13.0+</td> </tr> <tr> <td>2.4</td> <td>17.12.0+</td> </tr> <tr> <td>2.3</td> <td>17.06.0+</td> </tr> <tr> <td>2.2</td> <td>1.13.0+</td> </tr> <tr> <td>2.1</td> <td>1.12.0+</td> </tr> <tr> <td>2.0</td> <td>1.10.0+</td> </tr> </tbody> </table> <p>In addition to Compose file format versions shown in the table, the Compose itself is on a release schedule, as shown in <a href="https://github.com/docker/compose/releases/">Compose releases</a>, but file format versions do not necessarily increment with each release. For example, Compose file format 3.0 was first introduced in <a href="https://github.com/docker/compose/releases/tag/1.10.0">Compose release 1.10.0</a>, and versioned gradually in subsequent releases.</p> <p>The latest Compose file format is defined by the <a href="https://github.com/compose-spec/compose-spec/blob/master/spec/" target="_blank" rel="noopener" class="_">Compose Specification</a> and is implemented by Docker Compose <strong>1.27.0+</strong>.</p> <blockquote> <p>Looking for more detail on Docker and Compose compatibility?</p> <p>We recommend keeping up-to-date with newer releases as much as possible. However, if you are using an older version of Docker and want to determine which Compose release is compatible, refer to the <a href="https://github.com/docker/compose/releases/">Compose release notes</a>. Each set of release notes gives details on which versions of Docker Engine are supported, along with compatible Compose file format versions. (See also, the discussion in <a href="https://github.com/docker/docker.github.io/issues/3404">issue #3404</a>.)</p> </blockquote> <p>For details on versions and how to upgrade, see <a href="index#versioning">Versioning</a> and <a href="index#upgrading">Upgrading</a>.</p> <h2 id="versioning">Versioning</h2> <p>There are three legacy versions of the Compose file format:</p> <ul> <li> <p>Version 1. This is specified by omitting a <code class="language-plaintext highlighter-rouge">version</code> key at the root of the YAML.</p> </li> <li> <p>Version 2.x. This is specified with a <code class="language-plaintext highlighter-rouge">version: '2'</code> or <code class="language-plaintext highlighter-rouge">version: '2.1'</code>, etc., entry at the root of the YAML.</p> </li> <li> <p>Version 3.x, designed to be cross-compatible between Compose and the Docker Engine’s <a href="../../../engine/swarm/index">swarm mode</a>. This is specified with a <code class="language-plaintext highlighter-rouge">version: '3'</code> or <code class="language-plaintext highlighter-rouge">version: '3.1'</code>, etc., entry at the root of the YAML.</p> </li> </ul> <p>The latest and recommended version of the Compose file format is defined by the <a href="https://github.com/compose-spec/compose-spec/blob/master/spec/">Compose Specification</a>. This format merges the 2.x and 3.x versions and is implemented by <strong>Compose 1.27.0+</strong>.</p> <blockquote> <h3 id="v2-and-v3-declaration">v2 and v3 Declaration</h3> <p><strong>Note</strong>: When specifying the Compose file version to use, make sure to specify both the <em>major</em> and <em>minor</em> numbers. If no minor version is given, <code class="language-plaintext highlighter-rouge">0</code> is used by default and not the latest minor version.</p> </blockquote> <p>The <a href="#compatibility-matrix">Compatibility Matrix</a> shows Compose file versions mapped to Docker Engine releases.</p> <p>To move your project to a later version, see the <a href="#upgrading">Upgrading</a> section.</p> <blockquote> <p><strong>Note</strong>: If you’re using <a href="../../extends/index#multiple-compose-files">multiple Compose files</a> or <a href="../../extends/index#extending-services">extending services</a>, each file must be of the same version - you cannot, for example, mix version 1 and 2 in a single project.</p> </blockquote> <p>Several things differ depending on which version you use:</p> <ul> <li>The structure and permitted configuration keys</li> <li>The minimum Docker Engine version you must be running</li> <li>Compose’s behaviour with regards to networking</li> </ul> <p>These differences are explained below.</p> <h3 id="version-1-deprecated">Version 1 (Deprecated)</h3> <p>Compose files that do not declare a version are considered “version 1”. In those files, all the <a href="../compose-file-v3/index#service-configuration-reference">services</a> are declared at the root of the document.</p> <p>Version 1 is supported by <strong>Compose up to 1.6.x</strong>. It will be deprecated in a future Compose release.</p> <p>Version 1 files cannot declare named <a href="../compose-file-v3/index#volume-configuration-reference">volumes</a>, <a href="../compose-file-v3/index#network-configuration-reference">networks</a> or <a href="../compose-file-v3/index#args">build arguments</a>.</p> <p>Compose does not take advantage of <a href="../../networking/index">networking</a> when you use version 1: every container is placed on the default <code class="language-plaintext highlighter-rouge">bridge</code> network and is reachable from every other container at its IP address. You need to use <code class="language-plaintext highlighter-rouge">links</code> to enable discovery between containers.</p> <p>Example:</p> <div class="highlight"><pre class="highlight" data-language="">web:
+  build: .
+  ports:
+   - "8000:5000"
+  volumes:
+   - .:/code
+  links:
+   - redis
+redis:
+  image: redis
+</pre></div> <h3 id="version-2">Version 2</h3> <p>Compose files using the version 2 syntax must indicate the version number at the root of the document. All <a href="../compose-file-v2/index#service-configuration-reference">services</a> must be declared under the <code class="language-plaintext highlighter-rouge">services</code> key.</p> <p>Version 2 files are supported by <strong>Compose 1.6.0+</strong> and require a Docker Engine of version <strong>1.10.0+</strong>.</p> <p>Named <a href="../compose-file-v2/index#volume-configuration-reference">volumes</a> can be declared under the <code class="language-plaintext highlighter-rouge">volumes</code> key, and <a href="../compose-file-v2/index#network-configuration-reference">networks</a> can be declared under the <code class="language-plaintext highlighter-rouge">networks</code> key.</p> <p>By default, every container joins an application-wide default network, and is discoverable at a hostname that’s the same as the service name. This means <a href="../compose-file-v2/index#links">links</a> are largely unnecessary. For more details, see <a href="../../networking/index">Networking in Compose</a>.</p> <blockquote> <p><strong>Note</strong></p> <p>When specifying the Compose file version to use, make sure to specify both the <em>major</em> and <em>minor</em> numbers. If no minor version is given, <code class="language-plaintext highlighter-rouge">0</code> is used by default and not the latest minor version. As a result, features added in later versions will not be supported. For example:</p> <div class="highlight"><pre class="highlight" data-language="">version: "2"
+</pre></div>  <p>is equivalent to:</p> <div class="highlight"><pre class="highlight" data-language="">version: "2.0"
+</pre></div>  </blockquote> <p>Simple example:</p> <div class="highlight"><pre class="highlight" data-language="">version: "2.4"
+services:
+  web:
+    build: .
+    ports:
+     - "8000:5000"
+    volumes:
+     - .:/code
+  redis:
+    image: redis
+</pre></div> <p>A more extended example, defining volumes and networks:</p> <div class="highlight"><pre class="highlight" data-language="">version: "2.4"
+services:
+  web:
+    build: .
+    ports:
+     - "8000:5000"
+    volumes:
+     - .:/code
+    networks:
+      - front-tier
+      - back-tier
+  redis:
+    image: redis
+    volumes:
+      - redis-data:/var/lib/redis
+    networks:
+      - back-tier
+volumes:
+  redis-data:
+    driver: local
+networks:
+  front-tier:
+    driver: bridge
+  back-tier:
+    driver: bridge
+</pre></div> <p>Several other options were added to support networking, such as:</p> <ul> <li> <p><a href="../compose-file-v2/index#aliases"><code class="language-plaintext highlighter-rouge">aliases</code></a></p> </li> <li> <p>The <a href="../compose-file-v2/index#depends_on"><code class="language-plaintext highlighter-rouge">depends_on</code></a> option can be used in place of links to indicate dependencies between services and startup order.</p> <div class="highlight"><pre class="highlight" data-language="">version: "2.4"
+services:
+  web:
+    build: .
+    depends_on:
+      - db
+      - redis
+  redis:
+    image: redis
+  db:
+    image: postgres
+</pre></div>  </li> <li> <p><a href="../compose-file-v2/index#ipv4_address-ipv6_address"><code class="language-plaintext highlighter-rouge">ipv4_address</code>, <code class="language-plaintext highlighter-rouge">ipv6_address</code></a></p> </li> </ul> <p><a href="../compose-file-v2/index#variable-substitution">Variable substitution</a> also was added in Version 2.</p> <h3 id="version-21">Version 2.1</h3> <p>An upgrade of <a href="#version-2">version 2</a> that introduces new parameters only available with Docker Engine version <strong>1.12.0+</strong>. Version 2.1 files are supported by <strong>Compose 1.9.0+</strong>.</p> <p>Introduces the following additional parameters:</p> <ul> <li><a href="../compose-file-v2/index#link_local_ips"><code class="language-plaintext highlighter-rouge">link_local_ips</code></a></li> <li>
+<a href="../compose-file-v2/index#isolation-1"><code class="language-plaintext highlighter-rouge">isolation</code></a> in build configurations and service definitions</li> <li>
+<code class="language-plaintext highlighter-rouge">labels</code> for <a href="../compose-file-v2/index#volume-configuration-reference">volumes</a>, <a href="../compose-file-v2/index#network-configuration-reference">networks</a>, and <a href="../compose-file-v3/index#build">build</a>
+</li> <li>
+<code class="language-plaintext highlighter-rouge">name</code> for <a href="../compose-file-v2/index#volume-configuration-reference">volumes</a>
+</li> <li><a href="../compose-file-v2/index#userns_mode"><code class="language-plaintext highlighter-rouge">userns_mode</code></a></li> <li><a href="../compose-file-v2/index#healthcheck"><code class="language-plaintext highlighter-rouge">healthcheck</code></a></li> <li><a href="../compose-file-v2/index#sysctls"><code class="language-plaintext highlighter-rouge">sysctls</code></a></li> <li><a href="../compose-file-v2/index#pids_limit"><code class="language-plaintext highlighter-rouge">pids_limit</code></a></li> <li><a href="../compose-file-v2/index#cpu-and-other-resources"><code class="language-plaintext highlighter-rouge">oom_kill_disable</code></a></li> <li><a href="../compose-file-v2/index#cpu-and-other-resources"><code class="language-plaintext highlighter-rouge">cpu_period</code></a></li> </ul> <h3 id="version-22">Version 2.2</h3> <p>An upgrade of <a href="#version-21">version 2.1</a> that introduces new parameters only available with Docker Engine version <strong>1.13.0+</strong>. Version 2.2 files are supported by <strong>Compose 1.13.0+</strong>. This version also allows you to specify default scale numbers inside the service’s configuration.</p> <p>Introduces the following additional parameters:</p> <ul> <li><a href="../compose-file-v2/index#init"><code class="language-plaintext highlighter-rouge">init</code></a></li> <li><a href="../compose-file-v2/index#scale"><code class="language-plaintext highlighter-rouge">scale</code></a></li> <li><a href="../compose-file-v2/index#cpu_rt_runtime-cpu_rt_period"><code class="language-plaintext highlighter-rouge">cpu_rt_runtime</code> and <code class="language-plaintext highlighter-rouge">cpu_rt_period</code></a></li> <li>
+<a href="../compose-file-v2/index#network"><code class="language-plaintext highlighter-rouge">network</code></a> for <a href="../compose-file-v2/index#build">build configurations</a>
+</li> </ul> <h3 id="version-23">Version 2.3</h3> <p>An upgrade of <a href="#version-22">version 2.2</a> that introduces new parameters only available with Docker Engine version <strong>17.06.0+</strong>. Version 2.3 files are supported by <strong>Compose 1.16.0+</strong>.</p> <p>Introduces the following additional parameters:</p> <ul> <li>
+<a href="../compose-file-v2/index#target"><code class="language-plaintext highlighter-rouge">target</code></a>, <a href="../compose-file-v2/index#extra_hosts-1"><code class="language-plaintext highlighter-rouge">extra_hosts</code></a> and <a href="../compose-file-v2/index#shm_size"><code class="language-plaintext highlighter-rouge">shm_size</code></a> for <a href="../compose-file-v2/index#build">build configurations</a>
+</li> <li>
+<code class="language-plaintext highlighter-rouge">start_period</code> for <a href="../compose-file-v2/index#healthcheck"><code class="language-plaintext highlighter-rouge">healthchecks</code></a>
+</li> <li><a href="../compose-file-v2/index#long-syntax">“Long syntax” for volumes</a></li> <li>
+<a href="../compose-file-v2/index#runtime"><code class="language-plaintext highlighter-rouge">runtime</code></a> for service definitions</li> <li><a href="../compose-file-v2/index#device_cgroup_rules"><code class="language-plaintext highlighter-rouge">device_cgroup_rules</code></a></li> </ul> <h3 id="version-24">Version 2.4</h3> <p>An upgrade of <a href="#version-23">version 2.3</a> that introduces new parameters only available with Docker Engine version <strong>17.12.0+</strong>. Version 2.4 files are supported by <strong>Compose 1.21.0+</strong>.</p> <p>Introduces the following additional parameters:</p> <ul> <li>
+<a href="../compose-file-v2/index#platform"><code class="language-plaintext highlighter-rouge">platform</code></a> for service definitions</li> <li>Support for extension fields at the root of service, network, and volume definitions</li> </ul> <h3 id="version-3">Version 3</h3> <p>Designed to be cross-compatible between Compose and the Docker Engine’s <a href="../../../engine/swarm/index">swarm mode</a>, version 3 removes several options and adds several more.</p> <ul> <li> <p>Removed: <code class="language-plaintext highlighter-rouge">volume_driver</code>, <code class="language-plaintext highlighter-rouge">volumes_from</code>, <code class="language-plaintext highlighter-rouge">cpu_shares</code>, <code class="language-plaintext highlighter-rouge">cpu_quota</code>, <code class="language-plaintext highlighter-rouge">cpuset</code>, <code class="language-plaintext highlighter-rouge">mem_limit</code>, <code class="language-plaintext highlighter-rouge">memswap_limit</code>, <code class="language-plaintext highlighter-rouge">extends</code>, <code class="language-plaintext highlighter-rouge">group_add</code>. See the <a href="#upgrading">upgrading</a> guide for how to migrate away from these. (For more information on <code class="language-plaintext highlighter-rouge">extends</code>, see <a href="../../extends/index#extending-services">Extending services</a>.)</p> </li> <li> <p>Added: <a href="../compose-file-v3/index#deploy">deploy</a></p> </li> </ul> <blockquote> <p><strong>Note</strong>: When specifying the Compose file version to use, make sure to specify both the <em>major</em> and <em>minor</em> numbers. If no minor version is given, <code class="language-plaintext highlighter-rouge">0</code> is used by default and not the latest minor version. As a result, features added in later versions will not be supported. For example:</p> <div class="highlight"><pre class="highlight" data-language="">version: "3"
+</pre></div>  <p>is equivalent to:</p> <div class="highlight"><pre class="highlight" data-language="">version: "3.0"
+</pre></div>  </blockquote> <h3 id="version-31">Version 3.1</h3> <p>An upgrade of <a href="#version-3">version 3</a> that introduces new parameters only available with Docker Engine version <strong>1.13.1+</strong>, and higher.</p> <p>Introduces the following additional parameters:</p> <ul> <li><a href="../compose-file-v3/index#secrets"><code class="language-plaintext highlighter-rouge">secrets</code></a></li> </ul> <h3 id="version-32">Version 3.2</h3> <p>An upgrade of <a href="#version-3">version 3</a> that introduces new parameters only available with Docker Engine version <strong>17.04.0+</strong>, and higher.</p> <p>Introduces the following additional parameters:</p> <ul> <li>
+<a href="../compose-file-v3/index#cache_from"><code class="language-plaintext highlighter-rouge">cache_from</code></a> in <a href="../compose-file-v3/index#build">build configurations</a>
+</li> <li>Long syntax for <a href="../compose-file-v3/index#ports">ports</a> and <a href="../compose-file-v3/index#volumes">volume mounts</a>
+</li> <li>
+<a href="../compose-file-v3/index#attachable"><code class="language-plaintext highlighter-rouge">attachable</code></a> network driver option</li> <li><a href="../compose-file-v3/index#endpoint_mode">deploy <code class="language-plaintext highlighter-rouge">endpoint_mode</code></a></li> <li><a href="../compose-file-v3/index#placement">deploy placement <code class="language-plaintext highlighter-rouge">preference</code></a></li> </ul> <h3 id="version-33">Version 3.3</h3> <p>An upgrade of <a href="#version-3">version 3</a> that introduces new parameters only available with Docker Engine version <strong>17.06.0+</strong>, and higher.</p> <p>Introduces the following additional parameters:</p> <ul> <li><a href="../compose-file-v3/index#build">build <code class="language-plaintext highlighter-rouge">labels</code></a></li> <li><a href="../compose-file-v3/index#credential_spec"><code class="language-plaintext highlighter-rouge">credential_spec</code></a></li> <li><a href="../compose-file-v3/index#configs"><code class="language-plaintext highlighter-rouge">configs</code></a></li> </ul> <h3 id="version-34">Version 3.4</h3> <p>An upgrade of <a href="#version-3">version 3</a> that introduces new parameters. It is only available with Docker Engine version <strong>17.09.0</strong> and higher.</p> <p>Introduces the following additional parameters:</p> <ul> <li>
+<a href="../compose-file-v3/index#target"><code class="language-plaintext highlighter-rouge">target</code></a> and <a href="../compose-file-v3/index#network"><code class="language-plaintext highlighter-rouge">network</code></a> in <a href="../compose-file-v3/index#build">build configurations</a>
+</li> <li>
+<code class="language-plaintext highlighter-rouge">start_period</code> for <a href="../compose-file-v3/index#healthcheck"><code class="language-plaintext highlighter-rouge">healthchecks</code></a>
+</li> <li>
+<code class="language-plaintext highlighter-rouge">order</code> for <a href="../compose-file-v3/index#update_config">update configurations</a>
+</li> <li>
+<code class="language-plaintext highlighter-rouge">name</code> for <a href="../compose-file-v3/index#volume-configuration-reference">volumes</a>
+</li> </ul> <h3 id="version-35">Version 3.5</h3> <p>An upgrade of <a href="#version-3">version 3</a> that introduces new parameters. It is only available with Docker Engine version <strong>17.12.0</strong> and higher.</p> <p>Introduces the following additional parameters:</p> <ul> <li>
+<a href="../compose-file-v3/index#isolation"><code class="language-plaintext highlighter-rouge">isolation</code></a> in service definitions</li> <li>
+<code class="language-plaintext highlighter-rouge">name</code> for networks, secrets and configs</li> <li>
+<code class="language-plaintext highlighter-rouge">shm_size</code> in <a href="../compose-file-v3/index#build">build configurations</a>
+</li> </ul> <h3 id="version-36">Version 3.6</h3> <p>An upgrade of <a href="#version-3">version 3</a> that introduces new parameters. It is only available with Docker Engine version <strong>18.02.0</strong> and higher.</p> <p>Introduces the following additional parameters:</p> <ul> <li>
+<a href="../compose-file-v3/index#long-syntax-3"><code class="language-plaintext highlighter-rouge">tmpfs</code> size</a> for <code class="language-plaintext highlighter-rouge">tmpfs</code>-type mounts</li> </ul> <h3 id="version-37">Version 3.7</h3> <p>An upgrade of <a href="#version-3">version 3</a> that introduces new parameters. It is only available with Docker Engine version <strong>18.06.0</strong> and higher.</p> <p>Introduces the following additional parameters:</p> <ul> <li>
+<a href="../compose-file-v3/index#init"><code class="language-plaintext highlighter-rouge">init</code></a> in service definitions</li> <li>
+<a href="../compose-file-v3/index#rollback_config"><code class="language-plaintext highlighter-rouge">rollback_config</code></a> in deploy configurations</li> <li>Support for extension fields at the root of service, network, volume, secret and config definitions</li> </ul> <h3 id="version-38">Version 3.8</h3> <p>An upgrade of <a href="#version-3">version 3</a> that introduces new parameters. It is only available with Docker Engine version <strong>19.03.0</strong> and higher.</p> <p>Introduces the following additional parameters:</p> <ul> <li>
+<a href="../compose-file-v3/index#max_replicas_per_node"><code class="language-plaintext highlighter-rouge">max_replicas_per_node</code></a> in placement configurations</li> <li>
+<code class="language-plaintext highlighter-rouge">template_driver</code> option for <a href="../compose-file-v3/index#configs-configuration-reference">config</a> and <a href="../compose-file-v3/index#secrets-configuration-reference">secret</a> configurations. This option is only supported when deploying swarm services using <code class="language-plaintext highlighter-rouge">docker stack deploy</code>.</li> <li>
+<code class="language-plaintext highlighter-rouge">driver</code> and <code class="language-plaintext highlighter-rouge">driver_opts</code> option for <a href="../compose-file-v3/index#secrets-configuration-reference">secret</a> configurations. This option is only supported when deploying swarm services using <code class="language-plaintext highlighter-rouge">docker stack deploy</code>.</li> </ul> <h2 id="upgrading">Upgrading</h2> <h3 id="version-2x-to-3x">Version 2.x to 3.x</h3> <p>Between versions 2.x and 3.x, the structure of the Compose file is the same, but several options have been removed:</p> <ul> <li> <p><code class="language-plaintext highlighter-rouge">volume_driver</code>: Instead of setting the volume driver on the service, define a volume using the <a href="../compose-file-v3/index#volume-configuration-reference">top-level <code class="language-plaintext highlighter-rouge">volumes</code> option</a> and specify the driver there.</p> <div class="highlight"><pre class="highlight" data-language="">version: "3.9"
+services:
+  db:
+    image: postgres
+    volumes:
+      - data:/var/lib/postgresql/data
+volumes:
+  data:
+    driver: mydriver
+</pre></div>  </li> <li> <p><code class="language-plaintext highlighter-rouge">volumes_from</code>: To share a volume between services, define it using the <a href="../compose-file-v3/index#volume-configuration-reference">top-level <code class="language-plaintext highlighter-rouge">volumes</code> option</a> and reference it from each service that shares it using the <a href="../compose-file-v3/index#driver">service-level <code class="language-plaintext highlighter-rouge">volumes</code> option</a>.</p> </li> <li> <p><code class="language-plaintext highlighter-rouge">cpu_shares</code>, <code class="language-plaintext highlighter-rouge">cpu_quota</code>, <code class="language-plaintext highlighter-rouge">cpuset</code>, <code class="language-plaintext highlighter-rouge">mem_limit</code>, <code class="language-plaintext highlighter-rouge">memswap_limit</code>: These have been replaced by the <a href="../compose-file-v3/index#resources">resources</a> key under <code class="language-plaintext highlighter-rouge">deploy</code>. <code class="language-plaintext highlighter-rouge">deploy</code> configuration only takes effect when using <code class="language-plaintext highlighter-rouge">docker stack deploy</code>, and is ignored by <code class="language-plaintext highlighter-rouge">docker-compose</code>.</p> </li> <li>
+<code class="language-plaintext highlighter-rouge">extends</code>: This option has been removed for <code class="language-plaintext highlighter-rouge">version: "3.x"</code> Compose files. (For more information, see <a href="../../extends/index#extending-services">Extending services</a>.)</li> <li>
+<code class="language-plaintext highlighter-rouge">group_add</code>: This option has been removed for <code class="language-plaintext highlighter-rouge">version: "3.x"</code> Compose files.</li> <li>
+<code class="language-plaintext highlighter-rouge">pids_limit</code>: This option has not been introduced in <code class="language-plaintext highlighter-rouge">version: "3.x"</code> Compose files.</li> <li>
+<code class="language-plaintext highlighter-rouge">link_local_ips</code> in <code class="language-plaintext highlighter-rouge">networks</code>: This option has not been introduced in <code class="language-plaintext highlighter-rouge">version: "3.x"</code> Compose files.</li> </ul> <h3 id="version-1-to-2x">Version 1 to 2.x</h3> <p>In the majority of cases, moving from version 1 to 2 is a very simple process:</p> <ol> <li>Indent the whole file by one level and put a <code class="language-plaintext highlighter-rouge">services:</code> key at the top.</li> <li>Add a <code class="language-plaintext highlighter-rouge">version: '2'</code> line at the top of the file.</li> </ol> <p>It’s more complicated if you’re using particular configuration features:</p> <ul> <li> <p><code class="language-plaintext highlighter-rouge">dockerfile</code>: This now lives under the <code class="language-plaintext highlighter-rouge">build</code> key:</p> <div class="highlight"><pre class="highlight" data-language="">build:
+  context: .
+  dockerfile: Dockerfile-alternate
+</pre></div>  </li> <li> <p><code class="language-plaintext highlighter-rouge">log_driver</code>, <code class="language-plaintext highlighter-rouge">log_opt</code>: These now live under the <code class="language-plaintext highlighter-rouge">logging</code> key:</p> <div class="highlight"><pre class="highlight" data-language="">logging:
+  driver: syslog
+  options:
+    syslog-address: "tcp://192.168.0.42:123"
+</pre></div>  </li> <li> <p><code class="language-plaintext highlighter-rouge">links</code> with environment variables: environment variables created by links, such as <code class="language-plaintext highlighter-rouge">CONTAINERNAME_PORT</code>, ` have been deprecated for some time. In the new Docker network system, they have been removed. You should either connect directly to the appropriate hostname or set the relevant environment variable yourself, using the link hostname:</p> <div class="highlight"><pre class="highlight" data-language="">web:
+  links:
+    - db
+  environment:
+    - DB_PORT=tcp://db:5432
+</pre></div>  </li> <li> <p><code class="language-plaintext highlighter-rouge">external_links</code>: Compose uses Docker networks when running version 2 projects, so links behave slightly differently. In particular, two containers must be connected to at least one network in common in order to communicate, even if explicitly linked together.</p> <p>Either connect the external container to your app’s <a href="../../networking/index">default network</a>, or connect both the external container and your service’s containers to an <a href="../../networking/index#use-a-pre-existing-network">external network</a>.</p> </li> <li> <p><code class="language-plaintext highlighter-rouge">net</code>: This is now replaced by <a href="../compose-file-v3/index#network_mode">network_mode</a>:</p> <div class="highlight"><pre class="highlight" data-language="">net: host    -&gt;  network_mode: host
+net: bridge  -&gt;  network_mode: bridge
+net: none    -&gt;  network_mode: none
+</pre></div>  <p>If you’re using <code class="language-plaintext highlighter-rouge">net: "container:[service name]"</code>, you must now use <code class="language-plaintext highlighter-rouge">network_mode: "service:[service name]"</code> instead.</p> <div class="highlight"><pre class="highlight" data-language="">net: "container:web"  -&gt;  network_mode: "service:web"
+</pre></div>  <p>If you’re using <code class="language-plaintext highlighter-rouge">net: "container:[container name/id]"</code>, the value does not need to change.</p> <div class="highlight"><pre class="highlight" data-language="">net: "container:cont-name"  -&gt;  network_mode: "container:cont-name"
+net: "container:abc12345"   -&gt;  network_mode: "container:abc12345"
+</pre></div>  </li> <li> <p><code class="language-plaintext highlighter-rouge">volumes</code> with named volumes: these must now be explicitly declared in a top-level <code class="language-plaintext highlighter-rouge">volumes</code> section of your Compose file. If a service mounts a named volume called <code class="language-plaintext highlighter-rouge">data</code>, you must declare a <code class="language-plaintext highlighter-rouge">data</code> volume in your top-level <code class="language-plaintext highlighter-rouge">volumes</code> section. The whole file might look like this:</p> <div class="highlight"><pre class="highlight" data-language="">version: "2.4"
+services:
+  db:
+    image: postgres
+    volumes:
+      - data:/var/lib/postgresql/data
+volumes:
+  data: {}
+</pre></div>  <p>By default, Compose creates a volume whose name is prefixed with your project name. If you want it to just be called <code class="language-plaintext highlighter-rouge">data</code>, declare it as external:</p> <div class="highlight"><pre class="highlight" data-language="">volumes:
+  data:
+    external: true
+</pre></div>  </li> </ul> <h2 id="compatibility-mode">Compatibility mode</h2> <p><code class="language-plaintext highlighter-rouge">docker-compose</code> 1.20.0 introduces a new <code class="language-plaintext highlighter-rouge">--compatibility</code> flag designed to help developers transition to version 3 more easily. When enabled, <code class="language-plaintext highlighter-rouge">docker-compose</code> reads the <code class="language-plaintext highlighter-rouge">deploy</code> section of each service’s definition and attempts to translate it into the equivalent version 2 parameter. Currently, the following deploy keys are translated:</p> <ul> <li>
+<a href="../compose-file-v3/index#resources">resources</a> limits and memory reservations</li> <li><a href="../compose-file-v3/index#replicas">replicas</a></li> <li>
+<a href="../compose-file-v3/index#restart_policy">restart_policy</a> <code class="language-plaintext highlighter-rouge">condition</code> and <code class="language-plaintext highlighter-rouge">max_attempts</code>
+</li> </ul> <p>All other keys are ignored and produce a warning if present. You can review the configuration that will be used to deploy by using the <code class="language-plaintext highlighter-rouge">--compatibility</code> flag with the <code class="language-plaintext highlighter-rouge">config</code> command.</p> <blockquote> <p>Do not use this in production!</p> <p>We recommend against using <code class="language-plaintext highlighter-rouge">--compatibility</code> mode in production. Because the resulting configuration is only an approximate using non-Swarm mode properties, it may produce unexpected results.</p> </blockquote> <h2 id="compose-file-format-references">Compose file format references</h2> <ul> <li><a href="../index">Compose Specification</a></li> <li><a href="../compose-file-v3/index">Compose file version 3</a></li> <li><a href="../compose-file-v2/index">Compose file version 2</a></li> </ul> 
+<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=versions">versions</a>, <a href="https://docs.docker.com/search/?q=upgrading">upgrading</a>, <a href="https://docs.docker.com/search/?q=docker">docker</a></p>
+<div class="_attribution">
+  <p class="_attribution-p">
+    &copy; 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/compose-versioning/" class="_attribution-link">https://docs.docker.com/compose/compose-file/compose-versioning/</a>
+  </p>
+</div>