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

Document Compose 1.16.0 additions (#4293) 

Signed-off-by: Joffrey F <joffrey@docker.com>
This commit is contained in:
Joffrey F 2017-08-21 15:07:43 -07:00 committed by Misty Stanley-Jones
parent 563c564d4c
commit 0702f23aae
6 changed files with 332 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
_includes/content/compose-matrix.md
View File

@ -2,6 +2,7 @@ This table shows which Compose file versions support specific Docker releases.
| **Compose file format** | **Docker Engine release** |
| ------------------- | ------------------ |
| 3.4 | 17.07.0+ |
| 3.3 | 17.06.0+ |
| 3.2 | 17.04.0+ |
| 3.1 | 1.13.1+ |

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

@ -46,6 +46,64 @@ full details.
This section contains a list of all configuration options supported by a service
definition in version 2.
### blkio_config
A set of configuration options to set block IO limits for this service.
version: '2.2'
services:
foo:
image: busybox
blkio_config:
weight: 300
weight_device:
- path: /dev/sda
weight: 400
device_read_bps:
- path: /dev/sdb
rate: '12mb'
device_read_iops:
- path: /dev/sdb
rate: 120
device_write_bps:
- path: /dev/sdb
rate: '1024k'
device_write_iops:
- path: /dev/sdb
rate: 30
#### device_read_bps, device_write_bps
Set a limit in bytes per second for read / write operations on a given device.
Each item in the list must have two keys:
* `path`, defining the symbolic path to the affected device
* `rate`, either as an integer value representing the number of bytes or as
a string expressing a [byte value](#specifying-byte-values).
#### device_read_iops, device_write_iops
Set a limit in operations per second for read / write operations on a given
device. Each item in the list must have two keys:
* `path`, defining the symbolic path to the affected device
* `rate`, as an integer value representing the permitted number of operations
per second.
#### weight
Modify the proportion of bandwidth allocated to this service relative to other
services. Takes an integer value between 10 and 1000, with 500 being the
default.
#### weight_device
Fine-tune bandwidth allocation by device. Each item in the list must have
two keys:
* `path`, defining the symbolic path to the affected device
* `weight`, an integer value between 10 and 1000
### build
Configuration options that are applied at build time.
@ -182,8 +240,14 @@ build.
> Added in [version 2.3](compose-versioning.md#version-23) file format
Sets the name of the build-stage to build in a
[multi-stage Dockerfile](/engine/userguide/eng-image/multistage-build.md).
Build the specified stage as defined inside the `Dockerfile`. See the
[multi-stage build docs](engine/userguide/eng-image/multistage-build.md) for
details.
build:
context: .
target: prod
### cap_add, cap_drop
@ -546,8 +610,9 @@ for details on how healthchecks work.
interval: 1m30s
timeout: 10s
retries: 3
start_period: 40s
`interval` and `timeout` are specified as
`interval`, `timeout` and `start_period` are specified as
[durations](#specifying-durations).
`test` must be either a string or a list. If it's a list, the first item must be
@ -567,6 +632,9 @@ true`. This is equivalent to specifying `test: ["NONE"]`.
healthcheck:
disable: true
> **Note**: The `start_period` option is a more recent feature and is only
> available with the [2.3 file format](compose-versioning.md#version-23).
### image
Specify the image to start the container from. Can either be a repository/tag or
@ -1071,6 +1139,21 @@ format that looks like this:
The supported units are `us`, `ms`, `s`, `m` and `h`.
## Specifying byte values
Some configuration options, such as the `device_read_bps` sub-option for
[`blkio_config`](#blkioconfig), accept a byte value as a string in a format
that looks like this:
2b
1024kb
2048k
300m
1gb
The supported units are `b`, `k`, `m` and `g`, and their alternative notation `kb`,
`mb` and `gb`. Please note that decimal values are not supported at this time.
## Volume configuration reference
While it is possible to declare volumes on the fly as part of the service
@ -1084,7 +1167,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: "3"
version: "2.2"
services:
db:
@ -1155,6 +1238,9 @@ refer to it within the Compose file:
external:
name: actual-name-of-volume
> **Note**: In newer versions of Compose, the `external.name` property is
> deprecated in favor of simply using the `name` property.
### labels
> [Added in version 2.1 file format](compose-versioning.md#version-21).
@ -1177,6 +1263,25 @@ conflicting with those used by other software.
- "com.example.label-with-empty-value"
### name
> [Added in version 2.1 file format](compose-versioning.md#version-21)
Set a custom name for this volume.
version: '2.1'
volumes:
data:
name: my-app-data
It can also be used in conjuction with the `external` property:
version: '2.1'
volumes:
data:
external: true
name: my-app-data
## Network configuration reference
The top-level `networks` key lets you specify networks to be created. For a full

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

@ -46,7 +46,7 @@ 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.x. This is specified with a `version: '2'` or `version: '2.1'` entry 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, the latest and recommended version, designed to
be cross-compatible between Compose and the Docker Engine's
@ -197,6 +197,7 @@ Introduces the following additional parameters:
- [`isolation`](compose-file-v2.md#isolation)
- `labels` for [volumes](compose-file-v2.md#volume-configuration-reference) and
[networks](compose-file-v2.md#network-configuration-reference)
- `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)
@ -217,12 +218,13 @@ Introduces the following additional parameters:
### Version 2.3
An upgrade of [version 2.2](#version-22) that introduces new parameters only
available with Docker Engine version **17.06+**. Version 2.3 files are
supported by **Compose 17.06+**.
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)
- [`target`](compose-file-v2.md#target) for [build configurations](compose-file-v2.md#build)
- `start_period` for [`healthchecks`](compose-file-v2.md#healthcheck)
### Version 3
@ -249,6 +251,16 @@ Introduces the following additional parameters:
- [`configs`](/compose/compose-file/index.md#configs)
- [deploy `endpoint_mode`](/compose/compose-file/index.md#endpointmode)
### Version 3.4
An upgrade of [version 3](#version-3).
Introduces the following additional parameters:
- [build `target` and `network`](/compose/compose-file/index.md#build)
- `name` for [volumes](compose-file-v2.md#volume-configuration-reference)
- `order` for [`update_config`](/compose/compose-file/index.md#updateconfig) in `deploy`.
## Upgrading
### Version 2.x to 3.x

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

@ -311,6 +311,34 @@ those used by other software.
- "com.example.department=Finance"
- "com.example.label-with-empty-value"
#### network
> **Note:** This option is new in v3.4
Set the network containers will connect to for the `RUN` instructions during
build.
build:
context: .
network: host
build:
context: .
network: custom_network_1
#### target
> **Note:** This option is new in v3.4
Build the specified target as defined inside the `Dockerfile`. See the
[multi-stage build docs](engine/userguide/eng-image/multistage-build.md) for
details.
build:
context: .
target: prod
### cap_add, cap_drop
Add or drop container capabilities.
@ -1865,6 +1893,24 @@ conflicting with those used by other software.
- "com.example.department=IT/Ops"
- "com.example.label-with-empty-value"
### name
> [Added in version 3.4 file format](compose-versioning.md#version-34)
Set a custom name for this volume.
version: '3.4'
volumes:
data:
name: my-app-data
It can also be used in conjuction with the `external` property:
version: '3.4'
volumes:
data:
external: true
name: my-app-data
## Network configuration reference

1
compose/reference/overview.md
View File

@ -24,6 +24,7 @@ Options:
-f, --file FILE Specify an alternate Compose file (default: docker-compose.yml)
-p, --project-name NAME Specify an alternate project name (default: directory name)
--verbose Show more output
--no-ansi Do not print ANSI control characters
-v, --version Print version and exit
-H, --host HOST Daemon socket to connect to

159
release-notes/docker-compose.md
View File

@ -80,6 +80,165 @@ toc_max: 2
### Bugfixes
- Fixed a bug where service's dependencies were being rescaled to their
default scale when running a `docker-compose run` command
- Fixed a bug where `docker-compose rm` with the `--stop` flag was not
behaving properly when provided with a list of services to remove
- Fixed a bug where `cache_from` in the build section would be ignored when
using more than one Compose file.
- Fixed a bug that prevented binding the same port to different IPs when
using more than one Compose file.
- Fixed a bug where override files would not be picked up by Compose if they
had the `.yaml` extension
- Fixed a bug on Windows Engine where networks would be incorrectly flagged
for recreation
- Fixed a bug where services declaring ports would cause crashes on some
versions of Python 3
- Fixed a bug where the output of `docker-compose config` would sometimes
contain invalid port definitions
## 1.16.0 (2017-08-31)
### New features
#### Compose file version 3.4
- Introduced version 3.4 of the `docker-compose.yml` specification.
This version requires to be used with Docker Engine 17.06.0 or above.
#### Compose file version 2.3
- Introduced version 2.3 of the `docker-compose.yml` specification.
This version requires to be used with Docker Engine 17.06.0 or above.
- Added support for the `target` parameter in network configurations
(also available in 3.4)
- Added support for the `start_period` parameter in healthcheck
configurations
#### Compose file version 2.x
- Added support for the `blkio_config` parameter in service definitions
- Added support for setting a custom name in volume definitions using
the `name` parameter (not available for version 2.0)
#### All formats
- Added new CLI flag `--no-ansi` to suppress ANSI control characters in
output
### Bugfixes
- Fixed a bug where nested `extends` instructions weren't resolved
properly, causing "file not found" errors
- Fixed several issues with `.dockerignore` parsing
- Fixed issues where logs of TTY-enabled services were being printed
incorrectly and causing `MemoryError` exceptions
- The `$` character in the output of `docker-compose config` is now
properly escaped
- Fixed a bug where running `docker-compose top` would sometimes fail
with an uncaught exception
- Fixed a bug where `docker-compose pull` with the `--parallel` flag
would return a `0` exit code when failing
- Fixed an issue where keys in `deploy.resources` were not being validated
- Fixed an issue where the `logging` options in the output of
`docker-compose config` would be set to `null`, an invalid value
- Fixed the output of `docker-compose config` when a port definition used
`0` as the value for the published port
## 1.15.0 (2017-07-26)
### New features
#### Compose file version 2.2
- Added support for the `network` parameter in build configurations.
#### Compose file version 2.1 and up
- The `pid` option in a service's definition now supports a `service:<name>`
value.
- Added support for the `storage_opt` parameter in in service definitions.
This option is not available for the v3 format
#### All formats
- Added `--quiet` flag to `docker-compose pull`, suppressing progress output
- Some improvements to CLI output
### Bugfixes
- Volumes specified through the `--volume` flag of `docker-compose run` now
complement volumes declared in the service's defintion instead of replacing
them
- Fixed a bug where using multiple Compose files would unset the scale value
defined inside the Compose file.
- Fixed an issue where the `credHelpers` entries in the `config.json` file
were not being honored by Compose
- Fixed a bug where using multiple Compose files with port declarations
would cause failures in Python 3 environments
- Fixed a bug where some proxy-related options present in the user's
environment would prevent Compose from running
- Fixed an issue where the output of `docker-compose config` would be invalid
if the original file used `Y` or `N` values
- Fixed an issue preventing `up` operations on a previously created stack on
Windows Engine.
## 1.14.0 (2017-06-19)
### New features
#### Compose file version 3.3
- Introduced version 3.3 of the `docker-compose.yml` specification.
This version requires to be used with Docker Engine 17.06.0 or above.
Note: the `credential_spec` and `configs` keys only apply to Swarm services
and will be ignored by Compose
#### Compose file version 2.2
- Added the following parameters in service definitions: `cpu_count`,
`cpu_percent`, `cpus`
#### Compose file version 2.1
- Added support for build labels. This feature is also available in the
2.2 and 3.3 formats.
#### All formats
- Added shorthand `-u` for `--user` flag in `docker-compose exec`
- Differences in labels between the Compose file and remote network
will now print a warning instead of preventing redeployment.
### Bugfixes
- Fixed a bug where service's dependencies were being rescaled to their
default scale when running a `docker-compose run` command