Docker Swarm Secrets: Create, Use and Rotate Credentials

Docker Swarm secrets deliver sensitive runtime data to the services that need it without baking the value into a container image. The important first step is identifying your deployment mode: Swarm secrets, local Docker Compose secrets and build-time secrets are related ideas with different delivery and storage behaviour.

This guide uses an existing authorized Swarm manager and Linux containers. The demonstration creates a disposable value and a test service. Do not initialize a new Swarm on a production host just to try the commands, and do not replace a live application’s credentials with the sample.

1. Choose the right secret mechanism

Context	Use	Important boundary
Swarm service	Docker secrets and explicit service grants.	Encrypted Swarm distribution and storage; runtime access remains sensitive.
Local Compose application	Compose secrets mapped to selected services.	Do not assume the local source file gains Swarm’s encrypted Raft storage.
Image build	BuildKit secret or SSH mounts.	Build-time access is separate from the application’s runtime secret.

In Swarm, secret data is encrypted in transit and in the stored Raft log. Authorized Linux tasks normally receive a file under /run/secrets/. The application must read that file; Docker does not automatically turn it into an environment variable.

A process authorized to use a secret can read it. Protect the application, node and manager access as well as the secret object. Windows-container storage and permission behaviour differs from Linux; consult the platform-specific documentation before applying this example there.

2. Create a disposable demonstration secret

Check that your selected Docker context points to the intended environment and that the node is a Swarm manager:

docker context show
docker info

In a private test directory, create a random local value with restrictive permissions, then add it to Swarm:

umask 077
openssl rand -hex 32 > password-demo.txt
docker secret create app_password_v1 ./password-demo.txt
docker secret ls
docker secret inspect app_password_v1

The inspect command returns metadata, not the original secret value. Keep the source file out of version control and shared logs. For real credentials, use your approved provisioning process and decide how source material is stored and removed under the organization’s data-handling policy.

3. Grant the secret to one test service

This service keeps the secret at a stable application path and checks only whether the file is readable and non-empty. It does not print the value:

docker service create \
  --name secret-demo \
  --user 10001:10001 \
  --secret source=app_password_v1,target=app_password,uid=10001,gid=10001,mode=0400 \
  busybox:1.37.0 \
  sh -c 'test -s /run/secrets/app_password && echo "Secret file available" && sleep 3600'

Use an approved, tested image and digest for a reproducible deployment. In a real service, configure the application to read /run/secrets/app_password. Some images document a _FILE setting, but that is an image convention, not a universal Docker feature.

docker service ps secret-demo
docker service logs secret-demo

Confirm that tasks start and that the expected success message appears. For an application credential, also verify the operation that actually requires authentication. A readable file does not prove that a database accepts its contents.

4. Rotate the value with a new secret version

Swarm secret contents are immutable. Create a new version, then update the service’s grant while keeping the application’s target filename stable:

openssl rand -hex 32 > password-demo-v2.txt
docker secret create app_password_v2 ./password-demo-v2.txt
docker service update \
  --secret-rm app_password_v1 \
  --secret-add source=app_password_v2,target=app_password,uid=10001,gid=10001,mode=0400 \
  secret-demo

This change replaces affected service tasks. Watch rollout status and application health before retiring the previous secret. In a real rotation, coordinate with the database or API that validates the credential. Where supported, an overlap period with two valid credentials can make transition safer.

Keep the old credential valid for the agreed rollback period, then revoke it at its issuing system and remove the unused Swarm object. Removing a secret object does not independently revoke a password that an external service still accepts.

5. Understand Compose and build secrets

In a local Compose project, define a top-level secret and grant it only to the service that needs it. A file-backed source stays a sensitive file on the host. Review its ownership, backup handling and access; the Compose declaration is not an encrypted secret vault.

For a build that needs a package-registry token, use a BuildKit secret mount rather than copying a credential file into the image or using build arguments for the value. The build command can expose a secret for a specific step, but the step must still avoid printing it or writing it into the image output.

6. Troubleshoot the access path

• Unknown secret: check the Docker context, secret name and manager.
• Permission denied: compare the task’s user with the secret UID, GID and mode.
• Application still uses the old credential: inspect service task replacement and application configuration.
• Authentication failure: verify the credential at the issuing system without logging its value.
• Secret cannot be removed: check whether a service still references it.

Clean up the demonstration

Only after confirming these are the test resources you created, remove the service and its unused secrets:

docker service rm secret-demo
docker secret rm app_password_v1 app_password_v2

If task cleanup is still in progress, wait for the references to clear before removing the secret objects. Handle local demonstration files under your normal cleanup process; a generic delete command is not a guarantee of secure erasure on every storage system.

Frequently asked questions

Can a standalone docker run container use Swarm secrets?

Not directly through the Swarm secret mechanism. Choose an appropriate runtime delivery method for that deployment mode rather than assuming the service examples apply unchanged.

Should secrets be stored in environment variables?

Prefer an application-supported secret-file or dedicated secret-provider interface where practical. Whatever mechanism you use, prevent credentials from appearing in images, source control, diagnostics and logs.

Official references and related reading

• Docker Swarm secret lifecycle and platform differences
• docker secret create
• Updating service secret grants
• Docker Compose secrets
• BuildKit secrets
• Docker security best practices