Create and verify a Docker Swarm config safely

You will create a named Docker Swarm config from a local file or standard input, attach optional labels, inspect the metadata, and remove a disposable test config when you are finished. Allow about five minutes if Docker is already running and the current context points at a Swarm manager.

Before you start

This is a cluster-management operation. You need Docker CLI access to a Docker Engine that is part of a Swarm, and the command must reach a manager node. A normal Docker client account is enough if its access to the daemon is already configured. Use sudo only if your local Docker installation requires it; adding sudo does not turn a worker into a manager.

The examples use the deliberately obvious name demo-app-settings. Config names are cluster-wide, so choose a name that will not collide with an existing object. Do not put passwords, private keys, or other secrets in a config: Docker configs are intended for non-sensitive configuration data, and the content can be exposed to services that are granted access.

1. Check the client and Swarm context

Confirm the installed client version and ask the daemon for its Swarm state. These checks do not create or change a config.

docker version --format '{{.Client.Version}}'
docker info --format 'Swarm: {{.Swarm.LocalNodeState}}; control: {{.Swarm.ControlAvailable}}'

On the machine used for this guide, the client reports Docker 29.8.1. For a manager, the second command should show Swarm: active; control: true. If the command cannot contact the daemon, fix the Docker context or daemon access first. If control is not available, run the creation command against a manager context.

Checkpoint: ready to create

• The client can contact the intended Engine.
• Swarm is active and the target node has manager control.
• The chosen config name is not already in use.

2. Prepare a small configuration file

Keep the source file under your control and review it before uploading it to the Swarm. This example creates a harmless JSON settings file in the current directory.

cat > /tmp/demo-app-settings.json <<'EOF'
{
  "log_level": "info",
  "feature_preview": false
}
EOF
cat /tmp/demo-app-settings.json

Expected output is the same JSON, with the two settings visible. The /tmp path is only for a short-lived demonstration. For a real deployment, use a controlled path with permissions appropriate to the data and remove the local copy when your process permits.

3. Create the config from the file

Pass the new object name first and the source file second. Docker prints the resulting config ID when creation succeeds.

docker config create demo-app-settings /tmp/demo-app-settings.json

Expect a long identifier such as onakdyv307se2tl7nl20anokv, although your ID will differ. A name collision, a missing source file, a non-manager endpoint, or a daemon connection problem stops the command without creating the requested object.

The command stores the file content in the Swarm config. It does not automatically attach that config to a service or restart a service. A service must be created or updated separately with a config attachment.

4. Create one from standard input

Use a single hyphen as the source when another command should provide the content. This is useful for generated, reviewed text that does not need a permanent intermediate file.

printf '%s\n' 'mode=readonly' | docker config create demo-readonly-settings -

Again, successful output is a new config ID. Be careful with shell expansion: a quoted here-document or a carefully quoted printf prevents the shell from changing the content before Docker receives it. Never place an actual secret in shell history merely to avoid creating a temporary file.

5. Add labels when they answer an operational question

Labels are metadata, not content and not access control. Add one with --label key=value; repeat the option for more labels. For example, this records the environment and a revision marker while creating a second config.

docker config create \
  --label env=dev \
  --label revision=2026-09-23 \
  demo-labelled-settings /tmp/demo-app-settings.json

Use labels for filtering and ownership information that is safe to reveal to Docker administrators. Do not use them for credentials. The installed Docker 29.8.1 CLI also exposes --template-driver. The local manpage identifies it as a template driver option, but this guide does not use it because templated configs require a separate service workflow and a driver configured for the target environment.

6. Verify the object and its metadata

List the config by name first. This confirms that the manager accepted the object and shows its ID.

docker config ls --filter name=demo-app-settings

Then inspect the object. The result is a JSON array containing the name, labels, timestamps, and an encoded Data field.

docker config inspect demo-app-settings

Seeing the name in the list and a matching Spec.Name in the inspection output is the useful verification point. The Data value is base64-encoded in the JSON response, not a substitute for encryption. Treat inspection output as sensitive if the config itself is sensitive.

7. Remove only disposable examples

Creation is persistent in the Swarm. Removal is an operational change: services using the config may prevent deletion, and deleting a config is not an undo for a service update. Check the name before removing it.

docker config ls --filter name=demo-readonly-settings
docker config rm demo-readonly-settings

Repeat for demo-app-settings and demo-labelled-settings only if they were created for this exercise and are not attached to anything you need. If a config is in use, leave it in place and inspect the service relationship before changing the service. The local source file can be removed separately once you have confirmed it is no longer needed:

rm -- /tmp/demo-app-settings.json

That final command is irreversible for the local copy. Keep a reviewed source file elsewhere if the configuration is part of a real deployment.

Common traps

• Using a worker: config creation is a manager operation. A worker endpoint is the wrong target even though the Docker CLI itself is installed there.
• Confusing configs with client settings: docker config create creates a Swarm object. It does not edit the CLI's config.json or change the current Docker context.
• Expecting an overwrite: the name must be available. Pick a new name, or deliberately remove and recreate an unused test object after checking dependencies.
• Assuming labels protect data: labels help identify objects; they do not restrict who can inspect a config.
• Testing against the wrong context: check docker context show before inspecting or removing anything when several Engines are configured.