From a9585d470845fc01ddce4110e1d031a64912073f Mon Sep 17 00:00:00 2001 From: Allie Sadler <102604716+aevesdocker@users.noreply.github.com> Date: Fri, 12 Apr 2024 08:20:08 +0100 Subject: [PATCH] Engdocs 2058 (#19773) * ENGDOCS-2058 * add versioning to spec * add versioning to spec * review edits --- content/compose/compose-file/05-services.md | 39 ++++++++++++------- content/compose/compose-file/08-configs.md | 8 +--- content/compose/compose-file/09-secrets.md | 2 +- content/compose/compose-file/13-merge.md | 2 +- content/compose/compose-file/14-include.md | 2 +- content/compose/compose-file/build.md | 11 +++++- content/compose/file-watch.md | 4 +- .../compose/multiple-compose-files/include.md | 4 +- hugo.yaml | 2 +- 9 files changed, 42 insertions(+), 32 deletions(-) diff --git a/content/compose/compose-file/05-services.md b/content/compose/compose-file/05-services.md index bceae27772..1e58640929 100644 --- a/content/compose/compose-file/05-services.md +++ b/content/compose/compose-file/05-services.md @@ -40,7 +40,7 @@ annotations: ## attach -> Available with Docker Compose version 2.20.0 and later +{{< introduced compose 2.20.0 "../release-notes.md#2200" >}} When `attach` is defined and set to `false` Compose does not collect service logs, until you explicitly request it to. @@ -150,11 +150,11 @@ an integer value using microseconds as unit or a [duration](11-extension.md#spec ## cpus -_DEPRECATED: use [deploy.limits.cpus](deploy.md#cpus)_ - `cpus` define the number of (potentially virtual) CPUs to allocate to service containers. This is a fractional number. `0.000` means no limit. +When set, `cpus` must be consistent with the `cpus` attribute in the [Deploy Specification](deploy.md#cpus). + ## cpuset `cpuset` defines the explicit CPUs in which to allow execution. Can be a range `0-3` or a list `0,1` @@ -181,6 +181,9 @@ cap_drop: ``` ## cgroup + +{{< introduced compose 2.15.0 "../release-notes.md#2150" >}} + `cgroup` specifies the cgroup namespace to join. When unset, it is the container runtime's decision to select which cgroup namespace to use, if supported. @@ -387,7 +390,7 @@ expressed in the short form. - `restart`: When set to `true` Compose restarts this service after it updates the dependency service. This applies to an explicit restart controlled by a Compose operation, and excludes automated restart by the container runtime - after the container dies. + after the container dies. Introduced in Docker Compose version [2.17.0](../release-notes.md#2170). - `condition`: Sets the condition under which dependency is considered satisfied - `service_started`: An equivalent of the short syntax described above @@ -397,7 +400,7 @@ expressed in the short form. - `service_completed_successfully`: Specifies that a dependency is expected to run to successful completion before starting a dependent service. - `required`: When set to `false` Compose only warns you when the dependency service isn't started or available. If it's not defined - the default value of `required` is `true`. + the default value of `required` is `true`. Introduced in Docker Compose version [2.20.0](../release-notes.md#2200). Service dependencies cause the following behaviors: @@ -438,7 +441,7 @@ Compose guarantees dependency services marked with ## develop -> Available with Docker Compose version 2.22.0 and later. +{{< introduced compose 2.22.0 "../release-notes.md#2220" >}} `develop` specifies the development configuration for maintaining a container in sync with source, as defined in the [Development Section](develop.md). @@ -885,7 +888,7 @@ extra_hosts: - "myhostv6=[::1]" ``` -The separator `=` is preferred, but `:` can also be used. For example: +The separator `=` is preferred, but `:` can also be used. Introduced in Docker Compose version [2.24.1](../release-notes.md#2241). For example: ```yml extra_hosts: @@ -947,7 +950,7 @@ healthcheck: start_interval: 5s ``` -`interval`, `timeout`, `start_period`, and `start_interval` are [specified as durations](11-extension.md#specifying-durations). +`interval`, `timeout`, `start_period`, and `start_interval` are [specified as durations](11-extension.md#specifying-durations). Introduced in Docker Compose version [2.20.2](../release-notes.md#2202) `test` defines the command Compose runs to check container health. It can be either a string or a list. If it's a list, the first item must be either `NONE`, `CMD` or `CMD-SHELL`. @@ -1112,11 +1115,15 @@ are platform specific. Driver specific options can be set with `options` as key- ## mem_limit -_DEPRECATED: use [deploy.limits.memory](deploy.md#memory)_ +`mem_limit` configures a limit on the amount of memory a container can allocate, set as a string expressing a [byte value](11-extension.md#specifying-byte-values). + +When set, `mem_limit` must be consistent with the `limits.memory` attribute in the [Deploy Specification](deploy.md#memory). ## mem_reservation -_DEPRECATED: use [deploy.reservations.memory](deploy.md#memory)_ +`mem_reservation` configures a reservation on the amount of memory a container can allocate, set as a string expressing a [byte value](11-extension.md#specifying-byte-values). + +When set, `mem_reservation` must be consistent with the `reservations.memory` attribute in the [Deploy Specification](deploy.md#memory). ## mem_swappiness @@ -1278,6 +1285,8 @@ networks: ### mac_address +{{< introduced compose 2.23.2 "../release-notes.md#2232" >}} + `mac_address` sets the MAC address used by the service container when connecting to this particular network. ### priority @@ -1322,14 +1331,14 @@ Supported values are platform specific. ## pids_limit -_DEPRECATED: use [deploy.resources.limits.pids](deploy.md#pids)_ - `pids_limit` tunes a container’s PIDs limit. Set to -1 for unlimited PIDs. ```yml pids_limit: 10 ``` +When set, `pids_limit` must be consistent with the `pids` attribute in the [Deploy Specification](deploy.md#pids). + ## platform `platform` defines the target platform the containers for the service run on. It uses the `os[/arch[/variant]]` syntax. @@ -1403,7 +1412,7 @@ expressed in the short form. - `published`: The publicly exposed port. It is defined as a string and can be set as a range using syntax `start-end`. It means the actual port is assigned a remaining available port, within the set range. - `host_ip`: The Host IP mapping, unspecified means all network interfaces (`0.0.0.0`). - `protocol`: The port protocol (`tcp` or `udp`). Defaults to `tcp`. -- `app_protocol`: The application procotol (TCP/IP level 4 / OSI level 7) this port is used for. This is optional and can be used as a hint for Compose to offer richer behavior for protocols that it understands. +- `app_protocol`: The application procotol (TCP/IP level 4 / OSI level 7) this port is used for. This is optional and can be used as a hint for Compose to offer richer behavior for protocols that it understands. Introduced in Docker Compose version [2.26.0](../release-notes.md#2260). - `mode`: `host`: For publishing a host port on each node, or `ingress` for a port to be load balanced. Defaults to `ingress`. - `name`: A human-readable name for the port, used to document it's usage within the service. @@ -1698,6 +1707,8 @@ userns_mode: "host" ## uts +{{< introduced compose 2.15.1 "../release-notes.md#2151" >}} + `uts` configures the UTS namespace mode set for the service container. When unspecified it is the runtime's decision to assign a UTS namespace, if supported. Available values are: @@ -1781,7 +1792,7 @@ expressed in the short form. - `nocopy`: Flag to disable copying of data from a container when a volume is created. - `tmpfs`: Configures additional tmpfs options: - `size`: The size for the tmpfs mount in bytes (either numeric or as bytes unit). - - `mode`: The file mode for the tmpfs mount as Unix permission bits as an octal number. + - `mode`: The file mode for the tmpfs mount as Unix permission bits as an octal number. Introduced in Docker Compose version [2.14.0](../release-notes.md#2260). - `consistency`: The consistency requirements of the mount. Available values are platform specific. > **Tip** diff --git a/content/compose/compose-file/08-configs.md b/content/compose/compose-file/08-configs.md index 3162daa8a9..7395726890 100644 --- a/content/compose/compose-file/08-configs.md +++ b/content/compose/compose-file/08-configs.md @@ -17,18 +17,14 @@ By default, the config: The top-level `configs` declaration defines or references configuration data that is granted to services in your Compose application. The source of the config is either `file` or `external`. - `file`: The config is created with the contents of the file at the specified path. -- `environment`: The config content is created with the value of an environment variable. -- `content`: The content is created with the inlined value. +- `environment`: The config content is created with the value of an environment variable. Introduced in Docker Compose version [2.23.1](../release-notes.md#2231). +- `content`: The content is created with the inlined value. Introduced in Docker Compose version [2.23.1](../release-notes.md#2231). - `external`: If set to true, `external` specifies that this config has already been created. Compose does not attempt to create it, and if it does not exist, an error occurs. - `name`: The name of the config object in the container engine to look up. This field can be used to reference configs that contain special characters. The name is used as is and will **not** be scoped with the project name. -> **Note** -> -> `environment` and `content` attributes are available with Docker Compose version 2.23.1 and later. - ## Example 1 `_http_config` is created when the application is deployed, diff --git a/content/compose/compose-file/09-secrets.md b/content/compose/compose-file/09-secrets.md index b11fef50ab..15eb59141b 100644 --- a/content/compose/compose-file/09-secrets.md +++ b/content/compose/compose-file/09-secrets.md @@ -12,7 +12,7 @@ The top-level `secrets` declaration defines or references sensitive data that is application. The source of the secret is either `file` or `environment`. - `file`: The secret is created with the contents of the file at the specified path. -- `environment`: The secret is created with the value of an environment variable. +- `environment`: The secret is created with the value of an environment variable. ## Example 1 diff --git a/content/compose/compose-file/13-merge.md b/content/compose/compose-file/13-merge.md index 3a160d2198..2c67eb4213 100644 --- a/content/compose/compose-file/13-merge.md +++ b/content/compose/compose-file/13-merge.md @@ -178,7 +178,7 @@ services: ### Replace value -> Available in Docker Compose version 2.24.4 and later +{{< introduced compose 2.24.4 "../release-notes.md#2244" >}} While `!reset` can be used to remove a declaration from a Compose file using an override file, `!override` allows you to fully replace an attribute, bypassing the standard merge rules. A typical example is to fully replace a resource definition, to rely on a distinct model but using the same name. diff --git a/content/compose/compose-file/14-include.md b/content/compose/compose-file/14-include.md index f73e5c1714..a944ab97f6 100644 --- a/content/compose/compose-file/14-include.md +++ b/content/compose/compose-file/14-include.md @@ -4,7 +4,7 @@ description: Learn about include keywords: compose, compose specification, include, compose file reference --- -> Available with Docker Compose version 2.20.0 and later. +{{< introduced compose 2.20.0 "../release-notes.md#2200" >}} A Compose application can declare dependency on another Compose application. This is useful if: - You want to reuse other Compose files. diff --git a/content/compose/compose-file/build.md b/content/compose/compose-file/build.md index fd65413c33..928a17e914 100644 --- a/content/compose/compose-file/build.md +++ b/content/compose/compose-file/build.md @@ -123,6 +123,8 @@ build: ### dockerfile_inline +{{< introduced compose 2.17.0 "../release-notes.md#2170" >}} + `dockerfile_inline` defines the Dockerfile content as an inlined string in a Compose file. When set, the `dockerfile` attribute is not allowed and Compose rejects any Compose file having both set. @@ -245,6 +247,8 @@ Unsupported caches are ignored and don't prevent you from building images. ### additional_contexts +{{< introduced compose 2.17.0 "../release-notes.md#2170" >}} + `additional_contexts` defines a list of named contexts the image builder should use during image build. `additional_contexts` can be a mapping or a list: @@ -295,7 +299,7 @@ extra_hosts: - "myhostv6=[::1]" ``` -The separator `=` is preferred, but `:` can also be used. For example: +The separator `=` is preferred, but `:` can also be used. Introduced in Docker Compose version [2.24.1](../release-notes.md#2241). For example: ```yml extra_hosts: @@ -319,6 +323,8 @@ are platform specific. ### privileged +{{< introduced compose 2.15.0 "../release-notes.md#2" >}} + `privileged` configures the service image to build with elevated privileges. Support and actual impacts are platform specific. ```yml @@ -414,6 +420,7 @@ build: ``` ### secrets + `secrets` grants access to sensitive data defined by [secrets](05-services.md#secrets) on a per-service build basis. Two different syntax variants are supported: the short syntax and the long syntax. @@ -496,7 +503,7 @@ tags: ### ulimits -> Available with Docker Compose version 2.24.0 and later. +{{< introduced compose 2.23.1 "../release-notes.md#2231" >}} `ulimits` overrides the default ulimits for a container. It's specified either as an integer for a single limit or as mapping for soft/hard limits. diff --git a/content/compose/file-watch.md b/content/compose/file-watch.md index 9f8defe5ad..250772e644 100644 --- a/content/compose/file-watch.md +++ b/content/compose/file-watch.md @@ -4,9 +4,7 @@ keywords: compose, file watch, experimental title: Use Compose Watch --- -> **Note** -> -> Compose Watch is available in Docker Compose version 2.22 and later. +{{< introduced compose 2.22.0 "release-notes.md#2220" >}} Use `watch` to automatically update and preview your running Compose services as you edit and save your code. diff --git a/content/compose/multiple-compose-files/include.md b/content/compose/multiple-compose-files/include.md index e53469de0c..8f555379cb 100644 --- a/content/compose/multiple-compose-files/include.md +++ b/content/compose/multiple-compose-files/include.md @@ -4,9 +4,7 @@ keywords: compose, docker, include, compose file title: Include --- -> **Note** -> -> `include` is available in Docker Compose version 2.20.3 and later, and Docker Desktop version 4.22 and later. +{{< introduced compose 2.20.3 "../release-notes.md#2203" >}} With the [`include` top-level element](../compose-file/14-include.md), you can include a separate Compose file directly in your local Compose file. This solves the relative path problem that [`extends`](extends.md) and [merge](merge.md) present. diff --git a/hugo.yaml b/hugo.yaml index 80cbe154a1..2c7a93eced 100644 --- a/hugo.yaml +++ b/hugo.yaml @@ -112,7 +112,7 @@ params: engine: "24.0.0" api: "1.41" desktop: "4.20.0" - compose: "2.20.0" + compose: "2.14.0" scout: "1.0.0" menus: