docs: caveat interpolated secrets in structural Compose fields (#1425)

The effective-model read surfaces (Networking, Dossier/Anatomy, Storage,
and Compose Doctor) avoid environment, label, and command values, but
docker compose config resolves any ${VAR} interpolation before the model
is parsed, leaving no provenance. A secret interpolated into a structural
field (a bind path, network name, published port, or extra_hosts entry)
is therefore returned resolved. That value is already readable at the
same stack:read scope through the stack's files, so this documents the
caveat rather than changing behavior.

- Reword the "secret-safe / never shows a secret value" claims on the
  Networking, Dossier, Storage, and Doctor docs pages, and add a
  canonical note to the Environment and Secrets Guardrails page steering
  secrets to environment:/env_file: injection.
- Make the matching code comments honest in effectiveAnatomy,
  composeNetworkInspector, effectiveModel (extra_hosts), and the
  effective-anatomy route.
This commit is contained in:
Anso
2026-06-23 16:58:26 -04:00
committed by GitHub
parent b753d2d5e0
commit 4c47c47a27
9 changed files with 31 additions and 14 deletions
+1 -1
View File
@@ -21,7 +21,7 @@ The top of the tab shows a read-only summary derived live from the stack's curre
| **Env file** | The env file, its variable count, and any referenced `${VAR}` with no value |
| **Source** | Git source when the stack is linked, otherwise local |
Secret values are never read or shown. Only env variable **names** and **counts** appear, exactly as in the Anatomy tab.
Environment and label values are never read or shown: only variable **names** and **counts** appear, exactly as in the Anatomy tab. The one exception is a secret interpolated into a structural fact, such as a published port written as `${DB_PORT}`, which Compose resolves before the facts are read, so its value appears. The same is true of the resolved paths and network names shown on the Storage and Networking tabs. Keep secrets in `environment:` or `env_file:` rather than interpolating them into structural fields. See [Environment and Secrets Guardrails](/features/environment-guardrails).
## Operator notes