From fa2fd4f915e2571cce5e1768c0c367d56c8b60f2 Mon Sep 17 00:00:00 2001 From: Dockertopia <103652162+dockertopia@users.noreply.github.com> Date: Tue, 16 Aug 2022 16:48:45 +0100 Subject: [PATCH] Revisiting of Environmental variables precendence (#15396) * Rewriting based on knowledge transfer * Fix and minor edits --- compose/envvars-precedence.md | 66 ++++++++++++++++++----------------- 1 file changed, 34 insertions(+), 32 deletions(-) diff --git a/compose/envvars-precedence.md b/compose/envvars-precedence.md index 45ba8c6fe9..c3dc9537f4 100644 --- a/compose/envvars-precedence.md +++ b/compose/envvars-precedence.md @@ -1,40 +1,42 @@ --- title: Environment variables precedence -description: TODO +description: Scenario Overview illustrating how environmental 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 ENV directive](../../engine/reference/builder/#env). -- Command Line (docker compose run --env https://docs.docker.com/engine/reference/commandline/compose_run/#options) -- Compose File (service::environment section: https://docs.docker.com/compose/compose-file/#environment) -- Compose File (service::env_file section file: https://docs.docker.com/compose/compose-file/#env_file) -- Container Image ENV directive (https://docs.docker.com/engine/reference/builder/#env) +### 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. -When `WHEREAMI` is the variable in case: +Each row represents a scenario and each columns represents a context where you can be setting or passing an environment variable. -| Image (`ENV` directive in Dockerfile) | OS Environment | `.env` file on the project root (or overwrite through `docker compose -–env-file `) | Compose file (`service::env_file`) | Compose file (`service::environment`) | Command line (docker compose run -e ) | RESULT | -|:-------------------------------------:|:-----------------:|:-----------------------------------------------------------------------------------------:|:----------------------------------:|:-----------------------------------------:|:------------------------------------------------:|:------------------------:| -|
Dockerfile
| OS_Env | WHEREAMI=DotEnv_File | | | | Dockerfile | -| Dockerfile | OS_Env | WHEREAMI=
DotEnv_File
| | | WHEREAMI | DotEnv_File | -| Dockerfile |
OS_Env
| WHEREAMI=${WHEREAMI:-DotEnv_File_DefaultValue} | | | WHEREAMI | OS_Env | -|
Dockerfile
| OS_Env | WHEREAMI=${WHEREAMI:-DotEnv_File_DefaultValue} | | | | Dockerfile | -| Dockerfile | | WHEREAMI=${WHEREAMI:-
DotEnv_File_DefaultValue
} | | | WHEREAMI | DotEnv_File_DefaultValue | -| Dockerfile | OS_Env | WHEREAMI=${WHEREAMI:-DotEnv_File_DefaultValue} | | | WHEREAMI=
Command_Line
| Command_Line | -| Dockerfile |
OS_Env
| WHEREAMI=${WHEREAMI:-DotEnv_File_DefaultValue} | | WHEREAMI | | OS_Env | -| Dockerfile | OS_Env | WHEREAMI=${WHEREAMI:-DotEnv_File_DefaultValue} | | WHEREAMI=
Environment_Section
| | Environment_Section | -| Dockerfile | OS_Env | WHEREAMI=${WHEREAMI:-DotEnv_File_DefaultValue} | | WHEREAMI=Environment_Section | WHEREAMI=
Command_Line
| Command_Line | -| Dockerfile |
OS_Env
| WHEREAMI=${WHEREAMI:-DotEnv_File_DefaultValue} | | WHEREAMI=Environment_Section | WHEREAMI | OS_Env | -| Dockerfile | OS_Env | WHEREAMI=${WHEREAMI:-DotEnv_File_DefaultValue} | | WHEREAMI | WHEREAMI=
Command_Line
| Command_Line | -| Dockerfile | OS_Env | | WHEREAMI=Env_File | | WHEREAMI=
Command_Line
| Command_Line | -| Dockerfile | OS_Env | | WHEREAMI=Env_File | WHEREAMI=
Environment_Section
| | Environment_Section | -| Dockerfile | OS_Env | | WHEREAMI=
Env_File
| | | Env_File | -| Dockerfile |
OS_Env
| | | WHEREAMI=${WHEREAMI:-Environment_Section} | | OS_Env | -| Dockerfile |
OS_Env
| WHEREAMI=${WHEREAMI:-DotEnv_File_DefaultValue} | | WHEREAMI=${WHEREAMI:-Environment_Section} | | OS_Env | +| # | `.env` file | `compose.yaml`:`env_file` key | `compose.yaml`:`environment` key | CMD | Image | OS | Resolved as | +|:-:|:--------------------------:|:-----------------------------:|:---------------------------------:|:------------:|:-------------:|:------------:|:-----------------:| +| 1 | `TAG=1.3` | 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 | - | `TAG=1.6` | `TAG=1.4` | `TAG=1.6` | +| 5 | `TAG=$TAG:-1.2` | Unset | Unset | `TAG` | `TAG=1.6` | - | `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` | - | `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` | - | **`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| - |**`TAG=1.8`** | - | - | `TAG=1.6` | `TAG=1.4` | `TAG=1.8` | +| 15| - | - | `TAG=1.7` | - | `TAG=1.6` | `TAG=1.4` | `TAG=1.4` | +| 16| - | - | `TAG=1.7` | - | `TAG=1.6` | `TAG=1.4` | `TAG=1.4` | + +Description for each column: +* Image - `ENV` directive in the Dockerfile +* .env file - `.env` file on the project root (or, with higher precedence, the file passed via `docker compose -–env-file `). +* Command line - environmental variable passed via `docker compose run -e `. +* Compose file - in `environment` key from the service section in the `compose.yaml`. +* Compose file - in `env_file key` from the service section in the `compose.yaml`.