Single-host bind mount example
On a single Docker host (not in a Swarm), you can run an NGINX container that uses a custom configuration file by bind-mounting the file from the host into the container:/tmp/nginx.conf from the host into /etc/nginx/nginx.conf inside the container so NGINX uses your custom configuration.
Why bind mounts are problematic in a Swarm
In a Swarm, you deploy services (not standalone containers). If you try to bind-mount a host file into a replicated service, every node that might run a replica must have the file at the same host path. For example:/tmp/nginx.conf exists only on one node. Docker cannot bind-mount a host file that does not exist on the node where a replica gets scheduled. Maintaining identical host paths and files across many nodes is error-prone and fragile.
Use Docker Config objects to distribute configuration
Docker Configs are designed to distribute small, mostly static configuration files across the Swarm. Create the config on a manager node (the contents are stored in the Swarm and propagated to worker nodes), then attach it to services.- Create a config from a manager:
- Create the service and attach the config. To place the config at a specific path inside the container (for example,
/etc/nginx/nginx.conf), specifysrcandtarget:
target, Docker will create a file at the container root named after the config (for example, /nginx-conf).
Docker Config objects are a Swarm-only feature and can only be attached to services (not to standalone
docker run containers). Always create configs from a manager node so the Swarm stores and distributes the data to worker nodes.Configs vs volumes
Configs are for small, read-only configuration data that should be injected into service tasks. They are not intended to replace volumes when you need persistent read-write storage.| Resource Type | Best for | Example usage |
|---|---|---|
| Config | Small, static configuration files or secrets (read-only to tasks) | docker config create nginx-conf /tmp/nginx.conf |
| Volume | Persistent read-write storage shared by containers | docker volume create data and --mount source=data,target=/data |
Managing configs and rotating them
Common operations when working with configs:- Detach (remove) a config from a service:
- Remove the config object (only allowed when no service is using it):
- Rotate a config for an existing service: create the new config, then update the service to remove the old config and add the new one in a single update:
You cannot remove a config object while any service is using it. Remove the config from all services first (
--config-rm), then delete the config object (docker config rm). Failing to do so will produce an error.Quick commands reference
| Action | Command |
|---|---|
| Create config | docker config create <name> <file> |
| List configs | docker config ls |
| Inspect config | docker config inspect <name> |
| Remove config | docker config rm <name> |
| Attach config to service | docker service create --config src=<name>,target=<path> ... |
| Update service to remove config | docker service update --config-rm <name> <service> |
Summary
- Bind mounts work on a single host but are brittle in a Swarm because each node must have the same host path and file.
- Docker Configs let you centrally store and distribute configuration files across the Swarm and mount them into service tasks.
- Use
--config src=<name>,target=<path>to control where the file appears inside the container. - Configs are available only to Swarm services and must be created from a manager node.