From d7be7f5ee26f07aac7416ee1729533b04bf75f88 Mon Sep 17 00:00:00 2001 From: Ulysses Souza Date: Thu, 1 Sep 2022 18:43:49 +0200 Subject: [PATCH 1/2] Fix contents of the table with the last updates on precedence Signed-off-by: Ulysses Souza --- compose/envvars-precedence.md | 38 +++++++++++++++++------------------ 1 file changed, 18 insertions(+), 20 deletions(-) diff --git a/compose/envvars-precedence.md b/compose/envvars-precedence.md index 189019f2f1..63265edd20 100644 --- a/compose/envvars-precedence.md +++ b/compose/envvars-precedence.md @@ -15,32 +15,30 @@ The table below provides a quick overview of how interpolation works when using Each row represents a scenario and each column represents a context where you can be setting or passing an environment variable. -| # | `.env` file | `compose.yaml`:`env_file` key | `compose.yaml`:`environment` key | CMD | Image | OS | Resolved as | -|:-:|:--------------------------:|:-----------------------------:|:---------------------------------:|:------------:|:-------------:|:------------:|:-----------------:| -| 1 | `TAG=1.3` | Unset | Unset | Unset | `TAG=1.6` | `TAG=1.4` | `TAG=1.6` | -| 2 | `TAG=1.3` | Unset | Unset | `TAG` | `TAG=1.6` | `TAG=1.4` | `TAG=1.3` | -| 3 | `TAG=$TAG:-1.2` | Unset | Unset | `TAG` | `TAG=1.6` | `TAG=1.4` | `TAG=1.4` | -| 4 | `TAG=$TAG:-1.2` | Unset | Unset | Unset | `TAG=1.6` | `TAG=1.4` | `TAG=1.6` | -| 5 | `TAG=$TAG:-1.2` | Unset | Unset | `TAG` | `TAG=1.6` | Unset | `TAG=1.6` | -| 6 | `TAG=$TAG:-1.2` | Unset | Unset | `TAG=1.5` | `TAG=1.6` | `TAG=1.4` | `TAG=1.5` | -| 7 | `TAG=$TAG:-1.2` | Unset | `TAG` | Unset | `TAG=1.6` | `TAG=1.4` | `TAG=1.4` | -| 8 | `TAG=$TAG:-1.2` | Unset | `TAG=1.7` | `TAG` | `TAG=1.6` | `TAG=1.4` | `TAG=1.7` | -| 9 | `TAG=$TAG:-1.2` | Unset | `TAG=1.7` | `TAG=1.5` | `TAG=1.6` | `TAG=1.4` | `TAG=1.5` | -| 10| `TAG=$TAG:-1.2` | Unset | `TAG` | `TAG` | `TAG=1.6` | `TAG=1.4` | `TAG=1.4` | -| 11| `TAG=$TAG:-1.2` | Unset | `TAG` | `TAG` | `TAG=1.6` | `TAG=1.4` | `TAG=1.4` | -| 12| `TAG=$TAG:-1.2` | `TAG=1.8` | Unset | **`TAG=1.5`** | `TAG=1.6` | `TAG=1.4` | `TAG=1.5` | -| 13| `TAG=$TAG:-1.2` | `TAG=1.8` | **`TAG=1.7`** | `TAG=1.5` | `TAG=1.6` | `TAG=1.4` | `TAG=1.7` | -| 14| Unset |**`TAG=1.8`** | Unset | Unset | `TAG=1.6` | `TAG=1.4` | `TAG=1.8` | -| 15| Unset | Unset | `TAG=1.7` | Unset | `TAG=1.6` | `TAG=1.4` | `TAG=1.4` | -| 16| Unset | Unset | `TAG=1.7` | Unset | `TAG=1.6` | `TAG=1.4` | `TAG=1.4` | +| # | `.env` file | `Host OS` environment | Image | `compose.yaml`:`env_file` key | `compose.yaml`:`environment` key | `run --env` | Resolved as | +|:--:|:-----------------:|:-----------------------:|:-----------:|:-------------------------------:|:----------------------------------:|:-------------:|:-------------:| +| 1 | `TAG=1.3` | `TAG=1.4` | - | - | - | - | - | +| 2 | `TAG=1.3` | `TAG=1.4` |**`TAG=1.5`**| - | - | - | `TAG=1.5` | +| 3 | `TAG=1.3` |**`TAG=1.4`** | `TAG=1.5` | - | - |**`TAG`** | `TAG=1.4` | +| 4 |**`TAG=1.3`** | - | `TAG=1.5` |**`TAG`** | - | - | `TAG=1.3` | +| 5 |**`TAG=1.3`** | - | `TAG=1.5` | - | - |**`TAG`** | `TAG=1.3` | +| 6 | `TAG=1.3` | `TAG=1.4` | `TAG=1.5` | - | - |**`TAG=1.8`** | `TAG=1.8` | +| 7 | `TAG=1.3` |**`TAG=1.4`** | `TAG=1.5` | - |**`TAG`** | - | `TAG=1.4` | +| 8 | `TAG=1.3` |**`TAG=1.4`** | `TAG=1.5` | - | `TAG=1.7` |**`TAG`** | `TAG=1.4` | +| 9 | `TAG=1.3` | `TAG=1.4` | `TAG=1.5` | - | `TAG=1.7` |**`TAG=1.8`** | `TAG=1.8` | +| 10 | `TAG=1.3` |**`TAG=1.4`** | `TAG=1.5` | - |**`TAG`** | - | `TAG=1.4` | +| 11 | `TAG=1.3` | `TAG=1.4` | `TAG=1.5` | `TAG=1.6` | - |**`TAG=1.8`** | `TAG=1.8` | +| 12 | `TAG=1.3` | `TAG=1.4` | `TAG=1.5` | `TAG=1.6` | `TAG=1.7` |**`TAG=1.8`** | `TAG=1.8` | +| 13 | - | `TAG=1.4` | `TAG=1.5` |**`TAG=1.6`** | - | - | `TAG=1.6` | +| 14 | - | `TAG=1.4` | `TAG=1.5` | - |**`TAG=1.7`** | - | `TAG=1.7` | Description for each column: * `.env` file - `.env` file on the project root (or, with higher precedence, the file passed via `docker compose -–env-file `). -* `OS` environment - OS Environment variable +* `Host OS` environment - OS Environment variable * Image - `ENV` directive in the Dockerfile * Compose file - In `env_file` key from the service section in the `compose.yaml`. * Compose file - In `environment` key from the service section in the `compose.yaml`. * Command line - Environmental variable passed via `docker compose run -e `. * Resolved as - This column expresses the result available in the container. -**Note that the "`OS`" has precedence over "`.env` file" column for variable resolution in the other columns.** \ No newline at end of file +**Note that the "`Host OS`" has precedence over "`.env` file" column for variable resolution in the other columns.** From 4e2bd6b7269db630694d092486b16706f33624c1 Mon Sep 17 00:00:00 2001 From: dockertopia Date: Wed, 7 Sep 2022 17:25:12 +0100 Subject: [PATCH 2/2] Integrating feedback from the team --- compose/envvars-precedence.md | 68 +++++++++++++++++++---------------- 1 file changed, 37 insertions(+), 31 deletions(-) diff --git a/compose/envvars-precedence.md b/compose/envvars-precedence.md index 63265edd20..7973b99c72 100644 --- a/compose/envvars-precedence.md +++ b/compose/envvars-precedence.md @@ -1,44 +1,50 @@ --- title: Environment variables precedence -description: Scenario Overview illustrating how environmental variables are resolved in Compose +description: Scenario Overview illustrating how environment variables are resolved in Compose keywords: compose, environment, env file --- ## Order of precedence -1. Passed from the command-line [`docker compose run --env `](../../engine/reference/commandline/compose_run/#options). -2. Passed from/set in `compose.yaml` service's configuration, from the [environment key](../../compose/compose-file/#environment). -3. Passed from/set in `compose.yaml` service's configuration, from the [env_file key](../../compose/compose-file/#env_file). -4. Passed from/set in Container Image in the [ENV directive](../../engine/reference/builder/#env). + +1. Passed from the [`.env` file](../environment-variables/#the-env-file). +2. Set in the Host OS environment. +3. Passed from/set in Container Image in the [ENV directive](../../engine/reference/builder/#env). +4. Passed from/set in `compose.yaml` service's configuration, from the [env_file key](../../compose/compose-file/#env_file). +5. Passed from/set in `compose.yaml` service's configuration, from the [environment key](../../compose/compose-file/#environment). +6. Passed from the command line [`docker compose run --env `](../../engine/reference/commandline/compose_run/#options). ### Precedence quick overview table -The table below provides a quick overview of how interpolation works when using all environment variables on Compose, using `TAG`, an environmental variable defining the version for an image, as an example. +The table below provides a quick overview of how interpolation works when using environment variables on Compose. +This overview is done using `TAG`, an environment variable defining the version for an image, as an example. -Each row represents a scenario and each column represents a context where you can be setting or passing an environment variable. +Each table's: +* column - represents a context from where you can set or pass `TAG`, or environment variables in general. +* row - represents a scenario, this means a combination of contexts where `TAG` is set or passed simultaneously. -| # | `.env` file | `Host OS` environment | Image | `compose.yaml`:`env_file` key | `compose.yaml`:`environment` key | `run --env` | Resolved as | +The last column gives you the final result: how `TAG` is resolved for each scenario according with the precedence rule. + +| # | `.env` file | `Host OS` environment | Image | `compose.yaml`:`env_file` key | `compose.yaml`:`environment` key | `run --env` | RESOLVED AS | |:--:|:-----------------:|:-----------------------:|:-----------:|:-------------------------------:|:----------------------------------:|:-------------:|:-------------:| | 1 | `TAG=1.3` | `TAG=1.4` | - | - | - | - | - | -| 2 | `TAG=1.3` | `TAG=1.4` |**`TAG=1.5`**| - | - | - | `TAG=1.5` | -| 3 | `TAG=1.3` |**`TAG=1.4`** | `TAG=1.5` | - | - |**`TAG`** | `TAG=1.4` | -| 4 |**`TAG=1.3`** | - | `TAG=1.5` |**`TAG`** | - | - | `TAG=1.3` | -| 5 |**`TAG=1.3`** | - | `TAG=1.5` | - | - |**`TAG`** | `TAG=1.3` | -| 6 | `TAG=1.3` | `TAG=1.4` | `TAG=1.5` | - | - |**`TAG=1.8`** | `TAG=1.8` | -| 7 | `TAG=1.3` |**`TAG=1.4`** | `TAG=1.5` | - |**`TAG`** | - | `TAG=1.4` | -| 8 | `TAG=1.3` |**`TAG=1.4`** | `TAG=1.5` | - | `TAG=1.7` |**`TAG`** | `TAG=1.4` | -| 9 | `TAG=1.3` | `TAG=1.4` | `TAG=1.5` | - | `TAG=1.7` |**`TAG=1.8`** | `TAG=1.8` | -| 10 | `TAG=1.3` |**`TAG=1.4`** | `TAG=1.5` | - |**`TAG`** | - | `TAG=1.4` | -| 11 | `TAG=1.3` | `TAG=1.4` | `TAG=1.5` | `TAG=1.6` | - |**`TAG=1.8`** | `TAG=1.8` | -| 12 | `TAG=1.3` | `TAG=1.4` | `TAG=1.5` | `TAG=1.6` | `TAG=1.7` |**`TAG=1.8`** | `TAG=1.8` | -| 13 | - | `TAG=1.4` | `TAG=1.5` |**`TAG=1.6`** | - | - | `TAG=1.6` | -| 14 | - | `TAG=1.4` | `TAG=1.5` | - |**`TAG=1.7`** | - | `TAG=1.7` | +| 2 | `TAG=1.3` | `TAG=1.4` |**`TAG=1.5`**| - | - | - |**`TAG=1.5`** | +| 3 | `TAG=1.3` |**`TAG=1.4`** | `TAG=1.5` | - | - |**`$TAG`** |**`TAG=1.4`** | +| 4 |**`TAG=1.3`** | - | `TAG=1.5` |**`$TAG`** | - | - |**`TAG=1.3`** | +| 5 |**`TAG=1.3`** | - | `TAG=1.5` | - | - |**`$TAG`** |**`TAG=1.3`** | +| 6 | `TAG=1.3` | `TAG=1.4` | `TAG=1.5` | - | - |**`TAG=1.8`** |**`TAG=1.8`** | +| 7 | `TAG=1.3` |**`TAG=1.4`** | `TAG=1.5` | - |**`$TAG`** | - |**`TAG=1.4`** | +| 8 | `TAG=1.3` |**`TAG=1.4`** | `TAG=1.5` | - | `TAG=1.7` |**`$TAG`** |**`TAG=1.4`** | +| 9 | `TAG=1.3` | `TAG=1.4` | `TAG=1.5` | - | `TAG=1.7` |**`TAG=1.8`** |**`TAG=1.8`** | +| 10 | `TAG=1.3` |**`TAG=1.4`** | `TAG=1.5` | - |**`$TAG`** | - |**`TAG=1.4`** | +| 11 | `TAG=1.3` | `TAG=1.4` | `TAG=1.5` | `TAG=1.6` | - |**`TAG=1.8`** |**`TAG=1.8`** | +| 12 | `TAG=1.3` | `TAG=1.4` | `TAG=1.5` | `TAG=1.6` | `TAG=1.7` |**`TAG=1.8`** |**`TAG=1.8`** | +| 13 | - | `TAG=1.4` | `TAG=1.5` |**`TAG=1.6`** | - | - |**`TAG=1.6`** | +| 14 | - | `TAG=1.4` | `TAG=1.5` | - |**`TAG=1.7`** | - |**`TAG=1.7`** | -Description for each column: -* `.env` file - `.env` file on the project root (or, with higher precedence, the file passed via `docker compose -–env-file `). -* `Host OS` environment - OS Environment variable -* Image - `ENV` directive in the Dockerfile -* Compose file - In `env_file` key from the service section in the `compose.yaml`. -* Compose file - In `environment` key from the service section in the `compose.yaml`. -* Command line - Environmental variable passed via `docker compose run -e `. -* Resolved as - This column expresses the result available in the container. - -**Note that the "`Host OS`" has precedence over "`.env` file" column for variable resolution in the other columns.** +Table column's description: +* `.env` file - the `.env` file on the project root. +* `Host OS` environment - the environment where the Docker Engine is running. +* Image - `ENV` directive in the Dockerfile for the image. +* `compose.yaml`:`env_file` key - In `env_file` key from the service section in the `compose.yaml` file. +* `compose.yaml`:`environment` key - In `environment` key from the service section in the `compose.yaml` file. +* `run --env` - environment variable set via the command line: `docker compose run -e `. +* RESOLVED AS - This column expresses the result available in the container. So this column expresses the value of `TAG`, our example in this table, after Compose applies the precedence rule.