docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
docs/compose/compose-file/compose-versioning.md

532 lines
20 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
description: Compose file reference
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 [History of Compose](/compose/history/).
{: .warning}
The Compose file is a [YAML](https://yaml.org) file defining services,
networks, and volumes for a Docker application.
The Compose file formats are now described in these references, specific to each version.
| **Reference file** | **What changed in this version** |
|:------------------------------------------------------|:---------------------------------|
| [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) |
The topics below explain the differences among the versions, Docker Engine
compatibility, and [how to upgrade](#upgrading).
## Compatibility matrix
{% include content/compose-matrix.md %}
> Looking for more detail on Docker and Compose compatibility?
>
> 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 [Compose release
notes](https://github.com/docker/compose/releases/). 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
[issue #3404]({{ site.repo }}/issues/3404).)
For details on versions and how to upgrade, see
[Versioning](compose-versioning.md#versioning) and
[Upgrading](compose-versioning.md#upgrading).
## Versioning
There are three legacy versions of the Compose file format:
- Version 1. This is specified by omitting a `version` key at the root of the YAML.
- Version 2.x. This is specified with a `version: '2'` or `version: '2.1'`, etc., entry at the root of the YAML.
- Version 3.x, designed to be cross-compatible between Compose and the Docker Engine's
[swarm mode](../../engine/swarm/index.md). This is specified with a `version: '3'` or `version: '3.1'`, etc., entry at the root of the YAML.
The latest and recommended version of the Compose file format is defined by the [Compose Specification](https://github.com/compose-spec/compose-spec/blob/master/spec.md). This format merges the 2.x and 3.x versions and is implemented by **Compose 1.27.0+**.
The [Compatibility Matrix](#compatibility-matrix) shows Compose file versions mapped to Docker Engine releases.
To move your project to a later version, see the [Upgrading](#upgrading)
section.
> **Note**: If you're using
> [multiple Compose files](../extends.md#multiple-compose-files) or
> [extending services](../extends.md#extending-services), each file must be of the
> same version - you cannot, for example, mix version 1 and 2 in a single
> project.
Several things differ depending on which version you use:
- The structure and permitted configuration keys
- The minimum Docker Engine version you must be running
- Compose's behaviour with regards to networking
These differences are explained below.
### Version 2
Compose files using the version 2 syntax must indicate the version number at
the root of the document. All [services](compose-file-v2.md#service-configuration-reference)
must be declared under the `services` key.
Version 2 files are supported by **Compose 1.6.0+** and require a Docker Engine
of version **1.10.0+**.
Named [volumes](compose-file-v2.md#volume-configuration-reference) can be declared under the
`volumes` key, and [networks](compose-file-v2.md#network-configuration-reference) can be declared
under the `networks` key.
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
[links](compose-file-v2.md#links) are largely unnecessary. For more details, see
[Networking in Compose](../networking.md).
> **Note**
>
> With Compose version 2, when specifying the Compose file version to use, make sure to
> specify both the _major_ and _minor_ numbers. If no minor version is given,
> `0` is used by default and not the latest minor version. As a result, features added in later versions will not be supported. For example:
>
> ```yaml
> version: "2"
> ```
>
> is equivalent to:
>
> ```yaml
> version: "2.0"
> ```
Simple example:
version: "{{ site.compose_file_v2 }}"
services:
web:
build: .
ports:
- "8000:5000"
volumes:
- .:/code
redis:
image: redis
A more extended example, defining volumes and networks:
version: "{{ site.compose_file_v2 }}"
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
Several other options were added to support networking, such as:
* [`aliases`](compose-file-v2.md#aliases)
* The [`depends_on`](compose-file-v2.md#depends_on) option can be used in place of links to indicate dependencies
between services and startup order.
version: "{{ site.compose_file_v2 }}"
services:
web:
build: .
depends_on:
- db
- redis
redis:
image: redis
db:
image: postgres
* [`ipv4_address`, `ipv6_address`](compose-file-v2.md#ipv4_address-ipv6_address)
[Variable substitution](compose-file-v2.md#variable-substitution) also was added in Version 2.
### Version 2.1
An upgrade of [version 2](#version-2) that introduces new parameters only
available with Docker Engine version **1.12.0+**. Version 2.1 files are
supported by **Compose 1.9.0+**.
Introduces the following additional parameters:
- [`link_local_ips`](compose-file-v2.md#link_local_ips)
- [`isolation`](compose-file-v2.md#isolation-1) in build configurations and
service definitions
- `labels` for [volumes](compose-file-v2.md#volume-configuration-reference),
[networks](compose-file-v2.md#network-configuration-reference), and
[build](compose-file-v3.md#build)
- `name` for [volumes](compose-file-v2.md#volume-configuration-reference)
- [`userns_mode`](compose-file-v2.md#userns_mode)
- [`healthcheck`](compose-file-v2.md#healthcheck)
- [`sysctls`](compose-file-v2.md#sysctls)
- [`pids_limit`](compose-file-v2.md#pids_limit)
- [`oom_kill_disable`](compose-file-v2.md#cpu-and-other-resources)
- [`cpu_period`](compose-file-v2.md#cpu-and-other-resources)
### Version 2.2
An upgrade of [version 2.1](#version-21) that introduces new parameters only
available with Docker Engine version **1.13.0+**. Version 2.2 files are
supported by **Compose 1.13.0+**. This version also allows you to specify
default scale numbers inside the service's configuration.
Introduces the following additional parameters:
- [`init`](compose-file-v2.md#init)
- [`scale`](compose-file-v2.md#scale)
- [`cpu_rt_runtime` and `cpu_rt_period`](compose-file-v2.md#cpu_rt_runtime-cpu_rt_period)
- [`network`](compose-file-v2.md#network) for [build configurations](compose-file-v2.md#build)
### Version 2.3
An upgrade of [version 2.2](#version-22) that introduces new parameters only
available with Docker Engine version **17.06.0+**. Version 2.3 files are
supported by **Compose 1.16.0+**.
Introduces the following additional parameters:
- [`target`](compose-file-v2.md#target), [`extra_hosts`](compose-file-v2.md#extra_hosts-1) and
[`shm_size`](compose-file-v2.md#shm_size) for [build configurations](compose-file-v2.md#build)
- `start_period` for [`healthchecks`](compose-file-v2.md#healthcheck)
- ["Long syntax" for volumes](compose-file-v2.md#long-syntax)
- [`runtime`](compose-file-v2.md#runtime) for service definitions
- [`device_cgroup_rules`](compose-file-v2.md#device_cgroup_rules)
### Version 2.4
An upgrade of [version 2.3](#version-23) that introduces new parameters only
available with Docker Engine version **17.12.0+**. Version 2.4 files are
supported by **Compose 1.21.0+**.
Introduces the following additional parameters:
- [`platform`](compose-file-v2.md#platform) for service definitions
- Support for extension fields at the root of service, network, and volume
definitions
### Version 3
Designed to be cross-compatible between Compose and the Docker Engine's
[swarm mode](/engine/swarm/), version 3 removes several options and adds
several more.
- Removed: `volume_driver`, `volumes_from`, `cpu_shares`, `cpu_quota`,
`cpuset`, `mem_limit`, `memswap_limit`, `extends`, `group_add`. See
the [upgrading](#upgrading) guide for how to migrate away from these.
(For more information on `extends`, see [Extending services](../extends.md#extending-services).)
- Added: [deploy](compose-file-v3.md#deploy)
If only the major version is given (`version: '3'`),
the latest minor version is used by default.
### Version 3.1
An upgrade of [version 3](#version-3) that introduces new parameters only
available with Docker Engine version **1.13.1+**, and higher.
Introduces the following additional parameters:
- [`secrets`](compose-file-v3.md#secrets)
### Version 3.2
An upgrade of [version 3](#version-3) that introduces new parameters only
available with Docker Engine version **17.04.0+**, and higher.
Introduces the following additional parameters:
- [`cache_from`](compose-file-v3.md#cache_from) in [build configurations](compose-file-v3.md#build)
- Long syntax for [ports](compose-file-v3.md#ports) and [volume mounts](compose-file-v3.md#volumes)
- [`attachable`](compose-file-v3.md#attachable) network driver option
- [deploy `endpoint_mode`](compose-file-v3.md#endpoint_mode)
- [deploy placement `preference`](compose-file-v3.md#placement)
### Version 3.3
An upgrade of [version 3](#version-3) that introduces new parameters only
available with Docker Engine version **17.06.0+**, and higher.
Introduces the following additional parameters:
- [build `labels`](compose-file-v3.md#build)
- [`credential_spec`](compose-file-v3.md#credential_spec)
- [`configs`](compose-file-v3.md#configs)
### Version 3.4
An upgrade of [version 3](#version-3) that introduces new parameters. It is
only available with Docker Engine version **17.09.0** and higher.
Introduces the following additional parameters:
- [`target`](compose-file-v3.md#target) and [`network`](compose-file-v3.md#network) in
[build configurations](compose-file-v3.md#build)
- `start_period` for [`healthchecks`](compose-file-v3.md#healthcheck)
- `order` for [update configurations](compose-file-v3.md#update_config)
- `name` for [volumes](compose-file-v3.md#volume-configuration-reference)
### Version 3.5
An upgrade of [version 3](#version-3) that introduces new parameters. It is
only available with Docker Engine version **17.12.0** and higher.
Introduces the following additional parameters:
- [`isolation`](compose-file-v3.md#isolation) in service definitions
- `name` for networks, secrets and configs
- `shm_size` in [build configurations](compose-file-v3.md#build)
### Version 3.6
An upgrade of [version 3](#version-3) that introduces new parameters. It is
only available with Docker Engine version **18.02.0** and higher.
Introduces the following additional parameters:
- [`tmpfs` size](compose-file-v3.md#long-syntax-3) for `tmpfs`-type mounts
### Version 3.7
An upgrade of [version 3](#version-3) that introduces new parameters. It is
only available with Docker Engine version **18.06.0** and higher.
Introduces the following additional parameters:
- [`init`](compose-file-v3.md#init) in service definitions
- [`rollback_config`](compose-file-v3.md#rollback_config) in deploy configurations
- Support for extension fields at the root of service, network, volume, secret
and config definitions
### Version 3.8
An upgrade of [version 3](#version-3) that introduces new parameters. It is
only available with Docker Engine version **19.03.0** and higher.
Introduces the following additional parameters:
- [`max_replicas_per_node`](compose-file-v3.md#max_replicas_per_node) in placement
configurations
- `template_driver` option for [config](compose-file-v3.md#configs-configuration-reference)
and [secret](compose-file-v3.md#secrets-configuration-reference) configurations. This
option is only supported when deploying swarm services using
`docker stack deploy`.
- `driver` and `driver_opts` option for [secret](compose-file-v3.md#secrets-configuration-reference)
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
Between versions 2.x and 3.x, the structure of the Compose file is the same, but
several options have been removed:
- `volume_driver`: Instead of setting the volume driver on the service, define
a volume using the
[top-level `volumes` option](compose-file-v3.md#volume-configuration-reference)
and specify the driver there.
version: "3.8"
services:
db:
image: postgres
volumes:
- data:/var/lib/postgresql/data
volumes:
data:
driver: mydriver
- `volumes_from`: To share a volume between services, define it using the
[top-level `volumes` option](compose-file-v3.md#volume-configuration-reference)
and reference it from each service that shares it using the
[service-level `volumes` option](compose-file-v3.md#driver).
- `cpu_shares`, `cpu_quota`, `cpuset`, `mem_limit`, `memswap_limit`: These
have been replaced by the [resources](compose-file-v3.md#resources) key under
`deploy`. `deploy` configuration only takes effect when using
`docker stack deploy`, and is ignored by `docker-compose`.
- `extends`: This option has been removed for `version: "3.x"`
Compose files. (For more information, see [Extending services](../extends.md#extending-services).)
- `group_add`: This option has been removed for `version: "3.x"` Compose files.
- `pids_limit`: This option has not been introduced in `version: "3.x"` Compose files.
- `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:
1. Indent the whole file by one level and put a `services:` key at the top.
2. Add a `version: '2'` line at the top of the file.
It's more complicated if you're using particular configuration features:
- `dockerfile`: This now lives under the `build` key:
build:
context: .
dockerfile: Dockerfile-alternate
- `log_driver`, `log_opt`: These now live under the `logging` key:
logging:
driver: syslog
options:
syslog-address: "tcp://192.168.0.42:123"
- `links` with environment variables: environment variables created by
links, such as `CONTAINERNAME_PORT`, ` 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:
web:
links:
- db
environment:
- DB_PORT=tcp://db:5432
- `external_links`: 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.
Either connect the external container to your app's
[default network](../networking.md), or connect both the external container and
your service's containers to an
[external network](../networking.md#use-a-pre-existing-network).
- `net`: This is now replaced by [network_mode](compose-file-v3.md#network_mode):
net: host -> network_mode: host
net: bridge -> network_mode: bridge
net: none -> network_mode: none
If you're using `net: "container:[service name]"`, you must now use
`network_mode: "service:[service name]"` instead.
net: "container:web" -> network_mode: "service:web"
If you're using `net: "container:[container name/id]"`, the value does not
need to change.
net: "container:cont-name" -> network_mode: "container:cont-name"
net: "container:abc12345" -> network_mode: "container:abc12345"
- `volumes` with named volumes: these must now be explicitly declared in a
top-level `volumes` section of your Compose file. If a service mounts a
named volume called `data`, you must declare a `data` volume in your
top-level `volumes` section. The whole file might look like this:
version: "{{ site.compose_file_v2 }}"
services:
db:
image: postgres
volumes:
- data:/var/lib/postgresql/data
volumes:
data: {}
By default, Compose creates a volume whose name is prefixed with your
project name. If you want it to just be called `data`, declare it as
external:
volumes:
data:
external: true
Reference in New Issue View Git Blame Copy Permalink