From 88bb7acbd5b4ad9891f363e9c71a93341950d060 Mon Sep 17 00:00:00 2001 From: Victoria Bialas Date: Thu, 29 Jun 2017 11:57:03 -0700 Subject: [PATCH] expanded on explanation in note re: extends supported versions (#3696) * expanded on explanation in note re: extends supported versions Signed-off-by: Victoria Bialas * copyedits Signed-off-by: Victoria Bialas * x-ref to open issue to bring back extends Signed-off-by: Victoria Bialas * added more x-refs to note on extends Signed-off-by: Victoria Bialas --- compose/compose-file/compose-versioning.md | 12 ++++++---- compose/extends.md | 28 +++++++++++++++------- 2 files changed, 27 insertions(+), 13 deletions(-) diff --git a/compose/compose-file/compose-versioning.md b/compose/compose-file/compose-versioning.md index 686b3669e0..28939c56e2 100644 --- a/compose/compose-file/compose-versioning.md +++ b/compose/compose-file/compose-versioning.md @@ -205,7 +205,7 @@ Introduces the following additional parameters: ### Version 2.2 An upgrade of [version 2.1](#version-21) that introduces new parameters only -available with Docker Engine version **1.13.0+**. Version 2.2 files are +available with Docker Engine version **1.13.0+**. Version 2.2 files are supported by **Compose 1.13.0+**. This version also allows you to specify default scale numbers inside the service's configuration. @@ -220,9 +220,10 @@ 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`, `extends`, `group_add`. See the [upgrading](#upgrading) - guide for how to migrate away from these. +- Removed: `volume_driver`, `volumes_from`, `cpu_shares`, `cpu_quota`, +`cpuset`, `mem_limit`, `memswap_limit`, `extends`, `group_add`. See +the [upgrading](#upgrading) guide for how to migrate away from these. +(For more information on `extends`, please see [Extending services](/compose/extends.md#extending-services).) - Added: [deploy](index.md#deploy) @@ -269,7 +270,8 @@ several options have been removed: `deploy`. Note that `deploy` configuration only takes effect when using `docker stack deploy`, and is ignored by `docker-compose`. -- `extends`: This option has been removed for `version: "3.x"` Compose files. +- `extends`: This option has been removed for `version: "3.x"` +Compose files. (For more information, please see [Extending services](/compose/extends.md#extending-services).) - `group_add`: This option has been removed for `version: "3.x"` Compose files. - `pids_limit`: This option has not been introduced in `version: "3.x"` Compose files. - `link_local_ips` in `networks`: This option has not been introduced in diff --git a/compose/extends.md b/compose/extends.md index 7955b91019..ff25a7c305 100644 --- a/compose/extends.md +++ b/compose/extends.md @@ -163,7 +163,17 @@ backup, include the `docker-compose.admin.yml` as well. ## Extending services -> Up to version 2.1 , version 3.x does not support `extends` yet. +> **Note**: The `extends` keyword is supported in earlier Compose file formats +up to Compose file version 2.1 (see [extends in +v1](/compose/compose-file/compose-file-v1.md#extends) and [extends in +v2](/compose/compose-file/compose-file-v2.md#extends)), but is not supported in +Compose version 3.x. See the [Version 3 +summary](/compose/compose-file/compose-versioning.md#version-3) of keys added +and removed, along with information on [how to +upgrade](/compose/compose-file/compose-versioning.md#upgrading). See +[moby/moby#31101](https://github.com/moby/moby/issues/31101) to follow the +discussion thread on possibility of adding support for `extends` in some form in +future versions. Docker Compose's `extends` keyword enables sharing of common configurations among different files, or even different projects entirely. Extending services @@ -171,12 +181,12 @@ is useful if you have several services that reuse a common set of configuration options. Using `extends` you can define a common set of service options in one place and refer to it from anywhere. -> **Note**: `links`, `volumes_from`, and `depends_on` are never shared between -> services using `extends`. These exceptions exist to avoid -> implicit dependencies—you always define `links` and `volumes_from` -> locally. This ensures dependencies between services are clearly visible when -> reading the current file. Defining these locally also ensures changes to the -> referenced file don't result in breakage. +Keep in mind that `links`, `volumes_from`, and `depends_on` are never shared +between services using `extends`. These exceptions exist to avoid implicit +dependencies; you always define `links` and `volumes_from` locally. This ensures +dependencies between services are clearly visible when reading the current file. +Defining these locally also ensures that changes to the referenced file don't +break anything. ### Understand the extends configuration @@ -288,7 +298,9 @@ replaces the old value. # result command: python otherapp.py -> **Note**: In the case of `build` and `image`, when using +> `build` and `image` in Compose file version 1 +> +> In the case of `build` and `image`, when using > [version 1 of the Compose file format](compose-file.md#version-1), using one > option in the local service causes Compose to discard the other option if it > was defined in the original service.