> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Docker Config Objects
> Explains Docker Swarm Config objects for distributing small read only configuration files to services, why they replace host bind mounts for replicated services, and how to manage them.
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.
## 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:
```bash theme={null}
docker run -v /tmp/nginx.conf:/etc/nginx/nginx.conf nginx
```
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:
```bash theme={null}
docker service create --replicas=4 -v /tmp/nginx.conf:/etc/nginx/nginx.conf nginx
```
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:
```bash theme={null}
docker config create nginx-conf /tmp/nginx.conf
```
2. 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`:
```bash theme={null}
docker service create --replicas=4 --config src=nginx-conf,target=/etc/nginx/nginx.conf nginx
```
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.
| 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:
```bash theme={null}
docker service update --config-rm nginx-conf nginx
```
* Remove the config object (only allowed when no service is using it):
```bash theme={null}
docker config rm nginx-conf
```
* 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:
```bash theme={null}
docker config create nginx-conf-new /tmp/nginx-new.conf
docker service update \
--config-rm nginx-conf \
--config-add src=nginx-conf-new,target=/etc/nginx/nginx.conf \
nginx
```
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
| Action | Command |
| ------------------------------- | ------------------------------------------------------------- |
| Create config | `docker config create ` |
| List configs | `docker config ls` |
| Inspect config | `docker config inspect ` |
| Remove config | `docker config rm ` |
| Attach config to service | `docker service create --config src=,target= ...` |
| Update service to remove config | `docker service update --config-rm ` |
## 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=,target=` to control where the file appears inside the container.
* Configs are available only to Swarm services and must be created from a manager node.
## Links and references
* [Docker Docs — Configs](https://docs.docker.com/engine/swarm/configs/)
* [Docker Docs — Services and Swarm mode](https://docs.docker.com/engine/swarm/)
* [Docker Best Practices](https://docs.docker.com/develop/)