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

Use site parameter to use latest compose file versions in examples (#8630) 

* Use site parameter to use latest compose file versions in examples

Make sure that examples use the latest version of the compose file
format, to encourage using the latest version, and to prevent
users from running into "not supported by this version" problems
when copy/pasting, and combining examples that use different
versions.

Also add a note about `version: x` not being equivalent to
`version: x.latest`.

Note that there are still some examples using fixed versions
in the UCP sections; we need to evaluate those to make sure
the right (and supported) versions are used for UCP (which may
be different than "latest").

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

* Address some v3/v2 issues, and YAML syntax error

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

* Minor edit

* Final updates

- Added note around v2 and v3 versioning
- Updated note for v3 to match the v2 update
This commit is contained in:
Sebastiaan van Stijn 2019-04-12 15:25:47 +02:00 committed by Maria Bermudez
parent 4616cfeab4
commit e295a6e6cb
5 changed files with 111 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
_config.yml
View File

@ -23,6 +23,8 @@ latest_engine_api_version: "1.39"
docker_ce_version: "18.09" docker_ce_version: "18.09"
docker_ee_version: "18.09" docker_ee_version: "18.09"
compose_version: "1.24.0" compose_version: "1.24.0"
compose_file_v3: "3.7"
compose_file_v2: "2.4"
machine_version: "0.16.0" machine_version: "0.16.0"
distribution_version: "2.6" distribution_version: "2.6"
dtr_version: "2.6" dtr_version: "2.6"

2
_config_authoring.yml
View File

@ -23,6 +23,8 @@ latest_engine_api_version: "1.39"
docker_ce_version: "18.09" docker_ce_version: "18.09"
docker_ee_version: "18.09" docker_ee_version: "18.09"
compose_version: "1.24.0" compose_version: "1.24.0"
compose_file_v3: "3.7"
compose_file_v2: "2.4"
machine_version: "0.16.0" machine_version: "0.16.0"
distribution_version: "2.6" distribution_version: "2.6"
dtr_version: "2.6" dtr_version: "2.6"

36
compose/compose-file/compose-file-v2.md
View File

@ -50,7 +50,7 @@ definition in version 2.
A set of configuration options to set block IO limits for this service. A set of configuration options to set block IO limits for this service.
version: '2.2' version: "{{ site.compose_file_v2 }}"
services: services:
foo: foo:
image: busybox image: busybox
@ -393,7 +393,7 @@ Express dependency between services, which has two effects:
Simple example: Simple example:
version: '2' version: "{{ site.compose_file_v2 }}"
services: services:
web: web:
build: . build: .
@ -418,7 +418,7 @@ the healthcheck) before starting.
Example: Example:
version: '2.1' version: "{{ site.compose_file_v2 }}"
services: services:
web: web:
build: . build: .
@ -667,7 +667,7 @@ details.
A full example: A full example:
``` ```
version: '2' version: "{{ site.compose_file_v2 }}"
services: services:
myservice: myservice:
image: alpine image: alpine
@ -741,14 +741,14 @@ Run an init inside the container that forwards signals and reaps processes.
Either set a boolean value to use the default `init`, or specify a path to Either set a boolean value to use the default `init`, or specify a path to
a custom one. a custom one.
version: '2.2' version: "{{ site.compose_file_v2 }}"
services: services:
web: web:
image: alpine:latest image: alpine:latest
init: true init: true
version: '2.2' version: "{{ site.compose_file_v2 }}"
services: services:
web: web:
image: alpine:latest image: alpine:latest
@ -885,7 +885,7 @@ The general format is shown here.
In the example below, three services are provided (`web`, `worker`, and `db`), along with two networks (`new` and `legacy`). The `db` service is reachable at the hostname `db` or `database` on the `new` network, and at `db` or `mysql` on the `legacy` network. In the example below, three services are provided (`web`, `worker`, and `db`), along with two networks (`new` and `legacy`). The `db` service is reachable at the hostname `db` or `database` on the `new` network, and at `db` or `mysql` on the `legacy` network.
version: '2' version: "{{ site.compose_file_v2 }}"
services: services:
web: web:
@ -920,7 +920,7 @@ The corresponding network configuration in the [top-level networks section](#net
An example: An example:
version: '2.1' version: "{{ site.compose_file_v2 }}"
services: services:
app: app:
@ -954,7 +954,7 @@ managed by docker (IPAM driver).
Example usage: Example usage:
version: '2.1' version: "{{ site.compose_file_v2 }}"
services: services:
app: app:
image: busybox image: busybox
@ -977,7 +977,7 @@ In the following example, the `app` service connects to `app_net_1` first
as it has the highest priority. It then connects to `app_net_3`, then as it has the highest priority. It then connects to `app_net_3`, then
`app_net_2`, which uses the default priority value of `0`. `app_net_2`, which uses the default priority value of `0`.
version: '2.3' version: "{{ site.compose_file_v2 }}"
services: services:
app: app:
image: busybox image: busybox
@ -1216,7 +1216,7 @@ expressed in the short form.
```none ```none
version: "2.3" version: "{{ site.compose_file_v2 }}"
services: services:
web: web:
image: nginx:alpine image: nginx:alpine
@ -1380,7 +1380,7 @@ Here's an example of a two-service setup where a database's data directory is
shared with another service as a volume so that it can be periodically backed shared with another service as a volume so that it can be periodically backed
up: up:
version: "2.2" version: "{{ site.compose_file_v2 }}"
services: services:
db: db:
@ -1433,7 +1433,7 @@ In the example below, instead of attempting to create a volume called
`[projectname]_data`, Compose looks for an existing volume simply `[projectname]_data`, Compose looks for an existing volume simply
called `data` and mount it into the `db` service's containers. called `data` and mount it into the `db` service's containers.
version: '2' version: "{{ site.compose_file_v2 }}"
services: services:
db: db:
@ -1484,14 +1484,14 @@ conflicting with those used by other software.
Set a custom name for this volume. Set a custom name for this volume.
version: '2.1' version: "{{ site.compose_file_v2 }}"
volumes: volumes:
data: data:
name: my-app-data name: my-app-data
It can also be used in conjunction with the `external` property: It can also be used in conjunction with the `external` property:
version: '2.1' version: "{{ site.compose_file_v2 }}"
volumes: volumes:
data: data:
external: true external: true
@ -1609,7 +1609,7 @@ attempting to create a network called `[projectname]_outside`, Compose
looks for an existing network simply called `outside` and connect the `proxy` looks for an existing network simply called `outside` and connect the `proxy`
service's containers to it. service's containers to it.
version: '2' version: "{{ site.compose_file_v2 }}"
services: services:
proxy: proxy:
@ -1644,14 +1644,14 @@ Not supported for version 2 `docker-compose` files. Use
Set a custom name for this network. Set a custom name for this network.
version: '2.1' version: "{{ site.compose_file_v2 }}"
networks: networks:
network1: network1:
name: my-app-net name: my-app-net
It can also be used in conjunction with the `external` property: It can also be used in conjunction with the `external` property:
version: '2.1' version: "{{ site.compose_file_v2 }}"
networks: networks:
network1: network1:
external: true external: true

46
compose/compose-file/compose-versioning.md
View File

@ -52,6 +52,12 @@ omitting a `version` key at the root of the YAML.
be cross-compatible between Compose and the Docker Engine's 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. [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.
> ### v2 and v3 Declaration
>
> **Note**: 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.
The [Compatibility Matrix](#compatibility-matrix) shows Compose file versions mapped to Docker Engine releases. The [Compatibility Matrix](#compatibility-matrix) shows Compose file versions mapped to Docker Engine releases.
@ -121,9 +127,24 @@ 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 [links](compose-file-v2.md#links) are largely unnecessary. For more details, see
[Networking in Compose](compose-file-v2.md#networking.md). [Networking in Compose](compose-file-v2.md#networking.md).
> **Note**: 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: Simple example:
version: '2' version: "{{ site.compose_file_v2 }}"
services: services:
web: web:
build: . build: .
@ -136,7 +157,7 @@ Simple example:
A more extended example, defining volumes and networks: A more extended example, defining volumes and networks:
version: '2' version: "{{ site.compose_file_v2 }}"
services: services:
web: web:
build: . build: .
@ -169,7 +190,7 @@ Several other options were added to support networking, such as:
* The [`depends_on`](compose-file-v2.md#depends_on) option can be used in place of links to indicate dependencies * 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. between services and startup order.
version: '2' version: "{{ site.compose_file_v2 }}"
services: services:
web: web:
build: . build: .
@ -259,6 +280,21 @@ the [upgrading](#upgrading) guide for how to migrate away from these.
- Added: [deploy](/compose/compose-file/index.md#deploy) - Added: [deploy](/compose/compose-file/index.md#deploy)
> **Note**: 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: "3"
> ```
>
> is equivalent to:
>
> ```yaml
> version: "3.0"
> ```
### Version 3.3 ### Version 3.3
An upgrade of [version 3](#version-3) that introduces new parameters only An upgrade of [version 3](#version-3) that introduces new parameters only
@ -327,7 +363,7 @@ several options have been removed:
[top-level `volumes` option](/compose/compose-file/index.md#volume-configuration-reference) [top-level `volumes` option](/compose/compose-file/index.md#volume-configuration-reference)
and specify the driver there. and specify the driver there.
version: "3" version: "{{ site.compose_file_v3 }}"
services: services:
db: db:
image: postgres image: postgres
@ -422,7 +458,7 @@ It's more complicated if you're using particular configuration features:
named volume called `data`, you must declare a `data` volume in your named volume called `data`, you must declare a `data` volume in your
top-level `volumes` section. The whole file might look like this: top-level `volumes` section. The whole file might look like this:
version: '2' version: "{{ site.compose_file_v2 }}"
services: services:
db: db:
image: postgres image: postgres

98
compose/compose-file/index.md
View File

@ -30,7 +30,7 @@ how to upgrade, see **[About versions and upgrading](compose-versioning.md)**.
<i class="chevron fa fa-fw"></i></div> <i class="chevron fa fa-fw"></i></div>
<div class="collapse block" id="collapseSample1"> <div class="collapse block" id="collapseSample1">
<pre><code> <pre><code>
version: "3" version: "{{ site.compose_file_v3 }}"
services: services:
redis: redis:
@ -182,7 +182,7 @@ Configuration options that are applied at build time.
context: context:
```yaml ```yaml
version: '3' version: "{{ site.compose_file_v3 }}"
services: services:
webapp: webapp:
build: ./dir build: ./dir
@ -192,7 +192,7 @@ Or, as an object with the path specified under [context](#context) and
optionally [Dockerfile](#dockerfile) and [args](#args): optionally [Dockerfile](#dockerfile) and [args](#args):
```yaml ```yaml
version: '3' version: "{{ site.compose_file_v3 }}"
services: services:
webapp: webapp:
build: build:
@ -447,7 +447,7 @@ the stack deployment fails with a `config not found` error.
> of the compose file format. > of the compose file format.
```yaml ```yaml
version: "3.3" version: "{{ site.compose_file_v3 }}"
services: services:
redis: redis:
image: redis:latest image: redis:latest
@ -489,7 +489,7 @@ to `103`. The `redis` service does not have access to the `my_other_config`
config. config.
```yaml ```yaml
version: "3.3" version: "{{ site.compose_file_v3 }}"
services: services:
redis: redis:
image: redis:latest image: redis:latest
@ -573,7 +573,7 @@ behaviors:
Simple example: Simple example:
```yaml ```yaml
version: '3' version: "{{ site.compose_file_v3 }}"
services: services:
web: web:
build: . build: .
@ -609,7 +609,7 @@ only takes effect when deploying to a [swarm](/engine/swarm/index.md) with
ignored by `docker-compose up` and `docker-compose run`. ignored by `docker-compose up` and `docker-compose run`.
```yaml ```yaml
version: '3' version: "{{ site.compose_file_v3 }}"
services: services:
redis: redis:
image: redis:alpine image: redis:alpine
@ -645,7 +645,7 @@ in cases where you want to use your own load balancer, or for Hybrid
Windows and Linux applications. Windows and Linux applications.
```yaml ```yaml
version: "3.3" version: "{{ site.compose_file_v3 }}"
services: services:
wordpress: wordpress:
@ -694,7 +694,7 @@ Specify labels for the service. These labels are *only* set on the service,
and *not* on any containers for the service. and *not* on any containers for the service.
```yaml ```yaml
version: "3" version: "{{ site.compose_file_v3 }}"
services: services:
web: web:
image: web image: web
@ -706,7 +706,7 @@ services:
To set labels on containers instead, use the `labels` key outside of `deploy`: To set labels on containers instead, use the `labels` key outside of `deploy`:
```yaml ```yaml
version: "3" version: "{{ site.compose_file_v3 }}"
services: services:
web: web:
image: web image: web
@ -724,7 +724,7 @@ in the [swarm](/engine/swarm/) topics.)
```yaml ```yaml
version: '3' version: "{{ site.compose_file_v3 }}"
services: services:
worker: worker:
image: dockersamples/examplevotingapp_worker image: dockersamples/examplevotingapp_worker
@ -737,7 +737,7 @@ services:
Specify placement of constraints and preferences. See the docker service create documentation for a full description of the syntax and available types of [constraints](/engine/reference/commandline/service_create.md#specify-service-constraints-constraint) and [preferences](/engine/reference/commandline/service_create.md#specify-service-placement-preferences-placement-pref). Specify placement of constraints and preferences. See the docker service create documentation for a full description of the syntax and available types of [constraints](/engine/reference/commandline/service_create.md#specify-service-constraints-constraint) and [preferences](/engine/reference/commandline/service_create.md#specify-service-placement-preferences-placement-pref).
```yaml ```yaml
version: '3.3' version: "{{ site.compose_file_v3 }}"
services: services:
db: db:
image: postgres image: postgres
@ -756,7 +756,7 @@ If the service is `replicated` (which is the default), specify the number of
containers that should be running at any given time. containers that should be running at any given time.
```yaml ```yaml
version: '3' version: "{{ site.compose_file_v3 }}"
services: services:
worker: worker:
image: dockersamples/examplevotingapp_worker image: dockersamples/examplevotingapp_worker
@ -785,7 +785,7 @@ In this general example, the `redis` service is constrained to use no more than
and has `20M` of memory and `0.25` CPU time reserved (as always available to it). and has `20M` of memory and `0.25` CPU time reserved (as always available to it).
```yaml ```yaml
version: '3' version: "{{ site.compose_file_v3 }}"
services: services:
redis: redis:
image: redis:alpine image: redis:alpine
@ -841,7 +841,7 @@ Configures if and how to restart containers when they exit. Replaces
decide immediately). decide immediately).
```yaml ```yaml
version: "3" version: "{{ site.compose_file_v3 }}"
services: services:
redis: redis:
image: redis:alpine image: redis:alpine
@ -884,7 +884,7 @@ updates.
file format. file format.
```yaml ```yaml
version: '3.4' version: "{{ site.compose_file_v3 }}"
services: services:
vote: vote:
image: dockersamples/examplevotingapp_vote:before image: dockersamples/examplevotingapp_vote:before
@ -954,7 +954,7 @@ behaviors:
Simple example: Simple example:
```yaml ```yaml
version: '3' version: "{{ site.compose_file_v3 }}"
services: services:
web: web:
build: . build: .
@ -986,6 +986,9 @@ Custom DNS servers. Can be a single value or a list.
```yaml ```yaml
dns: 8.8.8.8 dns: 8.8.8.8
```
```yaml
dns: dns:
- 8.8.8.8 - 8.8.8.8
- 9.9.9.9 - 9.9.9.9
@ -1256,7 +1259,7 @@ Either set a boolean value to use the default `init`, or specify a path to
a custom one. a custom one.
```yaml ```yaml
version: '3.7' version: "{{ site.compose_file_v3 }}"
services: services:
web: web:
image: alpine:latest image: alpine:latest
@ -1393,7 +1396,7 @@ files are removed to allow storage of new logs.
Here is an example `docker-compose.yml` file that limits logging storage: Here is an example `docker-compose.yml` file that limits logging storage:
```yaml ```yaml
version: '3.7' version: "{{ site.compose_file_v3 }}"
services: services:
some-service: some-service:
image: some-service image: some-service
@ -1474,16 +1477,16 @@ the hostname `db` or `database` on the `new` network, and at `db` or `mysql` on
the `legacy` network. the `legacy` network.
```yaml ```yaml
version: '2' version: "{{ site.compose_file_v3 }}"
services: services:
web: web:
build: ./web image: "nginx:alpine"
networks: networks:
- new - new
worker: worker:
build: ./worker image: "my-worker-image:latest"
networks: networks:
- legacy - legacy
@ -1508,21 +1511,20 @@ Specify a static IP address for containers for this service when joining the net
The corresponding network configuration in the The corresponding network configuration in the
[top-level networks section](#network-configuration-reference) must have an [top-level networks section](#network-configuration-reference) must have an
`ipam` block with subnet configurations covering each static address. If IPv6 `ipam` block with subnet configurations covering each static address.
addressing is desired, the [`enable_ipv6`](#enableipv6) option must be set, and
you must use a version 2.x Compose file, such as the one below.
> **Note**: These options do not currently work in swarm mode. > If IPv6 addressing is desired, the [`enable_ipv6`](compose-file-v2.md##enable_ipv6)
> option must be set, and you must use a [version 2.x Compose file](compose-file-v2.md#ipv4_address-ipv6_address).
> _IPv6 options do not currently work in swarm mode_.
An example: An example:
```yaml ```yaml
version: '2.1' version: "{{ site.compose_file_v3 }}"
services: services:
app: app:
image: busybox image: nginx:alpine
command: ifconfig
networks: networks:
app_net: app_net:
ipv4_address: 172.16.238.10 ipv4_address: 172.16.238.10
@ -1530,15 +1532,11 @@ services:
networks: networks:
app_net: app_net:
driver: bridge
enable_ipv6: true
ipam: ipam:
driver: default driver: default
config: config:
- - subnet: "172.16.238.0/24"
subnet: 172.16.238.0/24 - subnet: "2001:3984:3989::/64"
-
subnet: 2001:3984:3989::/64
``` ```
### pid ### pid
@ -1642,7 +1640,7 @@ command or by another stack deployment. If the external secret does not exist,
the stack deployment fails with a `secret not found` error. the stack deployment fails with a `secret not found` error.
```yaml ```yaml
version: "3.1" version: "{{ site.compose_file_v3 }}"
services: services:
redis: redis:
image: redis:latest image: redis:latest
@ -1685,7 +1683,7 @@ to `103`. The `redis` service does not have access to the `my_other_secret`
secret. secret.
```yaml ```yaml
version: "3.1" version: "{{ site.compose_file_v3 }}"
services: services:
redis: redis:
image: redis:latest image: redis:latest
@ -1850,7 +1848,7 @@ for mounting a named volume. Named volumes must be listed under the top-level
`volumes` key, as shown. `volumes` key, as shown.
```yaml ```yaml
version: "3.2" version: "{{ site.compose_file_v3 }}"
services: services:
web: web:
image: nginx:alpine image: nginx:alpine
@ -1927,7 +1925,7 @@ expressed in the short form.
- `consistency`: the consistency requirements of the mount, one of `consistent` (host and container have identical view), `cached` (read cache, host view is authoritative) or `delegated` (read-write cache, container's view is authoritative) - `consistency`: the consistency requirements of the mount, one of `consistent` (host and container have identical view), `cached` (read cache, host view is authoritative) or `delegated` (read-write cache, container's view is authoritative)
```yaml ```yaml
version: "3.2" version: "{{ site.compose_file_v3 }}"
services: services:
web: web:
image: nginx:alpine image: nginx:alpine
@ -1975,7 +1973,7 @@ configured as a named volume to persist the data on the swarm,
_and_ is constrained to run only on `manager` nodes. Here is the relevant snip-it from that file: _and_ is constrained to run only on `manager` nodes. Here is the relevant snip-it from that file:
```yaml ```yaml
version: "3" version: "{{ site.compose_file_v3 }}"
services: services:
db: db:
image: postgres:9.4 image: postgres:9.4
@ -2011,7 +2009,7 @@ are visible on the host.
Here is an example of configuring a volume as `cached`: Here is an example of configuring a volume as `cached`:
```yaml ```yaml
version: '3' version: "{{ site.compose_file_v3 }}"
services: services:
php: php:
image: php:7.1-fpm image: php:7.1-fpm
@ -2096,7 +2094,7 @@ shared with another service as a volume so that it can be periodically backed
up: up:
```yaml ```yaml
version: "3" version: "{{ site.compose_file_v3 }}"
services: services:
db: db:
@ -2158,7 +2156,7 @@ In the example below, instead of attempting to create a volume called
called `data` and mount it into the `db` service's containers. called `data` and mount it into the `db` service's containers.
```yaml ```yaml
version: '3' version: "{{ site.compose_file_v3 }}"
services: services:
db: db:
@ -2227,7 +2225,7 @@ volumes that contain special characters. The name is used as is
and will **not** be scoped with the stack name. and will **not** be scoped with the stack name.
```yaml ```yaml
version: '3.4' version: "{{ site.compose_file_v3 }}"
volumes: volumes:
data: data:
name: my-app-data name: my-app-data
@ -2236,7 +2234,7 @@ volumes:
It can also be used in conjunction with the `external` property: It can also be used in conjunction with the `external` property:
```yaml ```yaml
version: '3.4' version: "{{ site.compose_file_v3 }}"
volumes: volumes:
data: data:
external: true external: true
@ -2306,7 +2304,7 @@ Docker has already created automatically) and an alias that Compose can use
network using the alias. network using the alias.
```yaml ```yaml
version: '3.7' version: "{{ site.compose_file_v3 }}"
services: services:
web: web:
networks: networks:
@ -2448,7 +2446,7 @@ looks for an existing network simply called `outside` and connect the `proxy`
service's containers to it. service's containers to it.
```yaml ```yaml
version: '3' version: "{{ site.compose_file_v3 }}"
services: services:
proxy: proxy:
@ -2473,7 +2471,7 @@ You can also specify the name of the network separately from the name used to
refer to it within the Compose file: refer to it within the Compose file:
```yaml ```yaml
version: '3.5' version: "{{ site.compose_file_v3 }}"
networks: networks:
outside: outside:
external: external:
@ -2489,7 +2487,7 @@ networks which contain special characters. The name is used as is
and will **not** be scoped with the stack name. and will **not** be scoped with the stack name.
```yaml ```yaml
version: '3.5' version: "{{ site.compose_file_v3 }}"
networks: networks:
network1: network1:
name: my-app-net name: my-app-net
@ -2498,7 +2496,7 @@ networks:
It can also be used in conjunction with the `external` property: It can also be used in conjunction with the `external` property:
```yaml ```yaml
version: '3.5' version: "{{ site.compose_file_v3 }}"
networks: networks:
network1: network1:
external: true external: true