Docker Secrets explained: setup, best practices & examples

What are Docker secrets and why do they matter?

Docker secrets are encrypted credentials that Docker mounts into containers at runtime without persisting them in image layers. This matters because traditional approaches like environment variables and build arguments (ARG, ENV) embed credentials directly into images, where anyone with access to the image can easily parse it to learn these secrets long after deployment.

Many teams still hard-code database passwords, API tokens, TLS certificates, and SSH keys in Dockerfiles or pass them via environment variables. Both practices are risky. Environment variables appear in process listings and logs. Build arguments become part of the final image.

Docker secrets avoid these problems by encrypting data at rest, restricting access to only the containers that need them, and mounting secrets on a memory-backed filesystem (tmpfs) that disappears when the container stops. Yet secrets alone are not enough. A broader hardening strategy that includes secret scanning and runtime monitoring is the only way to keep your sensitive information safe.

Secrets Security Cheat Sheet: From Sprawl to Control

In this cheat sheet, you’ll learn how the best practices to discover, validate, and protect secrets across your SDLC

La tua email di lavoro qui

Download cheat sheet

How Docker secrets work under the hood

Docker secrets flow through three stages: encrypted storage on Swarm managers, runtime-only decryption, and service-scoped access control.

When an administrator creates a secret using docker secret create, the secret is sent to the swarm manager over mutual TLS (mTLS) and stored in the Raft log, which is encrypted. Swarm managers replicate this log so that secrets remain available if a manager fails.

The secret stays encrypted until a container that references it starts. At that moment, the manager decrypts the secret and mounts it inside the container's memory at /run/secrets/<secret_name>. Only containers that declare the secret in their service definition can access it, and the file is unmounted and removed when the task stops.

When rotating a secret, you create a new secret and update the service to reference it. Docker then updates running services via rolling task replacement, allowing secrets to be rotated without application downtime when configured correctly.

There are some limitations to know about:

• Swarm and Compose only: Docker secrets are not available for standalone docker run commands or Kubernetes workloads. Use an external secret manager for those environments.

• Size limit: Each secret must be smaller than 500 KB.

• No built-in versioning: You manage secret versions manually by creating new secrets and updating service references.

Accademia Wiz

Top Docker Alternatives in 2026: Use Cases and Best Practices

Explore the top Docker alternatives with in-depth comparisons, practical insights, and expert tips for selecting the right container tool for your needs.

Leggi di più

Security benefits of Docker secrets over traditional approaches

Encryption and isolation

Docker secrets are encrypted in transit and at rest in the Raft log, then mounted into a memory-backed filesystem and removed on exit. Environment variables, on the other hand, remain accessible to any user who can inspect the process or container.

Short lifespan

Docker secrets’ runtime-only access means that secrets exist in memory only during the container’s lifetime and aren’t embedded in image layers, unlike hard-coded secrets that persist in images and can be extracted later.

Centralized management and rotation

Docker secrets allow administrators to manage sensitive data centrally through the Swarm API, assign secrets to services, and update them without redeploying containers. This is far more efficient and secure than scattering secrets across scripts, environment variables, and .env files. 

Integration with CI/CD secret scanning 

Docker secrets reduce exposure risks by design, and combining secrets with scanning and runtime monitoring provides a layered defense.

With Docker BuildKit’s --secret mounts, credentials are temporarily mounted for a specific build step (for example, a single RUN instruction), making them available only during that step and preventing them from being written into the final image. Secret scanning tools, such as Wiz Code, inspect Dockerfiles, Git commits, and images to catch hard-coded tokens before they reach production. 

Accademia Wiz

Docker Container Security Best Practices for Modern Applications

Leggi di più

Implementing Docker secrets across different environments

Swarm and Docker Compose secrets

To use a secret in Docker Swarm, first create it: 

printf "mysecret" | docker secret create db_password -

Next, reference it when creating a swarm service: 

docker service create --name backend --secret db_password app:latest

After creating the secret, you can reference the same Docker secret in a docker-compose.yml file. Docker Compose doesn’t create the secret itself; instead, it references an existing Docker Swarm secret and attaches it to the required services: 

services:

  backend:

    image: app:latest

    secrets:

      - db_password

secrets:

  db_password:

    external: true

Compose can reference external secrets or mount secret files for development, but these approaches don’t provide the same security guarantees as Docker Swarm secrets. 

CI/CD pipelines and GitHub Actions

In CI/CD pipelines, you often need credentials to pull private dependencies or push images. BuildKit lets you inject credentials securely: When you run a build with this command, BuildKit mounts the secret file inside /run/secrets during the relevant RUN instruction and removes it afterwards: 

docker build --secret id=mysecret,src=/secretspath 

Remember: You should avoid using ARG or ENV to pass sensitive data, since those mechanisms embed values in the image layers.

On GitHub Actions, you can safely provide repository secrets to BuildKit using the docker/build-push-action and its secrets input. The workflow provides a registry password stored in your repository’s encrypted secrets to BuildKit, allowing the build to authenticate with a private registry or other protected services when pulling base images and, if enabled, pushing the final image.

jobs:

  build:

    steps:

      - uses: docker/setup-buildx-action@v3

      - uses: docker/build-push-action@v6

        with:

          secrets: |

            "docker_password=${{ secrets.DOCKER_PASSWORD }}"

During the build, BuildKit mounts docker_password into the container’s /run/secrets/docker_password only for build steps that explicitly request it and automatically removes it when the build completes. This approach prevents credentials from being baked into image layers while still enabling secure, automated builds.

Docker secrets vs Kubernetes secrets

A common misconception is that Kubernetes Secrets provide the same encryption guarantees as Docker secrets. They do not. By default, Kubernetes stores secrets unencrypted in etcd as Base64-encoded strings, which provides no cryptographic protection. Base64 is encoding, not encryption, and is trivially reversible.

When migrating from Docker Swarm to Kubernetes, teams should create corresponding Secret objects and ensure encryption at rest is enabled and RBAC policies restrict secret access appropriately. Neither is configured securely out of the box.

Watch 12-min demo

See how Wiz integrates container security into the wider cloud ecosystem to isolate critical risks and harden your entire environment from one central platform.

La tua email di lavoro qui

Watch now

Docker secrets security best practices

• Don’t embed secrets in images or code: Avoid hard-coding credentials in images and Git repositories and Dockerfiles. This includes API keys in scripts, credentials in configuration files, and secrets in docker-compose.yml files. A leak discovered after deployment is hard to fix because the secret persists in image layers.  You’ll also want to use secrets or environment variables loaded from external sources. This strategy keeps secrets out of image layers and version control, reducing the risk of long-lived credential exposure.

• Prefer file-based mounts to plain environment variables: Even when secrets are managed correctly, exposing Docker secrets through environment variables can still lead to accidental leakage through logs or process inspection. Docker secret environment variables are often introduced for convenience, but they weaken isolation guarantees and increase the risk of unintended exposure.

• Apply least privilege: Provide each service only the secrets it needs. In Compose, specify secrets on a per-service basis so they aren’t exposed to other containers. In Swarm, use the --secret flag to mount secrets only into tasks that need them. Drop unnecessary Linux capabilities and try to avoid running as root when possible.

• Rotate secrets regularly and update services to use new versions: Regular rotation limits the impact of leaked credentials and ensures services pick up new secrets promptly.

• Remember that standalone containers aren’t protected by Docker secrets: Docker secrets are limited to Swarm services and Compose stacks, so standalone containers require different approaches, such as external secret managers or build-time secret handling.

• Automate scanning and monitoring: Wiz can detect secrets in code and images during builds. Setting up automated scans in your CI/CD pipeline prevents leaks from reaching production.

Accademia Wiz

Kubernetes vs Docker explained: Container orchestration basics

Docker makes it easy to build and run containers, while Kubernetes manages and scales them. Docker provides the tools to build, package, and run applications as self-contained images, and Kubernetes focuses on scheduling, scaling, and healing those containers across clusters of hosts. They address different layers of the stack and work best together.

Leggi di più

Monitoring and detecting secret exposure in containerized environments

Correct storage does not prevent runtime exposure. Secrets can still leak through misconfigurations, compromised workloads, or application bugs that write sensitive data to logs.

Runtime security tools based on eBPF monitor kernel events and generate real-time alerts when suspicious behavior occurs. This allows teams to detect behaviors that may indicate secret misuse as it happens, rather than relying solely on post-incident analysis.

Real-time alerting alone is not enough. Effective detection requires centralized visibility plus context. The best tools provide complete visibility across containers, hosts, and orchestration layers while correlating logs, metrics, and runtime events. With a full understanding of what is happening in real time, security teams can identify and stop anomalous access to secrets before a breach occurs.

How Wiz secures Docker secrets across the development lifecycle

Most secret detection tools find credentials but lack the context to show what an attacker could actually do with them. Wiz connects exposed Docker secrets to their real-world impact by correlating findings with network paths, identities, and data access across your cloud environment.

Wiz Code scans Dockerfiles, container images, IaC templates, and source code repositories to detect hard-coded secrets before they reach production. With over 150 built-in Secret Detection Rules—including specific detection for Docker Swarm Tokens (SECRET-1045)—Wiz catches exposed credentials early and integrates with IDEs, version control systems, and CI/CD pipelines to provide real-time feedback while minimizing false positives.

Wiz uses agentless scanning to inspect container images and running containers, identifying exposed secrets in images, environment variables, configuration files, and mounted volumes. The Wiz Security Graph correlates exposed secrets with network paths, vulnerabilities, identities, and permissions to show what an attacker could realistically access if a secret is compromised, prioritizing truly exploitable risks while reducing alert fatigue.

At runtime, Wiz Defend and the Wiz Sensor monitor process activity and network connections across Docker containers and Kubernetes. When suspicious behavior indicates secret misuse, Wiz detects it in real time and traces exposed secrets back to the originating code, commit, and developer so teams can address root causes rather than symptoms.

Ready to see how Wiz delivers full-lifecycle secret detection and contextual risk analysis for Docker environments? Request a demo today.

See Wiz Container Security in Action

See how teams achieve comprehensive container security without slowing down development. Schedule your personalized demo.

E-mail di lavoro*

Nome di battesimo*

Cognome*

Paese

Numero di telefono*

Società*

Tienimi aggiornato sulle versioni dei prodotti Wiz, sulle novità del settore e sugli eventi (puoi annullare l'iscrizione in qualsiasi momento)

Iscrivimi alle e-mail di riepilogo del blog Wiz

Invia

Per informazioni su come Wiz gestisce i tuoi dati personali, consulta il nostro Informativa sulla privacy.

La tua email di lavoro qui

Richiedi una demo

FAQs about Docker secrets