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

Merge pull request #920 from docker/revert-716-compose-file-v3 

Revert "Update Compose file reference for version 3"
This commit is contained in:
Victoria Bialas 2016-12-16 14:41:02 -08:00 committed by GitHub
parent 7f291684ad d0b903fc07
commit c44d528da9
1 changed files with 22 additions and 312 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

334
compose/compose-file.md
View File

@ -30,9 +30,10 @@ full details.
## Service configuration reference
> **Note:** There are several versions of the Compose file format – 1, 2, 2.1
> and 3. For more information, see the [Versioning](compose-file.md#versioning)
> section.
> **Note:** There are several versions of the Compose file format – version 1
> (the legacy format, which does not support volumes or networks) and
> version 2, as well as 2.1 (the most up-to-date). For more information,
> see the [Versioning](compose-file.md#versioning) section.
This section contains a list of all configuration options supported by a service
definition.
@ -186,124 +187,6 @@ Because Docker container names must be unique, you cannot scale a service
beyond 1 container if you have specified a custom name. Attempting to do so
results in an error.
### deploy
> **[Version 3](compose-file.md#version-3) only.**
Specify configuration related to the deployment and running of services. This
only takes effect when deploying to a [swarm](/engine/swarm/index.md) with
[`docker stack deploy`](/engine/reference/commandline/stack_deploy.md), and is
ignored by `docker-compose up` and `docker-compose run`.
deploy:
replicas: 6
update_config:
parallelism: 2
delay: 10s
restart_policy:
condition: on-failure
Several sub-options are available:
#### mode
Either `global` (exactly one container per swarm node) or `replicated` (a
specified number of containers). The default is `replicated`.
mode: global
#### replicas
If the service is `replicated` (which is the default), specify the number of
containers that should be running at any given time.
mode: replicated
replicas: 6
#### placement
Specify placement constraints. For a full description of the syntax and
available types of constraints, see the
[docker service create](engine/reference/commandline/service_create.md#specify-service-constraints-constraint)
documentation.
placement:
constraints:
- node.role == manager
- engine.labels.operatingsystem == ubuntu 14.04
#### update_config
Configures how the service should be updated. Useful for configuring rolling
updates.
- `parallelism`: The number of containers to update at a time.
- `delay`: The time to wait between updating a group of containers.
- `failure_action`: What to do if an update fails. One of `continue` or `pause`
(default: `pause`).
- `monitor`: TODO
- `max_failure_ratio`: TODO
update_config:
parallelism: 2
delay: 10s
#### resources
Configures resource constraints. This replaces the older resource constraint
options in Compose files prior to version 3 (`cpu_shares`, `cpu_quota`,
`cpuset`, `mem_limit`, `memswap_limit`).
resources:
limits:
cpus: '0.001'
memory: 50M
reservations:
cpus: '0.0001'
memory: 20M
#### restart_policy
Configures if and how to restart containers when they exit. Replaces
[`restart`](compose-file.md#restart).
- `condition`: One of `none`, `on-failure` or `any` (default: `any`).
- `delay`: How long to wait between restart attempts, specified as a
[duration](compose-file.md#specifying-durations) (default: 0).
- `max_attempts`: How many times to attempt to restart a container before giving
up (default: never give up).
- `window`: How long to wait before deciding if a restart has succeeded,
specified as a [duration](compose-file.md#specifying-durations) (default:
decide immediately).
restart_policy:
condition: on-failure
delay: 5s
max_attempts: 3
window: 120s
#### labels
Specify labels for the service. These labels will *only* be set on the service,
and *not* on any containers for the service.
version: "3"
services:
web:
image: web
deploy:
labels:
com.example.description: "This label will appear on the web service"
To set labels on containers instead, use the `labels` key outside of `deploy`:
version: "3"
services:
web:
image: web
labels:
com.example.description: "This label will appear on all containers for the web service"
### devices
List of device mappings. Uses the same format as the `--device` docker
@ -537,41 +420,6 @@ Running `id` inside the created container will show that the user belongs to
the `mail` group, which would not have been the case if `group_add` were not
used.
### healthcheck
> [Version 3 file format](compose-file.md#version-3) and up.
Configure a check that's run to determine whether or not containers for this
service are "healthy". See the docs for the
[HEALTHCHECK Dockerfile instruction](/engine/reference/builder.md#healthcheck)
for details on how healthchecks work.
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost"]
interval: 1m30s
timeout: 10s
retries: 3
`interval` and `timeout` are specified as
[durations](compose-file.md#specifying-durations).
`test` must be either a string or a list. If it's a list, the first item must be
either `NONE`, `CMD` or `CMD-SHELL`. If it's a string, it's equivalent to
specifying `CMD-SHELL` followed by that string.
# Hit the local web app
test: ["CMD", "curl", "-f", "http://localhost"]
# As above, but wrapped in /bin/sh. Both forms below are equivalent.
test: ["CMD-SHELL", "curl -f http://localhost && echo 'cool, it works'"]
test: curl -f https://localhost && echo 'cool, it works'
To disable any default healthcheck set by the image, you can use `disable:
true`. This is equivalent to specifying `test: ["NONE"]`.
healthcheck:
disable: true
### image
Specify the image to start the container from. Can either be a repository/tag or
@ -874,19 +722,6 @@ Override the default labeling scheme for each container.
- label:user:USER
- label:role:ROLE
### stop_grace_period
Specify how to long to wait when attempting to stop a container if it doesn't
handle SIGTERM (or whatever stop signal has been specified with
[`stop_signal`](compose-file.md#stop_signal)), before sending SIGKILL. Specified
as a [duration](compose-file.md#specifying-durations).
stop_grace_period: 1s
stop_grace_period: 1m30s
By default, `stop` waits 10 seconds for the container to exit before sending
SIGKILL.
### stop_signal
Sets an alternative signal to stop the container. By default `stop` uses
@ -940,39 +775,20 @@ If you do not use a host path, you may specify a `volume_driver`.
volume_driver: mydriver
There are several things to note, depending on which
[Compose file version](compose-file.md#versioning) you're using:
Note that for [version 2 files](compose-file.md#version-2), this driver
will not apply to named volumes (you should use the `driver` option when
[declaring the volume](compose-file.md#volume-configuration-reference) instead).
For [version 1](compose-file.md#version-1), both named volumes and container volumes will
use the specified driver.
- `volume_driver` is not supported at all in
[version 3](compose-file.md#version-3). Instead of setting the volume driver
on the service, define a volume using the
[top-level `volumes` option](compose-file.md#volume-configuration-reference)
and specify the driver there.
- You can use `volume_driver` in [version 2 files](compose-file.md#version-2),
but it will only apply to anonymous volumes (those specified in the image,
or specified under `volumes` without an explicit named volume or host path).
To configure the driver for a named volume, use the `driver` key under the
entry in the
[top-level `volumes` option](compose-file.md#volume-configuration-reference).
- For [version 1 files](compose-file.md#version-1), both named volumes and
container volumes will use the specified driver.
- No path expansion will be done if you have also specified a `volume_driver`.
For example, if you specify a mapping of `./foo:/data`, the `./foo` part
will be passed straight to the volume driver without being expanded.
> Note: No path expansion will be done if you have also specified a
> `volume_driver`.
See [Docker Volumes](/engine/userguide/dockervolumes.md) and
[Volume Plugins](/engine/extend/plugins_volume.md) for more information.
[Volume Plugins](/engine/extend/plugins_volume.md) for more
### volumes_from
> **Removed in [version 3](compose-file.md#version-3).** The best way to share a
> volume between services is to use the top-level
> [`volumes` option](compose-file.md#version-configuration-reference) to define
> a named volume and reference it from each service's `volumes` list.
Mount all of the volumes from another service or container, optionally
specifying read-only access (``ro``) or read-write (``rw``). If no access level is specified,
then read-write will be used.
@ -994,13 +810,6 @@ then read-write will be used.
### cpu\_shares, cpu\_quota, cpuset, domainname, hostname, ipc, mac\_address, mem\_limit, memswap\_limit, oom_score_adj, privileged, read\_only, restart, shm\_size, stdin\_open, tty, user, working\_dir
> **Note:** Resource constraint options (`cpu_shares`, `cpu_quota`, `cpuset`,
> `mem_limit`, `memswap_limit`) have been removed in
> [version 3](compose-file.md#version-3). You should set resource constraints
> with [deploy.resources](compose-file.md#resources) instead. Note that `deploy`
> configuration only takes effect when using `docker stack deploy`, and is
> ignored by `docker-compose`.
Each of these is a single value, analogous to its
[docker run](/engine/reference/run.md) counterpart.
@ -1034,21 +843,6 @@ Each of these is a single value, analogous to its
> * `oom_score_adj`
## Specifying durations
Some configuration options, such as the `interval` and `timeout` sub-options for
[`healthcheck`](compose-file.md#healthcheck), accept a duration as a string in a
format that looks like this:
2.5s
10s
1m30s
2h32m
5h34m56s
The supported units are `us`, `ms`, `s`, `m` and `h`.
## Volume configuration reference
While it is possible to declare volumes on the fly as part of the service
@ -1058,35 +852,10 @@ easily retrieved and inspected using the docker command line or API.
See the [docker volume](/engine/reference/commandline/volume_create.md)
subcommand documentation for more information.
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: "3"
services:
db:
image: db
volumes:
- data-volume:/var/lib/db
backup:
image: backup-service
volumes:
- data-volume:/var/lib/backup/data
volumes:
data-volume:
An entry under the top-level `volumes` key can be empty, in which case it will
use the default driver configured by the Engine (in most cases, this is the
`local` driver). Optionally, you can configure it with the following keys:
### driver
Specify which volume driver should be used for this volume. Defaults to whatever
driver the Docker Engine has been configured to use, which in most cases is
`local`. If the driver is not available, the Engine will return an error when
`docker-compose up` tries to create the volume.
Specify which volume driver should be used for this volume. Defaults to
`local`. The Docker Engine will return an error if the driver is not available.
driver: foobar
@ -1287,26 +1056,23 @@ refer to it within the Compose file:
## Versioning
There are currently four versions of the Compose file format:
There are currently three versions of the Compose file format:
- Version 1, the legacy format. This is specified by omitting a `version` key at
the root of the YAML.
- Version 2. This is specified with a `version: '2'` entry at the root of the
YAML.
- Version 2.1, an upgrade over version 2 that takes advantage of newer Docker
Engine features. Specify with a `version: '2.1'` entry at the root of
- Version 2, the recommended format. This is specified with a `version: '2'` entry
at the root of the YAML.
- Version 2.1, an upgrade over version 2 that takes advantage of the Docker
Engine's newest features. Specify with a `version: '2.1'` entry at the root of
the YAML.
- Version 3, the latest and recommended version, designed to be cross-compatible
between Compose and the Docker Engine's [swarm mode](/engine/swarm/index.md).
To move your project to a later version, see the
[Upgrading](compose-file.md#upgrading) section.
To move your project from version 1 to 2, see the [Upgrading](compose-file.md#upgrading)
section.
> **Note:** If you're using
> [multiple Compose files](extends.md#different-environments) 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.
> same version - you cannot mix version 1 and 2 in a single project.
Several things differ depending on which version you use:
@ -1330,11 +1096,6 @@ Version 1 files cannot declare named
[volumes](compose-file.md#volume-configuration-reference), [networks](networking.md) or
[build arguments](compose-file.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 will need to use
[links](compose-file.md#links) to enable discovery between containers.
Example:
web:
@ -1362,11 +1123,6 @@ Named [volumes](compose-file.md#volume-configuration-reference) can be declared
`volumes` key, and [networks](compose-file.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.md#links) are largely unnecessary. For more details, see
[Networking in Compose](networking.md).
Simple example:
version: '2'
@ -1421,54 +1177,8 @@ Introduces the following additional parameters:
- `labels` for [volumes](compose-file.md#volume-configuration-reference) and
[networks](compose-file.md#network-configuration-reference)
### Version 3
Designed to be cross-compatible between Compose and the Docker Engine's
[swarm mode](/engine/swarm/index.md), version 3 removes several options and adds
several more.
- Removed: `volume_driver`, `volumes_from`, `cpu_shares`, `cpu_quota`, `cpuset`,
`mem_limit`, `memswap_limit`. See the [upgrading](compose-file.md#upgrading)
guide for how to migrate away from these.
- Added: [deploy](compose-file.md#deploy),
[healthcheck](compose-file.md#healthcheck),
[stop_grace_period](compose-file.md#stop-grace-period).
### 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.md#volume-configuration-reference)
and specify the driver there.
version: "3"
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.md#volume-configuration-reference)
and reference it from each service that shares it using the
[service-level `volumes` option](compose-file.md#volumes-volume-driver).
- `cpu_shares`, `cpu_quota`, `cpuset`, `mem_limit`, `memswap_limit`: These
have been replaced by the [resources](compose-file.md#resources) key under
`deploy`. Note that `deploy` configuration only takes effect when using
`docker stack deploy`, and is ignored by `docker-compose`.
#### 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.