Docker Swarm Config Updates Require Object Replacement

Editing the file originally passed to docker config create does not change an existing Docker Swarm config. The command accepts a file or standard input, but Docker then sends that data to a swarm manager and stores it as a config object in the swarm’s Raft log (Docker Swarm configs; docker config).

The source file is an input, not a synchronization endpoint.

When a service is granted access to the stored config, Docker presents the config as a file inside the service container. Docker documents config data as immutable, so deploying different content requires a new config object and an updated service reference—not another edit to the original file (Docker Swarm configs).

Three separate layers

The lifecycle becomes clearer when you distinguish three things:

1. Source data: The local file or standard input supplied to docker config create.
2. Config object: The independently managed object stored in the swarm.
3. Mounted file: The config content presented inside a service task that has been granted access.

Docker positions Swarm configs as a way to store non-sensitive configuration outside a service image or its running containers. The CLI can create a config from a file or standard input, and the resulting object can then be inspected, listed, attached to services, or removed (Docker Swarm configs; docker config).

Local file or STDIN
        |
        | docker config create
        v
Swarm config object
        |
        | grant service access
        v
File presented inside an authorized task

Editing the local source afterward only changes what could be submitted in a future creation operation. It does not mutate the existing Swarm object. Although the config appears as a file inside a container, that appearance does not turn it into a live link to the original host file.

Why replacement is the update model

Docker documents Swarm configs as immutable: you cannot replace an existing config’s contents with a revised file. Instead, Docker’s rotation procedure creates a new config under a different name, updates the service to use it, and later removes the old object (Docker Swarm configs).

Docker recommends considering a version number or date in config names to make updates and rollbacks easier. Names such as nginx-site-v3 or prometheus-2026-09-19 make each deployed generation explicit. The object name can change while the service maps successive config versions to the same target path inside the container; Docker specifically notes that control over the mount point helps with versioned updates (Docker Swarm configs).

The change crosses two kinds of operation:

• Config commands create and manage the replacement object.
• Service commands control which config objects a service may access.

That separation is why changing the source file alone has no deployment effect. No new config exists, and the service still references the old one.

The complete object lifecycle

INITIAL DEPLOYMENT

Local file or STDIN
        |
        | create
        v
Swarm config: site-v1.conf
        |
        | grant service access
        v
Service specification references site-v1.conf
        |
        | present to authorized task
        v
Config appears as a file in the container


REPLACEMENT

Revised local file or STDIN
        |
        | create
        v
New Swarm config: site-v2.conf
        |
        | update service reference
        v
Service uses site-v2.conf
        |
        | revoke old access
        v
Service no longer references site-v1.conf
        |
        | remove obsolete object
        v
site-v1.conf is deleted

This diagram is an explanatory synthesis of Docker’s documented creation, attachment, rotation, and removal model—not an observed deployment trace.

The order at the end matters. Docker does not allow removal of a config that a running service is using, so the old service reference must be retired before the old object can be deleted (Docker Swarm configs). That constraint also helps expose stale references: an obsolete config cannot simply be removed while a running service still depends on it.

Object commands and service commands

The docker config command group manages the objects themselves:

• docker config create creates a config from a file or standard input.
• docker config inspect displays details about one or more configs.
• docker config ls lists configs.
• docker config rm removes configs.

Service access is managed separately. Docker says a running service can be updated to receive additional configs or have access to a config revoked (Docker Swarm configs). The docker service command group includes service inspection and update operations and must be run on a swarm manager.

A conceptual replacement workflow is therefore:

1. Revise the local source.
2. Create a distinctly named replacement config.
3. Inspect or list the config objects.
4. Update the service to use the replacement and revoke access to the old config.
5. Inspect the service and its tasks as appropriate.
6. Remove the old config after it is no longer referenced.

This sequence does not establish exact rollout timing, task-replacement order, application reload behavior, readiness, or uninterrupted availability. Those details are not specified by the supplied evidence.

Boundaries and alternatives

Swarm configs are for non-sensitive data. They can contain strings or binary content up to 500 KB and are available to Swarm services rather than ordinary standalone containers (Docker Swarm configs).

Docker also identifies bind-mounted configuration files and environment variables as alternatives. A bind mount should not be confused with a Swarm config: the config follows the immutable object lifecycle described above, while Docker presents bind mounting as a separate configuration mechanism. Environment variables can also be used alongside configs (Docker Swarm configs).

Sensitive runtime data belongs in Docker Swarm secrets, not configs. Docker documents secrets as encrypted in transit and at rest in a swarm and accessible only to explicitly authorized services while their tasks are running. Configs and secrets therefore have different intended security roles.

Windows services also implement config mounting differently. Docker does not support config UID, GID, or mode options for Windows containers, so Linux-specific mount and permission details should not be generalized across platforms (Docker Swarm configs).

The practical rule is simple: treat the local file as source material and the Swarm config as a deployed object with its own identity. Editing prepares new content; deployment happens only when you create a replacement and repoint the service.

This is a documentation-based explanation. No deployment test was performed.

Sources and further reading

• https://docs.docker.com/engine/swarm/configs
• https://docs.docker.com/reference/cli/docker/config
• https://docs.docker.com/reference/cli/docker/service
• https://docs.docker.com/engine/swarm/secrets