Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 38 ยท Stacks and Deployment

Private Registries and Image Delivery in Swarm

Deliver images to every Swarm node: docker login with --with-registry-auth, pinning digests, a registry service inside the swarm, pull failures and a release flow.

A swarm has no shared image cache. Each node pulls the images its tasks need, on its own, from a registry. If the image sits in a private registry, every node needs credentials; if the tag moves, nodes can disagree about what "1.4" means. This lesson explains how images reach the nodes and how to make that reliable.

Swarm cannot run on this site, so the commands are read-only; the Python blocks are stand-ins that model credentials and digest pinning.

The pull path

When you create or update a service, the manager resolves the image reference (for example myorg/api:1.4) to a digest by asking the registry. It stores myorg/api:1.4@sha256:... in the service spec. Each node that receives a task pulls that exact digest. This is why two nodes cannot silently run different builds of the same tag within one service version.

flowchart LR
  CI["CI build + push"] --> R["Registry"]
  M["Manager<br/>resolves tag to digest"] --> R
  M --> W1["Worker 1 pulls digest"]
  M --> W2["Worker 2 pulls digest"]
  R --> W1
  R --> W2

The manager pins the digest; workers pull it directly from the registry.

Logging in for private images

Terminal
docker login registry.example.com
docker stack deploy -c stack.yml --with-registry-auth shop
docker service create --with-registry-auth --name api registry.example.com/myorg/api:1.4
docker service update --with-registry-auth --image registry.example.com/myorg/api:1.5 api

docker login stores credentials on your machine (in ~/.docker/config.json, possibly via a credential helper). --with-registry-auth copies them into the service specification so workers can pull. Without it, the manager can resolve the tag but workers fail with No such image or pull access denied, and tasks bounce between preparing and rejected.

Two security notes. Use a read-only registry token for deployments, not your personal password; the credential travels with the service. And remember that the auth data is stored in the Raft log, so protect managers as described in Protecting Swarm Secrets. Rotate the token by deploying again with a fresh login and --with-registry-auth.

Digests and tags

Reference Meaning Use
myorg/api:latest Moving tag Avoid in production
myorg/api:1.4.2 Version tag, usually stable Good default
myorg/api@sha256:4f2c... Content address Strongest guarantee; hard to read

Use CI to build, test, tag with the Git commit or version and push. Deploy that tag. Reusing a version tag for different content ("force pushing 1.4") defeats rollback, because the old and new builds then look the same.

A registry inside the swarm

For a lab, or for an isolated site, you can run the open-source registry image as a service:

Terminal
docker service create --name registry --publish published=5000,target=5000 \
  --constraint node.role==manager \
  --mount type=volume,source=regdata,target=/var/lib/registry \
  registry:2

Because of the routing mesh, localhost:5000 works on every node, and Docker treats localhost registries as secure, so no TLS setup is needed for experiments. Pushing is just docker tag myimage localhost:5000/myimage && docker push localhost:5000/myimage. For anything real, add TLS and authentication, and pin the registry to a node with durable storage (a volume on one node is a single point of failure). Most teams use a hosted registry instead.

Typical release flow

  1. CI builds registry.example.com/shop/api:1.5.0 and pushes it.
  2. CI (or you) runs docker stack deploy -c stack.yml -c stack.prod.yml --with-registry-auth shop with TAG=1.5.0.
  3. Swarm resolves the digest, starts new tasks, waits for health, retires old tasks.
  4. If tasks fail to start, docker service ps --no-trunc shop_api shows the pull error.

Troubleshooting pulls

  • pull access denied: missing --with-registry-auth or a token without read access.
  • no such image on one node: a tag that exists in a different registry, or an architecture mismatch (an arm64 node needs a multi-arch image).
  • toomanyrequests: a public registry rate limit; log in or mirror the images.
  • x509 errors: the node does not trust the registry certificate.
  • Disk full: docker system prune on the node, and think about a pull-through cache.

Stand-in: digest pinning and pull access

Python Stand-in: why the manager pins a digest

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Python Stand-in: credentials must reach the workers

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. Why do workers fail to pull a private image although docker login succeeded on your laptop?

    docker login stores credentials locally. --with-registry-auth sends them to the nodes with the service spec.
  2. 2. What does the manager do with an image tag when creating a service?

    Resolving to a digest keeps all tasks of one service version identical.
  3. 3. Which tag habit makes rollback unreliable?

    If a version tag changes content, you can no longer return to the earlier build by name.

Summary

  • Every node pulls images itself; the manager pins the tag to a digest so tasks match.
  • Use --with-registry-auth with a read-only token for private registries.
  • Deploy immutable version tags or digests and never re-push a version.
  • A registry service inside the swarm is fine for labs; use TLS, auth and durable storage for anything real.

Next: Scaling Services Up and Down