From d55371d48b5af8f6d4f339b9bc5160b69e71e863 Mon Sep 17 00:00:00 2001 From: Allie Sadler <102604716+aevesdocker@users.noreply.github.com> Date: Tue, 18 Apr 2023 12:12:31 +0100 Subject: [PATCH] ENGDOCS-1303 (#17131) --- _includes/compose-eol.md | 2 +- compose/compose-file/compose-versioning.md | 122 +++++++++++---------- compose/compose-v2/index.md | 2 +- 3 files changed, 67 insertions(+), 59 deletions(-) diff --git a/_includes/compose-eol.md b/_includes/compose-eol.md index eb740c5e8a..1a508d4bf9 100644 --- a/_includes/compose-eol.md +++ b/_includes/compose-eol.md @@ -2,5 +2,5 @@ > > From the end of June 2023 Compose V1 won't be supported anymore and will be removed from all Docker Desktop versions. > -> Make sure you switch to [Compose V2](/compose/compose-file/) with the `docker compose` CLI plugin or by activating the **Use Docker Compose V2** setting in Docker Desktop. For more information, see the [Evolution of Compose](/compose/compose-v2/) +> Make sure you switch to [Compose V2](/compose/compose-file/) with the `docker compose` CLI plugin or by activating the **Use Docker Compose V2** setting in Docker Desktop. For more information, see the [Evolution of Compose](/compose/compose-v2/). {: .important} \ No newline at end of file diff --git a/compose/compose-file/compose-versioning.md b/compose/compose-file/compose-versioning.md index 6aa9ddc763..a37784a31d 100644 --- a/compose/compose-file/compose-versioning.md +++ b/compose/compose-file/compose-versioning.md @@ -4,6 +4,17 @@ keywords: fig, composition, compose, versions, upgrading, docker title: Compose file versions and upgrading --- +>**Warning** +> +>This page contains information on the legacy versions of Compose, also collectively referred to as Compose V1. +>From the end of June 2023 Compose V1 won’t be supported anymore. +> +>The latest and recommended version of Compose is the [Compose Specification](index.md). +>Make sure you switch to [Compose V2](/compose/compose-file/) with the `docker compose` CLI plugin or by activating the **Use Docker Compose V2** setting in Docker Desktop. +> +> For more information, see the [Evolution of Compose](/compose/compose-v2/). +{: .warning} + The Compose file is a [YAML](https://yaml.org) file defining services, networks, and volumes for a Docker application. @@ -11,7 +22,6 @@ The Compose file formats are now described in these references, specific to each | **Reference file** | **What changed in this version** | |:------------------------------------------------------|:---------------------------------| -| [Compose Specification](index.md) (most current, and recommended) | [Versioning](compose-versioning.md#versioning) | | [Version 3](compose-file-v3.md) | [Version 3 updates](#version-3) | | [Version 2](compose-file-v2.md) | [Version 2 updates](#version-2) | | Version 1 (Deprecated) | [Version 1 updates](#version-1-deprecated) | @@ -21,8 +31,6 @@ compatibility, and [how to upgrade](#upgrading). ## Compatibility matrix -There are several versions of the Compose file format – 1, 2, 2.x, and 3.x - {% include content/compose-matrix.md %} > Looking for more detail on Docker and Compose compatibility? @@ -79,36 +87,7 @@ Several things differ depending on which version you use: These differences are explained below. -### Version 1 (Deprecated) -Compose files that do not declare a version are considered "version 1". In those -files, all the [services](compose-file-v3.md#service-configuration-reference) are -declared at the root of the document. - -Version 1 is supported by **Compose up to 1.6.x**. It will be deprecated in a -future Compose release. - -Version 1 files cannot declare named -[volumes](compose-file-v3.md#volume-configuration-reference), [networks](compose-file-v3.md#network-configuration-reference) or -[build arguments](compose-file-v3.md#args). - -Compose does not take advantage of [networking](../networking.md) when you -use version 1: every container is placed on the default `bridge` network and is -reachable from every other container at its IP address. You need to use -`links` to enable discovery between containers. - -Example: - - web: - build: . - ports: - - "8000:5000" - volumes: - - .:/code - links: - - redis - redis: - image: redis ### Version 2 @@ -394,6 +373,38 @@ Introduces the following additional parameters: configurations. This option is only supported when deploying swarm services using `docker stack deploy`. +### Version 1 (Deprecated) + +Compose versions below 1.6.x are + +Compose files that do not declare a version are considered "version 1". In those +files, all the [services](compose-file-v3.md#service-configuration-reference) are +declared at the root of the document. + +Version 1 is supported by Compose up to 1.6.x** and has been deprecated. + +Version 1 files cannot declare named +[volumes](compose-file-v3.md#volume-configuration-reference), [networks](compose-file-v3.md#network-configuration-reference) or +[build arguments](compose-file-v3.md#args). + +Compose does not take advantage of [networking](../networking.md) when you +use version 1: every container is placed on the default `bridge` network and is +reachable from every other container at its IP address. You need to use +`links` to enable discovery between containers. + +Example: + + web: + build: . + ports: + - "8000:5000" + volumes: + - .:/code + links: + - redis + redis: + image: redis + ## Upgrading ### Version 2.x to 3.x @@ -433,6 +444,28 @@ Compose files. (For more information, see [Extending services](../extends.md#ext - `link_local_ips` in `networks`: This option has not been introduced in `version: "3.x"` Compose files. +#### Compatibility mode + +`docker-compose` 1.20.0 introduces a new `--compatibility` flag designed to +help developers transition to version 3 more easily. When enabled, +`docker-compose` reads the `deploy` section of each service's definition and +attempts to translate it into the equivalent version 2 parameter. Currently, +the following deploy keys are translated: + +- [resources](compose-file-v3.md#resources) limits and memory reservations +- [replicas](compose-file-v3.md#replicas) +- [restart_policy](compose-file-v3.md#restart_policy) `condition` and `max_attempts` + +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 `--compatibility` +flag with the `config` command. + +> Do not use this in production +> +> We recommend against using `--compatibility` mode in production. The +> resulting configuration is only an approximate using non-Swarm mode +> properties, it may produce unexpected results. + ### Version 1 to 2.x In the majority of cases, moving from version 1 to 2 is a very simple process: @@ -516,29 +549,4 @@ It's more complicated if you're using particular configuration features: data: external: true -## Compatibility mode -`docker-compose` 1.20.0 introduces a new `--compatibility` flag designed to -help developers transition to version 3 more easily. When enabled, -`docker-compose` reads the `deploy` section of each service's definition and -attempts to translate it into the equivalent version 2 parameter. Currently, -the following deploy keys are translated: - -- [resources](compose-file-v3.md#resources) limits and memory reservations -- [replicas](compose-file-v3.md#replicas) -- [restart_policy](compose-file-v3.md#restart_policy) `condition` and `max_attempts` - -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 `--compatibility` -flag with the `config` command. - -> Do not use this in production! -> -> We recommend against using `--compatibility` mode in production. Because the -> resulting configuration is only an approximate using non-Swarm mode -> properties, it may produce unexpected results. - -## Compose file format references -- [Compose Specification](index.md) -- [Compose file version 3](compose-file-v3.md) -- [Compose file version 2](compose-file-v2.md) \ No newline at end of file diff --git a/compose/compose-v2/index.md b/compose/compose-v2/index.md index 1f2ea0e7d4..20ad0af5df 100644 --- a/compose/compose-v2/index.md +++ b/compose/compose-v2/index.md @@ -19,7 +19,7 @@ Between 2014 and 2017 two other noticeable versions of Compose, which introduced These three key file format versions and releases prior to v1.29.2 are collectively referred to as Compose V1. -In mid-2020 Compose V2 was released. It merged Compose file format V2 and V3 and was written in Go. The file format is defined by the [Compose specification](https://github.com/compose-spec/compose-spec){:target="_blank" rel="noopener" class="_"}. Compose V2 is the latest and recommended version of Compose. It provides improved integration with other Docker command-line features, and simplified installation on macOS, Windows, and Linux. +In mid-2020 Compose V2 was released. It merged Compose file format V2 and V3 and was written in Go. The file format is defined by the [Compose specification](https://github.com/compose-spec/compose-spec){:target="_blank" rel="noopener" class="_"}. Compose V2 is the latest and recommended version of Compose and is compatible with Docker Engine version 19.03.0 and later. It provides improved integration with other Docker command-line features, and simplified installation on macOS, Windows, and Linux. It makes a clean distinction between the Compose YAML file model and the `docker-compose` implementation. Making this change has enabled a number of enhancements, including