Etiquetas frente a digests en imágenes de contenedor: nombres mutables y direcciones de contenido

Qué es

Un registro OCI almacena blobs (capas y manifiestos) por dirección de contenido. La especificación de distribución (citada) define un digest como un identificador único creado a partir de un hash criptográfico del contenido de un blob, y una etiqueta como un puntero personalizado y legible para humanos hacia un manifiesto; el digest de un manifiesto puede tener cero, una o varias etiquetas que lo referencian. La sección de descriptores de la especificación de imagen (citada) explica que el digest actúa como un identificador de contenido y que el contenido obtenido de una fuente no confiable puede verificarse recalculándolo. Una referencia tiene, por lo tanto, dos formas: registry/repo:tag se resuelve mediante un puntero mutable, mientras que registry/repo@sha256:<hex> nombra bytes. La referencia de la CLI de Docker (citada) llama a la segunda forma extracción (pull) mediante un identificador inmutable.

Por qué importa

python:3.12-slim hoy y el mes que viene son imágenes distintas con el mismo nombre; myapp:latest en dos nodos puede ser dos builds distintos. Una reversión "a la etiqueta anterior" puede traer algo más nuevo que lo que corría antes si la etiqueta se volvió a empujar (push). Los escaneos de vulnerabilidades, las atestaciones de procedencia y las firmas se adjuntan todos a los digests, de modo que un despliegue descrito solo por etiqueta no puede vincularse con su resultado de escaneo. A la inversa, un digest no tiene ningún significado para una persona sin un registro de a partir de qué se construyó.

Cómo aplicarlo

• Empujar (push) un build una sola vez bajo una identidad inmutable (sha-<commit> o una etiqueta de versión) y dejar que CI imprima el digest resultante; almacenarlo junto con el release.
• Desplegar por digest: image: registry/app@sha256:… en los manifiestos, o resolver la etiqueta a un digest en el momento del despliegue y registrarlo en el manifiesto renderizado.
• Fijar las imágenes base en los Dockerfiles como FROM image:tag@sha256:…, de modo que la etiqueta documente la intención y el digest fije el contenido; actualizar ambos mediante pull requests de actualización revisadas.
• Usar las etiquetas flotantes (latest, 3.12) solo para uso interactivo y para descubrir qué fijar a continuación.
• Tratar con cuidado una etiqueta multiplataforma: apunta a un índice de imágenes cuyo digest difiere de los digests de manifiesto por plataforma que contiene.

Trampas

Los listados de un registro suelen organizarse por etiqueta, de modo que un manifiesto sin etiqueta es fácil de pasar por alto, aunque siga siendo extraíble por digest y siga ocupando almacenamiento. La especificación de distribución permite que un registro implemente la eliminación de etiquetas por separado de la eliminación de manifiestos, de modo que quitar una etiqueta no libera por sí sola el manifiesto ni sus capas. Reempaquetar una imagen (por ejemplo, recomprimir las capas o reconstruir con metadatos distintos) cambia el digest aunque los archivos internos sean idénticos; las firmas y las atestaciones, en cambio, se almacenan junto a la imagen y no la modifican.