Skip to main content

with-registry-auth

--with-registry-auth no Docker Swarm é a flag que faz o manager enviar as credenciais do registry para os nós do swarm, para que eles consigam dar pull em imagens privadas ao criar ou atualizar serviços. O Docker documenta isso explicitamente para docker service create em registries privados. (Docker Documentation)

Em termos simples​

Sem essa flag:

  • você faz docker login no manager
  • o manager conhece o registry
  • mas os workers podem não conseguir baixar a imagem privada
  • resultado comum: task falha com erro de pull / “no such image” / acesso negado

Com essa flag:

  • o Swarm usa as credenciais autenticadas no manager
  • repassa esse contexto de autenticação para os nós que vão executar as tasks
  • os nós conseguem baixar a imagem privada do registry. (Docker Documentation)

Exemplo​

docker login registry.example.com

docker service create \
  --with-registry-auth \
  --name minha-api \
  registry.example.com/empresa/minha-api:1.0.0

Esse é exatamente o cenário descrito pela documentação oficial para imagem em private registry. (Docker Documentation)

No stack deploy​

A ideia é a mesma quando você usa stack:

docker stack deploy \
  --with-registry-auth \
  -c docker-compose.yml minha-stack

A documentação do docker stack deploy lista a flag como: “Send registry authentication details to Swarm agents”. (Docker Documentation)

Quando usar​

Use --with-registry-auth quando:

  • a imagem está em registry privado
  • você está usando Docker Hub privado, GHCR, GitLab Registry, ECR, ACR, Harbor, etc.
  • o serviço pode rodar em qualquer nó do swarm e esse nó precisa autenticar para baixar a imagem

A própria documentação do Docker Hub diz que, em Docker Swarm, você deve usar --with-registry-auth para autenticar pulls no Hub. (Docker Documentation)

O que ele não faz​

Ele não substitui o docker login.

O fluxo normal é:

  1. fazer docker login
  2. rodar docker service create ... --with-registry-auth ou docker stack deploy ... --with-registry-auth

O login autentica seu cliente no registry; a flag faz o Swarm aproveitar e propagar essas credenciais para os nós. (Docker Documentation)

Resumo curto​

  • docker login = autentica no registry
  • --with-registry-auth = faz o swarm usar e repassar essa autenticação aos nós para puxar a imagem privada

Se quiser, eu posso te mostrar exatamente onde isso entra no seu docker stack deploy da pipeline Azure/DO.