Como funciona um registro de contêineres: fazendo push/pull de imagens diretamente

(labs.iximiuz.com)

1 pontos por GN⁺ 5 시간 전 | Ainda não há comentários. | Compartilhar no WhatsApp

O registro de contêineres parece simples à primeira vista, mas para depurar problemas como tags incorretas, incompatibilidade de plataforma, camadas ausentes ou falhas na exclusão real, é essencial entender como ele funciona por dentro
O núcleo do registro é um armazenamento de blobs endereçado por conteúdo (content-addressable), no qual todas as camadas, arquivos de configuração e artefatos são armazenados usando o digest como endereço
O push de imagens segue a ordem de enviar os blobs e depois agrupá-los em um manifest, enquanto o pull faz o inverso: primeiro recebe o manifest e depois baixa os blobs em sequência
A exclusão de imagens não é concluída apenas com untag; para removê-las de fato, é preciso primeiro verificar as camadas compartilhadas por outros manifests e então excluir os blobs diretamente
Imagens multiplataforma são implementadas mantendo os endpoints da API existentes exatamente como estão, introduzindo apenas uma camada extra de indireção chamada image index (manifest list)

Visão geral da API de Registry

A maioria dos registros de contêineres modernos implementa a OCI Distribution Specification, que define um protocolo de API para padronizar a distribuição de conteúdo
A API de Registry é, na prática, concisa e fácil de entender, e pode ser manipulada diretamente apenas com curl

Um registro é essencialmente um armazenamento de blobs endereçado por conteúdo, no qual o arquivo é hasheado localmente e enviado usando o digest como endereço
A forma mais simples de upload é o Monolithic PUT, uma estrutura em 2 etapas em que se inicializa a sessão com POST e depois se envia o blob com PUT
- Para arquivos grandes, o upload em partes com POST + PATCH + PUT é mais eficiente, mas para blobs pequenos o Monolithic PUT é suficiente
Quando o upload é concluído com sucesso, a resposta HTTP/2 201 Created retorna junto com o cabeçalho Location, que aponta para a localização do novo blob
Para baixar, basta conhecer o digest e fazer GET /v2/<repo>/blobs/<digest>

Procedimento de push de imagem: (1) upload dos blobs de cada camada rootfs → (2) upload do blob de configuração da imagem → (3) push do arquivo manifest, que reúne todos os digests em um único documento JSON
O manifest é enviado pelo endpoint PUT /v2/<repo>/manifests/<tag>, e é nesse momento que a tag é criada
Clientes reais (por exemplo, docker push) fazem o upload dos blobs em paralelo, mas para entender o princípio também é possível tratá-los em sequência
Exemplo de estrutura de diretório da imagem: config.json, layer-1.tar.gz, layer-2.tar.gz, manifest.json

É possível consultar a lista completa de tags de um repositório específico pelo endpoint GET /v2/<repo>/tags/list
Essa funcionalidade não é exposta no CLI do docker, sendo acessível apenas com curl ou ferramentas como crane e regctl
- crane e regctl apenas encapsulam o mesmo endpoint no comando ls

O procedimento de pull é o inverso do push: (1) consultar o manifest com GET /v2/<repo>/manifests/<tag> → (2) baixar todos os blobs usando os digests indicados no manifest
Além de camadas rootfs e configuração de imagem, manifests modernos também são usados como armazenamento genérico para referenciar blobs de artefatos arbitrários, como charts Helm, SBOM, atestados de procedência (provenance attestation) e pesos de LLM

Excluir uma imagem não é algo simples, e remover a tag (untag) por si só não apaga o manifest
Procedimento de exclusão completa:
- (1) remover a tag com DELETE /v2/<repo>/manifests/<tag>
- (2) consultar o manifest pelo digest para identificar todos os blobs referenciados
- (3) excluir seletivamente apenas os blobs que não estejam sendo compartilhados por outros manifests
- (4) excluir o blob do manifest com DELETE /v2/<repo>/blobs/<manifest-digest>
Como o registro é um armazenamento endereçado por conteúdo, várias imagens podem compartilhar a mesma camada rootfs, e a exclusão pode afetar todas as imagens que referenciam essa camada
Como alternativa, também é possível remover todas as tags e então depender da configuração de garbage collection do registro, mas em registros públicos isso nem sempre está ativado

Imagens multiplataforma são implementadas sem alterar a estrutura da API de Registry — sem adicionar ou modificar endpoints, reutilizando a API existente como está
Forma de composição:
- primeiro, cada variante de plataforma única (amd64, arm64 etc.) é enviada individualmente com seu próprio manifest, com base em digest
- depois, é feito o push de um manifest de nível superior chamado image index (manifest list) junto com a tag
Ao chamar GET /v2/<repo>/manifests/<tag>, o retorno pode ser um manifest de plataforma única ou um image index, e quem faz a chamada precisa distingui-los pelo content type do documento retornado
No fim, o suporte a multiplataforma apenas adiciona uma camada de indireção e uma etapa de upload/download de documento index à estrutura existente

A OCI Distribution Spec não define de forma rígida o método de autenticação, mas a maioria dos registros reais usa autenticação HTTP Basic
Para evitar que credenciais sejam transmitidas em texto puro, a operação deve ocorrer obrigatoriamente sobre HTTPS