Skip to main content
Let’s explore Docker Config objects in Docker Swarm and why they are a better fit than host bind mounts for distributing configuration files to replicated services.
A dark presentation slide with the title "Docker Config" centered, featuring blue and purple wavy shapes at the bottom and faint circular and container-like graphics in the background.

​
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:
This mounts /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:
This will fail if /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.
  1. Create a config from a manager:
  1. Create the service and attach the config. To place the config at a specific path inside the container (for example, /etc/nginx/nginx.conf), specify src and target:
If you add a config without a 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.

​
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:
This ensures service tasks receive the updated configuration on redeploy.
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

​
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.

Watch Video