diff --git a/_includes/content/compose-matrix.md b/_includes/content/compose-matrix.md index 329b5ae894..3d75427231 100644 --- a/_includes/content/compose-matrix.md +++ b/_includes/content/compose-matrix.md @@ -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+ | diff --git a/compose/compose-file/compose-file-v2.md b/compose/compose-file/compose-file-v2.md index 3537c4c19f..825b57ddc5 100644 --- a/compose/compose-file/compose-file-v2.md +++ b/compose/compose-file/compose-file-v2.md @@ -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 diff --git a/compose/compose-file/compose-versioning.md b/compose/compose-file/compose-versioning.md index 9d5d64ab24..34c8fc0215 100644 --- a/compose/compose-file/compose-versioning.md +++ b/compose/compose-file/compose-versioning.md @@ -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 diff --git a/compose/compose-file/index.md b/compose/compose-file/index.md index 94221828c4..ba99871401 100644 --- a/compose/compose-file/index.md +++ b/compose/compose-file/index.md @@ -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 diff --git a/compose/reference/overview.md b/compose/reference/overview.md index 754aebaac1..af23cbd96c 100644 --- a/compose/reference/overview.md +++ b/compose/reference/overview.md @@ -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 diff --git a/release-notes/docker-compose.md b/release-notes/docker-compose.md index 6c75b6bc9d..0f51741675 100644 --- a/release-notes/docker-compose.md +++ b/release-notes/docker-compose.md @@ -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:` + 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