Tags versus digests de imagens de contêiner: nomes mutáveis e endereços de conteúdo

O que é

Um registry OCI armazena blobs (camadas e manifests) por endereço de conteúdo. A especificação de distribuição (citada) define o digest como um identificador único criado a partir de um hash criptográfico do conteúdo de um blob, e a tag como um ponteiro personalizado e legível por humanos para um manifest; um digest de manifest pode ter zero, uma ou várias tags apontando para ele. A seção de descritores da especificação de imagem (citada) explica que o digest funciona como identificador de conteúdo e que o conteúdo obtido de uma fonte não confiável pode ser verificado recalculando-se o digest. Uma referência tem, portanto, duas formas: registry/repo:tag é resolvida por meio de um ponteiro mutável, enquanto registry/repo@sha256:<hex> nomeia bytes. A referência da CLI do Docker (citada) chama a segunda forma de pull por um identificador imutável.

Por que importa

python:3.12-slim hoje e daqui a um mês são imagens diferentes com o mesmo nome; myapp:latest em dois nós pode corresponder a dois builds distintos. Um rollback "para a tag anterior" pode trazer algo mais recente do que o que rodava antes, se a tag tiver sido enviada de novo. Varreduras de vulnerabilidades, atestações de proveniência e assinaturas se associam a digests, então um deploy descrito apenas por tag não pode ser relacionado ao resultado da sua varredura. Por outro lado, um digest não diz nada a uma pessoa sem um registro do que foi usado para construí-lo.

Como aplicar

• Envie cada build uma única vez com uma identidade imutável (sha-<commit> ou uma tag de versão) e faça a CI imprimir o digest resultante; guarde-o junto com a release.
• Faça o deploy por digest: image: registry/app@sha256:… nos manifests, ou resolva a tag para um digest no momento do deploy e registre-o no manifest renderizado.
• Fixe as imagens base nos Dockerfiles como FROM image:tag@sha256:…, de modo que a tag documente a intenção e o digest fixe o conteúdo; atualize ambos por meio de pull requests de atualização revisados.
• Use tags flutuantes (latest, 3.12) apenas para uso interativo e para descobrir o que fixar em seguida.
• Trate com cuidado uma tag multiplataforma: ela aponta para um image index cujo digest difere dos digests dos manifests por plataforma contidos nele.

Armadilhas

As listagens de um registry costumam ser organizadas por tag, por isso um manifest sem tag passa facilmente despercebido, embora ainda possa ser baixado por digest e continue ocupando armazenamento. A especificação de distribuição permite que um registry implemente a exclusão de tags separadamente da exclusão de manifests, de modo que remover uma tag não libera, por si só, o manifest nem suas camadas. Reempacotar uma imagem (por exemplo, recomprimir as camadas ou refazer o build com metadados diferentes) altera o digest, mesmo que os arquivos internos sejam idênticos; já as assinaturas e atestações ficam armazenadas ao lado da imagem e não a modificam.