Configs & secrets

Docker Swarm - Overview and how to use it

3 min read

Published Jul 13 2025, updated Jul 14 2025

CLIDockerMulti-NodeOrchestrationReplicasServicesStacks

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

Feature	Configs	Secrets
Purpose	Non-sensitive configuration	Sensitive data (passwords, keys)
Encrypted at rest	No	Yes
Encrypted in transit	No	Yes
Visible in API	Yes (plain text)	No (masked)
Mounted path	`/configs/<name>` or custom	`/run/secrets/<name>`
File permissions	Read-only	Read-only (mode 0400)
Availability	Always on container start	Only at runtime

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.