Secrets and Configuration Patterns, Runtime Injection, Environment Risk, Build Secrets, and External Secret Stores: Configuration, Design Choices, and Tradeoffs

1. Start with the decision, not the syntax

“How do I pass a variable?” is often the wrong first question. Ask instead: Is the value sensitive? Which phase needs it? Who issues it? Which exact consumer should read it? How long should it remain valid? What evidence proves rotation or revocation? The resulting mechanism becomes much easier to choose.

2. Environment variable versus mounted file versus provider

3. Build secret versus runtime secret

A dependency-download credential can disappear when the image is finished. A database password is meaningless during image construction and must exist when the application runs. Putting a runtime credential into the build makes every image copy a secret-delivery event; putting a build credential into runtime broadens authority after it is needed.

Use different identities where possible. A package-reader token should not also be a production database administrator token.

4. Static versus short-lived credentials

Static credentials are operationally simple but create long exposure windows. Short-lived credentials reduce the useful lifetime of a leak, especially when the issuer can bind them to an audience, role, workload, or repository. They also demand reliable refresh and clock/provider availability.

A rotation design needs versioned evidence: issuance time, active version, consumer reconciliation time, old-version revocation, and validation that the workload still functions. “We changed the file” is not enough.

5. Compose, Swarm, and external providers are different trust models

Local Compose: a source such as a local file is granted to selected services and mounted as a file. This improves service-level scope but does not turn the local source into encrypted secret storage.

Swarm: the orchestrator manages secret distribution for services. This is relevant to Swarm estates, not a reason to initialize Swarm merely to get a secret API for a local lab.

External manager: a separate security system owns secret material and authorization. Docker usually transports only the workload bootstrap identity, mounted result, or provider integration—not the provider’s policy model itself.

6. Decision table

7. Rollback is identity-aware

Rolling an application image back by digest does not necessarily roll a secret back. That separation is usually good: credentials can rotate independently. But it means incident procedures must define whether an old binary is compatible with the current secret format/provider policy. Record image identity and secret-version identity separately.

8. Performance and reliability tradeoffs

Environment reads and mounted files are local and cheap. Provider API calls introduce network latency and failure modes; caching reduces latency but creates another secret-retention surface. Choose a TTL aligned with credential lifetime and outage tolerance, and never solve provider latency by baking a long-lived secret into an image.

Knowledge check

Official references and version notes

• Docker Build secrets — secret mounts, SSH mounts, Git authentication secrets, file/environment sources, and build-time scope.
• Dockerfile reference — RUN --mount=type=secret, RUN --mount=type=ssh, required, target, ownership, and environment exposure options.
• SecretsUsedInArgOrEnv build check — why Dockerfile ARG/ENV are not secret channels.
• Manage secrets securely in Docker Compose — per-service grants and file-based runtime delivery.
• Compose secrets reference — top-level secret definitions and service consumption.
• Compose environment-variable best practices — configuration precedence and why sensitive data should use secrets.
• Swarm secrets — orchestrator-managed secret semantics, intentionally distinct from local Compose file mounts.
• Docker Engine 29 release notes — current Engine baseline.
• Buildx releases and BuildKit releases — current builder/frontend assumptions.