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

View File

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

View File

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

View File

@ -50,7 +50,7 @@ definition in version 2.
A set of configuration options to set block IO limits for this service.
version: '2.2'
version: "{{ site.compose_file_v2 }}"
services:
foo:
image: busybox
@ -393,7 +393,7 @@ Express dependency between services, which has two effects:
Simple example:
version: '2'
version: "{{ site.compose_file_v2 }}"
services:
web:
build: .
@ -418,7 +418,7 @@ the healthcheck) before starting.
Example:
version: '2.1'
version: "{{ site.compose_file_v2 }}"
services:
web:
build: .
@ -667,7 +667,7 @@ details.
A full example:
```
version: '2'
version: "{{ site.compose_file_v2 }}"
services:
myservice:
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
a custom one.
version: '2.2'
version: "{{ site.compose_file_v2 }}"
services:
web:
image: alpine:latest
init: true
version: '2.2'
version: "{{ site.compose_file_v2 }}"
services:
web:
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.
version: '2'
version: "{{ site.compose_file_v2 }}"
services:
web:
@ -920,7 +920,7 @@ The corresponding network configuration in the [top-level networks section](#net
An example:
version: '2.1'
version: "{{ site.compose_file_v2 }}"
services:
app:
@ -954,7 +954,7 @@ managed by docker (IPAM driver).
Example usage:
version: '2.1'
version: "{{ site.compose_file_v2 }}"
services:
app:
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
`app_net_2`, which uses the default priority value of `0`.
version: '2.3'
version: "{{ site.compose_file_v2 }}"
services:
app:
image: busybox
@ -1216,7 +1216,7 @@ expressed in the short form.
```none
version: "2.3"
version: "{{ site.compose_file_v2 }}"
services:
web:
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
up:
version: "2.2"
version: "{{ site.compose_file_v2 }}"
services:
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
called `data` and mount it into the `db` service's containers.
version: '2'
version: "{{ site.compose_file_v2 }}"
services:
db:
@ -1484,14 +1484,14 @@ conflicting with those used by other software.
Set a custom name for this volume.
version: '2.1'
version: "{{ site.compose_file_v2 }}"
volumes:
data:
name: my-app-data
It can also be used in conjunction with the `external` property:
version: '2.1'
version: "{{ site.compose_file_v2 }}"
volumes:
data:
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`
service's containers to it.
version: '2'
version: "{{ site.compose_file_v2 }}"
services:
proxy:
@ -1644,14 +1644,14 @@ Not supported for version 2 `docker-compose` files. Use
Set a custom name for this network.
version: '2.1'
version: "{{ site.compose_file_v2 }}"
networks:
network1:
name: my-app-net
It can also be used in conjunction with the `external` property:
version: '2.1'
version: "{{ site.compose_file_v2 }}"
networks:
network1:
external: true

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
[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.
@ -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
[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:
version: '2'
version: "{{ site.compose_file_v2 }}"
services:
web:
build: .
@ -136,7 +157,7 @@ Simple example:
A more extended example, defining volumes and networks:
version: '2'
version: "{{ site.compose_file_v2 }}"
services:
web:
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
between services and startup order.
version: '2'
version: "{{ site.compose_file_v2 }}"
services:
web:
build: .
@ -259,6 +280,21 @@ the [upgrading](#upgrading) guide for how to migrate away from these.
- 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
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)
and specify the driver there.
version: "3"
version: "{{ site.compose_file_v3 }}"
services:
db:
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
top-level `volumes` section. The whole file might look like this:
version: '2'
version: "{{ site.compose_file_v2 }}"
services:
db:
image: postgres

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>
<div class="collapse block" id="collapseSample1">
<pre><code>
version: "3"
version: "{{ site.compose_file_v3 }}"
services:
redis:
@ -182,7 +182,7 @@ Configuration options that are applied at build time.
context:
```yaml
version: '3'
version: "{{ site.compose_file_v3 }}"
services:
webapp:
build: ./dir
@ -192,7 +192,7 @@ Or, as an object with the path specified under [context](#context) and
optionally [Dockerfile](#dockerfile) and [args](#args):
```yaml
version: '3'
version: "{{ site.compose_file_v3 }}"
services:
webapp:
build:
@ -447,7 +447,7 @@ the stack deployment fails with a `config not found` error.
> of the compose file format.
```yaml
version: "3.3"
version: "{{ site.compose_file_v3 }}"
services:
redis:
image: redis:latest
@ -489,7 +489,7 @@ to `103`. The `redis` service does not have access to the `my_other_config`
config.
```yaml
version: "3.3"
version: "{{ site.compose_file_v3 }}"
services:
redis:
image: redis:latest
@ -573,7 +573,7 @@ behaviors:
Simple example:
```yaml
version: '3'
version: "{{ site.compose_file_v3 }}"
services:
web:
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`.
```yaml
version: '3'
version: "{{ site.compose_file_v3 }}"
services:
redis:
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.
```yaml
version: "3.3"
version: "{{ site.compose_file_v3 }}"
services:
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.
```yaml
version: "3"
version: "{{ site.compose_file_v3 }}"
services:
web:
image: web
@ -706,7 +706,7 @@ services:
To set labels on containers instead, use the `labels` key outside of `deploy`:
```yaml
version: "3"
version: "{{ site.compose_file_v3 }}"
services:
web:
image: web
@ -724,7 +724,7 @@ in the [swarm](/engine/swarm/) topics.)
```yaml
version: '3'
version: "{{ site.compose_file_v3 }}"
services:
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).
```yaml
version: '3.3'
version: "{{ site.compose_file_v3 }}"
services:
db:
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.
```yaml
version: '3'
version: "{{ site.compose_file_v3 }}"
services:
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).
```yaml
version: '3'
version: "{{ site.compose_file_v3 }}"
services:
redis:
image: redis:alpine
@ -841,7 +841,7 @@ Configures if and how to restart containers when they exit. Replaces
decide immediately).
```yaml
version: "3"
version: "{{ site.compose_file_v3 }}"
services:
redis:
image: redis:alpine
@ -884,7 +884,7 @@ updates.
file format.
```yaml
version: '3.4'
version: "{{ site.compose_file_v3 }}"
services:
vote:
image: dockersamples/examplevotingapp_vote:before
@ -954,7 +954,7 @@ behaviors:
Simple example:
```yaml
version: '3'
version: "{{ site.compose_file_v3 }}"
services:
web:
build: .
@ -986,6 +986,9 @@ Custom DNS servers. Can be a single value or a list.
```yaml
dns: 8.8.8.8
```
```yaml
dns:
- 8.8.8.8
- 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.
```yaml
version: '3.7'
version: "{{ site.compose_file_v3 }}"
services:
web:
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:
```yaml
version: '3.7'
version: "{{ site.compose_file_v3 }}"
services:
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.
```yaml
version: '2'
version: "{{ site.compose_file_v3 }}"
services:
web:
build: ./web
image: "nginx:alpine"
networks:
- new
worker:
build: ./worker
image: "my-worker-image:latest"
networks:
- 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
[top-level networks section](#network-configuration-reference) must have an
`ipam` block with subnet configurations covering each static address. If IPv6
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.
`ipam` block with subnet configurations covering each static address.
> **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:
```yaml
version: '2.1'
version: "{{ site.compose_file_v3 }}"
services:
app:
image: busybox
command: ifconfig
image: nginx:alpine
networks:
app_net:
ipv4_address: 172.16.238.10
@ -1530,15 +1532,11 @@ services:
networks:
app_net:
driver: bridge
enable_ipv6: true
ipam:
driver: default
config:
-
subnet: 172.16.238.0/24
-
subnet: 2001:3984:3989::/64
- subnet: "172.16.238.0/24"
- subnet: "2001:3984:3989::/64"
```
### 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.
```yaml
version: "3.1"
version: "{{ site.compose_file_v3 }}"
services:
redis:
image: redis:latest
@ -1685,7 +1683,7 @@ to `103`. The `redis` service does not have access to the `my_other_secret`
secret.
```yaml
version: "3.1"
version: "{{ site.compose_file_v3 }}"
services:
redis:
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.
```yaml
version: "3.2"
version: "{{ site.compose_file_v3 }}"
services:
web:
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)
```yaml
version: "3.2"
version: "{{ site.compose_file_v3 }}"
services:
web:
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:
```yaml
version: "3"
version: "{{ site.compose_file_v3 }}"
services:
db:
image: postgres:9.4
@ -2011,7 +2009,7 @@ are visible on the host.
Here is an example of configuring a volume as `cached`:
```yaml
version: '3'
version: "{{ site.compose_file_v3 }}"
services:
php:
image: php:7.1-fpm
@ -2096,7 +2094,7 @@ shared with another service as a volume so that it can be periodically backed
up:
```yaml
version: "3"
version: "{{ site.compose_file_v3 }}"
services:
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.
```yaml
version: '3'
version: "{{ site.compose_file_v3 }}"
services:
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.
```yaml
version: '3.4'
version: "{{ site.compose_file_v3 }}"
volumes:
data:
name: my-app-data
@ -2236,7 +2234,7 @@ volumes:
It can also be used in conjunction with the `external` property:
```yaml
version: '3.4'
version: "{{ site.compose_file_v3 }}"
volumes:
data:
external: true
@ -2306,7 +2304,7 @@ Docker has already created automatically) and an alias that Compose can use
network using the alias.
```yaml
version: '3.7'
version: "{{ site.compose_file_v3 }}"
services:
web:
networks:
@ -2448,7 +2446,7 @@ looks for an existing network simply called `outside` and connect the `proxy`
service's containers to it.
```yaml
version: '3'
version: "{{ site.compose_file_v3 }}"
services:
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:
```yaml
version: '3.5'
version: "{{ site.compose_file_v3 }}"
networks:
outside:
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.
```yaml
version: '3.5'
version: "{{ site.compose_file_v3 }}"
networks:
network1:
name: my-app-net
@ -2498,7 +2496,7 @@ networks:
It can also be used in conjunction with the `external` property:
```yaml
version: '3.5'
version: "{{ site.compose_file_v3 }}"
networks:
network1:
external: true