Configs & secrets

When running applications in Docker Swarm, configuration management and secure handling of sensitive data become critical. Swarm offers two powerful tools for these needs:

• Configs: For storing configuration data (non-sensitive).
• Secrets: For securely managing sensitive data like API keys, passwords, TLS certificates, etc.

They allow you to externalise configuration, avoid hardcoding, and ensure secure distribution of data to only the services that need them.

What Are Docker Swarm Configs?

Docker configs are intended for non-sensitive configuration data that you want to manage separately from your application code — such as:

• .conf files
• .json or .yaml configs
• HTML files (e.g., custom landing pages)
• Any plain-text content that isn’t private

Configs are versioned and managed by the Swarm manager, and mounted read-only into containers that need them.

How to use configs

Create a Config:

docker config create my-config ./myconfig.conf

This uploads the file to the Swarm manager and stores it under the name my-config.

Use It in a Service:

docker service create \  --name web \  --config source=my-config,target=/etc/myconfig.conf \  nginx

This mounts the config file inside the container at /etc/myconfig.conf.

Inspect a Config:

docker config inspect my-config

List All Configs:

docker config ls

Remove a Config:

docker config rm my-config

Removing a config that’s still in use by a service will fail — you must first remove the service or update it to no longer reference the config.

What Are Docker Swarm Secrets?

Secrets are similar to configs, but designed for sensitive data:

• Database credentials
• TLS private keys
• API tokens
• Encryption keys

Swarm encrypts secrets at rest and in transit, and only makes them available to the container at runtime — never as build-time arguments or environment variables.

How to Use Secrets

Create a Secret:

echo "my-super-secret-password" | docker secret create db_password -

Or create from a file:

docker secret create tls_key ./server.key

Use It in a Service:

docker service create \  --name app \  --secret db_password \  myapp

The secret will be available inside the container under:

/run/secrets/db_password

Secrets are read-only files in that directory and are removed when the container stops.

Inspect a Secret:

docker secret inspect db_password

List All Secrets:

docker secret ls

Remove a Secret:

docker secret rm db_password

Note: You cannot update an existing secret. You must delete and recreate it, then update the service to use the new version.

Secrets vs Configs: Key Differences

Compose File Integration

Both configs and secrets can be used in docker-compose.yml when deploying via Swarm (docker stack deploy).

Example:

version: "3.9"​services:  web:    image: my-web-app    configs:      - source: nginx_conf        target: /etc/nginx/nginx.conf    secrets:      - db_password​configs:  nginx_conf:    external: true​secrets:  db_password:    external: true

Deploy with:

docker stack deploy -c docker-compose.yml mystack

Ensure the configs and secrets exist before deploying the stack (docker config create / docker secret create).

Secret security

• Secrets are only sent to nodes running the relevant service tasks.
• Only tasks that need a secret can access it.
• Stored in-memory, not written to disk.
• Rotating secrets requires creating a new secret and updating services to use the new version.