DEV Community

Celso Nery
Celso Nery

Posted on

Kubernetes On-Premise: Criando um Registro de Imagens Docker Local

#kubernetes #k8s #devops #registry

Em clusters Kubernetes on-premise, nem sempre faz sentido depender do Docker Hub (ou de qualquer registro público na nuvem) para armazenar as imagens das aplicações — seja por questões de segurança, de conectividade limitada com a internet, ou simplesmente para manter tudo dentro da própria infraestrutura. Neste artigo, mostro como subir um registro de imagens Docker local, tanto em uma versão simples (para testes) quanto em uma versão com autenticação (mais próxima de um cenário real).

⚠️ O passo a passo abaixo usa um registro sem TLS, adequado apenas para ambientes de teste. Para produção, é essencial configurar um certificado e conexão TLS — nunca exponha um registro sem criptografia em produção.

Configuração inicial

Antes de subir o registro, é preciso avisar o Docker de que ele pode confiar em um registro "inseguro" (sem TLS). Essa configuração precisa ser feita no servidor onde o registro vai rodar e em todos os nós do cluster que forem usá-lo.

Edite o arquivo /etc/docker/daemon.json, informando o host (IP ou nome da máquina) e a porta do registro:

{
    "insecure-registries": [ "host:port" ]
}
Enter fullscreen mode Exit fullscreen mode

Depois, reinicie o serviço do Docker para aplicar a mudança:

# systemctl restart docker
Enter fullscreen mode Exit fullscreen mode

Criando o servidor de registro

A forma mais simples de subir um registro é rodando a imagem oficial registry como um container:

$ docker run -d -p 5000:5000 --restart=always --name=repositorio registry
Enter fullscreen mode Exit fullscreen mode

Explicando cada opção:

Opção Função
-d Roda o container em background (daemon)
-p 5000:5000 Expõe a porta 5000 do container na porta 5000 do host
--restart=always Reinicia o container automaticamente em caso de falha
--name=repositorio Nome dado ao container
registry Imagem oficial usada para rodar o servidor de registro

Testando o registro

Para confirmar que o registro está no ar, basta acessar pelo navegador:

http://registry.zion.local:5000/v2/
Enter fullscreen mode Exit fullscreen mode

Uma resposta vazia em JSON ({}) já indica que o serviço está funcionando corretamente.

Publicando uma imagem no registro local

1. Liste as imagens disponíveis localmente:

$ docker image ls
Enter fullscreen mode Exit fullscreen mode

2. Marque (tag) a imagem apontando para o endereço do registro local — no exemplo, a imagem oregontecnologia/myapp-api:

$ docker tag oregontecnologia/myapp-api registry.zion.local:5000/myapp-api
Enter fullscreen mode Exit fullscreen mode

3. Envie a imagem para o registro local:

$ docker push registry.zion.local:5000/myapp-api
Enter fullscreen mode Exit fullscreen mode

Usando a imagem do registro local no Kubernetes

Com a imagem publicada, já é possível criar um Deployment no cluster apontando diretamente para o registro local:

$ kubectl create deploy myapp-api --image=registry.zion.local:5000/myapp-api
Enter fullscreen mode Exit fullscreen mode

E confirmar que o pod subiu corretamente:

$ kubectl get pods -o wide
Enter fullscreen mode Exit fullscreen mode

Se o Kubernetes não conseguir baixar a imagem (erro de ImagePullBackOff), verifique se o insecure-registries foi configurado em todos os nós do cluster — não só no servidor onde o registro está rodando —, já que qualquer worker pode ser escolhido para agendar o pod.

Subindo o nível: registro com autenticação

O exemplo acima é funcional, mas sem nenhuma proteção — qualquer pessoa com acesso à rede pode enviar ou baixar imagens. Para um cenário mais realista, vamos adicionar autenticação via htpasswd.

Criando as credenciais

Primeiro, instale o utilitário htpasswd (parte do pacote apache2-utils):

$ sudo apt install apache2-utils
Enter fullscreen mode Exit fullscreen mode

Crie uma pasta para armazenar o arquivo de senhas:

$ mkdir ~/home-user/auth && cd $_
Enter fullscreen mode Exit fullscreen mode

Crie o arquivo registry.password, adicionando o primeiro usuário com a flag -c (que cria o arquivo) e -B (que usa criptografia bcrypt):

$ htpasswd -Bc registry.password nome_usuário
Enter fullscreen mode Exit fullscreen mode

Para adicionar outros usuários depois, não use a flag -c novamente (ela sobrescreveria o arquivo):

$ htpasswd -B registry.password nome_do_novo_usuário
Enter fullscreen mode Exit fullscreen mode

Subindo o registro autenticado com Docker Compose

Em vez de um único comando docker run, um registro autenticado fica mais organizado como um docker-compose.yml:

$ vim docker-compose.yml
Enter fullscreen mode Exit fullscreen mode 
version: '3'

services:
  registry:
    image: registry:2
    ports:
    - "5000:5000"
    environment:
      REGISTRY_AUTH: htpasswd
      REGISTRY_AUTH_HTPASSWD_REALM: Registry
      REGISTRY_AUTH_HTPASSWD_PATH: /auth/registry.password
      REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY: /data
    volumes:
      - ./auth:/auth
      - ./data:/data
    restart: always
Enter fullscreen mode Exit fullscreen mode

Esse arquivo:

  • Usa a imagem oficial registry:2;
  • Habilita autenticação via htpasswd, apontando para o arquivo de senhas criado anteriormente;
  • Persiste as imagens em um volume local (./data), evitando perda de dados caso o container seja recriado.

Suba o serviço:

$ docker-compose up
Enter fullscreen mode Exit fullscreen mode

Testando o registro autenticado 

http://nome-ou-ip-do-servidor:5000/v2
Enter fullscreen mode Exit fullscreen mode

Ao tentar acessar, o navegador (ou o docker login) deve solicitar usuário e senha — confirmando que a autenticação está ativa.

Considerações finais

Ter um registro de imagens local dá mais controle e independência ao cluster on-premise, especialmente em ambientes sem acesso irrestrito à internet ou com políticas de segurança mais rígidas. A versão com autenticação via htpasswd já é um bom ponto de partida para ambientes reais — mas, para produção, vale complementar com TLS e, dependendo da escala, considerar soluções mais robustas como o Harbor, que adiciona recursos como controle de acesso granular, scanning de vulnerabilidades e replicação entre registros.

Se o seu cluster precisar autenticar automaticamente contra um registro privado (público ou local) ao fazer o pull das imagens, veja também o artigo sobre como configurar um imagePullSecret com regcred no Kubernetes.

Top comments (0)