Create a Docker Swarm Config with docker config create

Need to push a settings file into a Swarm without baking it into an image? docker config create does it in one line. You will create a named config from a file or standard input, add labels, inspect the metadata and clean up a disposable test config, in about five minutes if Docker is running and your context points at a Swarm manager.

Before you start

• Manager access. This is a cluster-management operation. You need Docker CLI access to an Engine that is part of a Swarm, and the command must reach a manager node.
• Normal account is enough. A normal Docker client account works if its daemon access is already configured. Use sudo only if your local Docker installation requires it; adding sudo does not turn a worker into a manager.
• Pick an obvious name. The examples use demo-app-settings. Config names are cluster-wide, so choose one that will not collide with an existing object.

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. On a manager, the second command shows Swarm: active; control: true.

• Cannot contact the daemon? Fix the Docker context or daemon access first.
• Control not available? Run the creation command against a manager context.

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 /tmp.

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

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. Any of these stops the command without creating the object:

• Name collision. The name is already taken.
• Missing source file. The path is wrong.
• Non-manager endpoint. You are pointed at a worker.
• Daemon connection problem. Docker cannot be reached.

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 a config from standard input

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

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

Successful output is again a new config ID. A quoted here-document or a carefully quoted printf stops the shell changing the content before Docker receives it.

5. Add labels when they answer a question

Labels are metadata, not content and not access control. Add one with --label key=value; repeat the option for more. This example 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.

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

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

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.