Cómo funciona un registro de contenedores: hacer push/pull de imágenes directamente

• El registro de contenedores parece simple por fuera, pero para depurar problemas como etiquetas incorrectas, incompatibilidades de plataforma, capas faltantes o fallos de eliminación real, es imprescindible entender cómo funciona internamente
• El núcleo del registro es un almacenamiento de blobs direccionado por contenido (content-addressable), donde todas las capas, archivos de configuración y artefactos se guardan usando el digest como dirección
• El push de una imagen sigue el orden de subir blobs y luego agruparlos en un manifest, mientras que el pull sigue la estructura inversa: primero obtiene el manifest y después descarga los blobs en secuencia
• La eliminación de imágenes no se completa solo con quitar la etiqueta; para borrarlas por completo hay que verificar primero las capas compartidas por otros manifests y luego eliminar también los blobs directamente
• Las imágenes multiplataforma se implementan manteniendo intactos los endpoints del API existente y agregando solo una capa extra de indirección llamada image index (manifest list)

---

Resumen del API del registro

• La mayoría de los registros de contenedores modernos implementan la OCI Distribution Specification, que define un protocolo API para estandarizar la distribución de contenido
• El API del registro es en realidad conciso y fácil de entender, y se puede manipular directamente incluso solo con curl

Subida y descarga de blobs

• Un registro es, en esencia, un almacenamiento de blobs direccionado por contenido: se hace hash del archivo localmente y luego se sube usando el digest como dirección
• La forma más simple de subirlo es con Monolithic PUT, una estructura de 2 pasos donde se inicializa una sesión con POST y luego se envía el blob con PUT
  • Para archivos grandes, el método de subida por fragmentos POST + PATCH + PUT es más eficiente, pero para blobs pequeños Monolithic PUT es suficiente
• Si la subida tiene éxito, se devuelve una respuesta HTTP/2 201 Created junto con un encabezado Location que apunta a la ubicación del nuevo blob
• Para descargar, si se conoce el digest, se puede hacer directamente con GET /v2/<repo>/blobs/<digest>

Push de imágenes

• Procedimiento de push de una imagen: (1) subir los blobs de cada capa de rootfs → (2) subir el blob de image configuration → (3) hacer push del archivo manifest, que agrupa todos los digests en un único documento JSON
• El manifest se sube al endpoint PUT /v2/<repo>/manifests/<tag>, y en ese momento se crea la etiqueta
• Los clientes reales (por ejemplo, docker push) suben blobs en paralelo, pero para entender el principio también se puede procesar de forma secuencial
• Ejemplo de estructura de un directorio de imagen: config.json, layer-1.tar.gz, layer-2.tar.gz, manifest.json

Consulta de la lista de etiquetas

• Con el endpoint GET /v2/<repo>/tags/list se puede consultar la lista completa de etiquetas de un repositorio específico
• Esta función no está expuesta en el CLI de docker; solo se puede acceder con curl o herramientas como crane y regctl
  • crane y regctl no hacen más que envolver el mismo endpoint con el comando ls

Pull de imágenes

• El procedimiento de pull es el inverso del push: (1) consultar el manifest con GET /v2/<repo>/manifests/<tag> → (2) descargar todos los blobs usando los digests indicados en el manifest
• Además de capas de rootfs y configuración de imagen, los manifests modernos también se usan como un almacén genérico que referencia blobs de artefactos arbitrarios como charts de Helm, SBOM, attestations de procedencia, pesos de LLM y más

Eliminación de imágenes

• Eliminar una imagen no es algo simple, y quitar una etiqueta (untag) no elimina el manifest en sí
• Procedimiento de eliminación completa:
  • (1) quitar la etiqueta con DELETE /v2/<repo>/manifests/<tag>
  • (2) consultar el manifest por digest para verificar todos los blobs que referencia
  • (3) eliminar de forma selectiva solo los blobs que no estén compartidos por otros manifests
  • (4) eliminar el blob del manifest con DELETE /v2/<repo>/blobs/<manifest-digest>
• Como el registro es un almacenamiento direccionado por contenido, varias imágenes pueden compartir la misma capa de rootfs, y al eliminarla se afecta a todas las imágenes que la referencian
• Como alternativa, se pueden quitar todas las etiquetas y luego depender de la configuración de garbage collection del registro, aunque en los registros públicos no siempre está habilitada

Imágenes multiplataforma

• Las imágenes multiplataforma se implementan sin cambiar la estructura del API del registro: se reutiliza el API existente tal cual, sin agregar ni modificar endpoints
• Forma de composición:
  • primero se hace push de cada variante de plataforma individual (amd64, arm64, etc.) basada en digest, junto con su manifest correspondiente
  • después se hace push de un manifest superior, llamado image index (manifest list), junto con la etiqueta
• Al llamar a GET /v2/<repo>/manifests/<tag>, se devuelve ya sea un manifest de plataforma única o un image index, y quien llama debe distinguirlos por el content type del documento recibido
• En consecuencia, el soporte multiplataforma solo agrega a la estructura existente una capa de indirección y una etapa adicional de subida/descarga del documento index

Protección del API del registro

• La OCI Distribution Spec no define de forma estricta el método de autenticación, pero la mayoría de los registros reales usan autenticación HTTP Basic
• Para evitar que las credenciales se transmitan en texto plano, es obligatorio operar sobre HTTPS