Remove a Swarm Config with docker config rm

One typo in docker config rm and a config is gone, with no prompt and no undo. You will remove one or more Swarm configs by name or ID, checking that you have the right object and have recorded enough to recreate it. The examples use Docker CE CLI 29.8.1, installed here as package version 5:29.8.1-1~ubuntu.24.04~noble. The local manual gives the command as docker config rm CONFIG [CONFIG...].

Allow about ten minutes for a config that is already known to be obsolete. You need the Docker CLI and access to a Swarm manager.

Destructive action: Docker does not ask for confirmation, and the command does not provide an undo operation. If a service still needs the data, update that service first and keep a copy of the config content in your deployment source.

1. Confirm the command and the Swarm context

Check the installed client and its syntax before touching the cluster:

$ docker version --format '{{.Client.Version}}'
29.8.1
$ docker config rm --help
Usage:  docker config rm CONFIG [CONFIG...]

Remove one or more configs

Aliases:
  docker config rm, docker config remove

The command is a Swarm management operation, so run it against a manager node or a Docker context that points to one. A normal Docker CLI command may need sudo on your host, but do not add it automatically. First try the command as your deployment user. If the daemon socket is inaccessible, use the privilege arrangement approved for that host.

Ask Docker which Swarm node role the current endpoint has:

$ docker info --format 'Swarm: {{.Swarm.LocalNodeState}}; control: {{.Swarm.ControlAvailable}}'
Swarm: active; control: true

Checkpoint: the values are host-specific, but you need an active Swarm and a manager-capable endpoint. If the result says the Swarm is inactive or control is unavailable, stop here. Changing Swarm membership is outside this guide.

2. List configs and choose an exact target

List the configs on the current Swarm:

$ docker config ls
ID                          NAME              CREATED        UPDATED
abcdefghijkl               app-settings      3 days ago     3 days ago
mnopqrstuvwxyz              old-app-settings  30 days ago    30 days ago

Your IDs, names and timestamps will differ. A name is a label, not proof that it is the correct generation. Compare the target with the service or stack deployment that owns it. If your automation records config IDs, use the ID from that record to reduce the chance of deleting a similarly named object.

Do not paste an unreviewed value into the command. Shell variables are useful when they make the review visible:

$ CONFIG_TO_REMOVE='old-app-settings'
$ docker config inspect "$CONFIG_TO_REMOVE"
[
    {
        "ID": "mnopqrstuvwxyz",
        "Spec": {
            "Name": "old-app-settings"
        }
    }
]

The full inspection includes the config specification and metadata. Check the ID and name against the change you intend to make. Do not expect the secret or ordinary file content to be printed by this inspection command.

3. Check service references before deleting

A config can be attached to a Swarm service. Before removal, inspect the services that could consume it:

$ docker service ls
ID            NAME          MODE         REPLICAS   IMAGE
serviceid     example-web   replicated   3/3        example/web:stable
$ docker service inspect example-web --format '{{json .Spec.TaskTemplate.ContainerSpec.Configs}}'
[{"ConfigID":"mnopqrstuvwxyz","ConfigName":"old-app-settings","File":{"Name":"/etc/example/settings.conf"}}]

The service list is only a starting point. Repeat the inspection for each candidate service, or inspect the rendered stack configuration used by your deployment tooling. A config reference may be expressed by ID or name, and the output is compact JSON, so search for both the exact ID and exact name.

Warning: if a service still references the config, do not remove it as a clean-up shortcut. Deploy the replacement config and update the service to use it, then verify the service has converged.

The exact update command depends on how the service was deployed. Keep the previous config until the new tasks are healthy and your rollback plan no longer needs it.

4. Save recovery information

Docker config removal is not reversible through docker config rm. Before the deletion, save the configuration in the source repository or deployment secret store that normally creates it.

Warning: do not put sensitive values in shell history, a ticket or a paste service. Docker Swarm configs are intended for non-sensitive configuration; credentials belong in Docker secrets or the equivalent approved secret system.

Also record the target's name, ID, labels and the file name or mount target used by its consumers. If your deployment source can recreate the object, test that its creation process preserves the name and expected content before deleting the old object. There is no rollback command that can recover content from an ID after removal.

Run the inspection once more immediately before removal and compare the ID with your change record:

$ docker config inspect "$CONFIG_TO_REMOVE" --format '{{.ID}} {{.Spec.Name}}'
mnopqrstuvwxyz old-app-settings

Checkpoint: the ID printed matches the one in your change record.

5. Remove one or more configs

Once the target is approved, remove it by its exact name or ID:

$ docker config rm "$CONFIG_TO_REMOVE"
mnopqrstuvwxyz

A successful command prints the removed config ID. It does not prompt, so a typo or an over-broad list is not protected by an interactive question. For several already-reviewed objects, pass each exact target as a separate argument:

$ docker config rm old-app-settings retired-web-settings
mnopqrstuvwxyz
qrstuvwxyzab

Warning: do not build that argument list from a broad pipeline, such as every config matching a loose text pattern. Review the output of docker config ls, inspect each target, and paste a short explicit list. The command can affect cluster state even when the objects are unrelated to the service currently in front of you.

6. Verify removal and handle failures

Check that the removed object no longer appears:

$ docker config inspect "$CONFIG_TO_REMOVE"
Error response from daemon: config old-app-settings not found

The wording can vary with the Docker release. The useful result is a non-zero status and a not-found response for the exact object. You can also list the remaining configs:

$ docker config ls --format '{{.ID}} {{.Name}}' | grep -F -- 'old-app-settings' || echo 'config absent'
config absent

Recovery: there is no safe undo for the removed object itself. Recreate it from the retained deployment source, then update services to reference the recreated config. That produces a new object ID even when the name is the same, so redeploy and verify the service tasks instead of relying on the old ID.

Done means