Docker
Publicación, pull, autenticación, versionado y promoción de imágenes.
Un registry es el sistema que almacena y distribuye imágenes y otros artefactos compatibles con OCI. No guarda una imagen como un único archivo llamado ; organiza repositories, manifests, índices, configs y blobs direccionados por contenido.
api:1.4.0registry.example.com/team/api:1.4.0
│
├── registry: registry.example.com
├── namespace: team
├── repository: api
└── tag: 1.4.0
↓
manifest o image index
↓
config + layer blobsEl registry forma parte de la cadena de suministro. Si no está disponible, no es confiable o permite sobrescribir artefactos sin control, la reproducibilidad del despliegue queda comprometida.
Una imagen construida únicamente en un laptop no puede utilizarse de forma controlada por CI, staging y producción. Copiar manualmente tarballs genera varios problemas:
El registry proporciona un punto de distribución común:
CI construye
→ publica blobs y manifest
→ staging hace pull
→ valida el digest
→ producción utiliza el mismo artefactoLa idea importante es construir una vez y promover el mismo contenido. Si cada ambiente reconstruye desde source, puede obtener dependencias, timestamps, bases o paquetes diferentes.
Agrupa versiones relacionadas de un artefacto:
team/apiUn repository puede contener muchos tags y manifests. No representa una sola imagen.
Es una referencia legible:
team/api:1.4.0
team/api:main
team/api:latestPor diseño, un tag puede moverse y apuntar a otro manifest. Algunos registries permiten configurar tags inmutables, pero no debes asumirlo sin verificar la política.
Identifica contenido exacto:
team/api@sha256:abc123...Si cambia el manifest, cambia el digest. Por eso es la unidad adecuada para promoción, auditoría y rollback.
Tag
“dame lo que actualmente se llama 1.4.0”
Digest
“dame exactamente este manifest”Un tag semántico sigue siendo útil para humanos. El error es utilizarlo como única evidencia de qué se desplegó.
Considera:
docker tag my-api:build-481 registry.example.com/team/api:1.4.0
docker push registry.example.com/team/api:1.4.0El primer comando no duplica necesariamente los datos. Añade una nueva referencia local al mismo contenido.
Durante el push, de forma simplificada:
El manifest debe publicarse al final. Si una capa falla antes, el tag no debería apuntar a un artefacto incompleto, aunque pueden quedar blobs sin referencia que una política posterior limpie.
docker pull registry.example.com/team/api:1.4.0Flujo conceptual:
Hacer pull por tag no significa que Docker consulte el registry cada vez que ejecutas docker run. Si la referencia existe localmente, puede utilizar esa copia según la herramienta y política de pull aplicada.
Una referencia como:
team/api:1.4.0puede apuntar a un image index:
index digest D1
├── linux/amd64 manifest digest D2
└── linux/arm64 manifest digest D3Los tres digests identifican objetos diferentes.
Para promover una publicación multi-platform, normalmente interesa conservar el digest del índice. Para investigar qué ejecutó un host concreto, también importa el digest del manifest de su plataforma.
Inspección:
docker buildx imagetools inspect registry.example.com/team/api:1.4.0No asumas que “el digest de la imagen” siempre es uno solo sin contexto.
Una estrategia útil combina referencias para propósitos diferentes.
1.4.0Comunica una release comprensible.
git-a84f92cPermite volver del artefacto al source.
main
staging
stableSon referencias móviles apropiadas para ciertos flujos, pero no deben ser la única identidad almacenada en el deployment.
build-481Ayuda a relacionar el artefacto con CI.
Un mismo manifest puede tener varios tags:
api:1.4.0
api:git-a84f92c
api:build-481Todos pueden resolver inicialmente al mismo digest.
latest es solo un tag convencional. Docker no compara fechas ni versiones para determinarlo.
Puede ocurrir que:
Usarlo en desarrollo puede ser aceptable si la mutabilidad es intencional. En producción dificulta reproducibilidad, incidentes y rollback.
Un flujo débil reconstruye en cada ambiente:
commit
├── build staging → digest A
└── build production → digest BAunque ambos builds partan del mismo commit, pueden cambiar:
Un flujo sólido:
commit
→ build
→ digest A
→ test
→ scan
→ staging usa digest A
→ aprobación
→ producción usa digest ALa configuración de runtime puede variar. El artefacto no.
Promover no siempre requiere descargar y volver a subir todas las capas. Algunos registries permiten copiar manifests o añadir tags dentro del servidor.
Conceptualmente:
api:candidate → sha256:A
api:stable → sha256:ALa nueva referencia humana apunta al mismo contenido.
Aun así, el deployment debe registrar sha256:A. Si mañana stable se mueve, puedes demostrar qué versión se ejecutó.
docker login registry.example.comLa autenticación permite obtener credenciales para operaciones posteriores. El almacenamiento y helper utilizado dependen de la plataforma.
--password-stdin cuando corresponda.printf '%s' "$REGISTRY_TOKEN" | docker login \
--username ci \
--password-stdin registry.example.comEl comando evita incluir el token literalmente en el historial del shell, pero la variable y el entorno de CI todavía necesitan protección.
Autenticarse responde “quién eres”. Autorizar responde “qué puedes hacer”.
Un pipeline que solo hace pull no necesita permiso de push. Un repositorio de producción puede aceptar publicaciones únicamente desde un workflow protegido.
Permisos excesivos aumentan el impacto de una credencial robada:
token comprometido
+ permiso de sobrescribir tags de producción
→ sustitución de artefactosTLS protege el transporte, pero no responde todas las preguntas:
Controles complementarios:
Un digest exacto puede identificar malware exacto. La identidad criptográfica no sustituye la confianza.
El registry es una dependencia del despliegue.
Puede iniciar un contenedor sin contactar nuevamente al registry, siempre que el contenido y referencia local estén disponibles y la política no fuerce pull.
Necesita descargar la imagen. Una caída del registry puede impedir nuevas instancias o rollbacks no cacheados.
No bases una estrategia de recuperación únicamente en “seguro la imagen sigue en algún host”.
Los registries acumulan manifests, tags y blobs. Una política debe distinguir:
Eliminar un tag puede no borrar inmediatamente los blobs. El garbage collector solo puede eliminar contenido que ya no esté referenciado según el modelo del registry.
Si borras el digest anterior justo después de desplegar, pierdes un rollback rápido. También puedes dejar una deployment definition que referencia un artefacto inexistente.
1. checkout commit a84f92c
2. tests
3. docker buildx build
4. push api:git-a84f92c
5. registry devuelve digest sha256:A
6. generar SBOM y provenance para A
7. desplegar staging con sha256:A
8. smoke tests
9. aprobar
10. desplegar producción con sha256:A
11. conservar sha256:PREVIOUS para rollbackTags como candidate o stable pueden facilitar navegación, pero la base de datos de deployments registra sha256:A.
Rollback:
producción sha256:A falla
→ actualizar deployment a sha256:PREVIOUS
→ no reconstruir
→ verificar saludPosibles causas:
Primero confirma identidad y alcance; no conviertas una credencial de lectura en administrador para “resolver rápido”.
La referencia no existe o el tag fue eliminado. Comprueba registry, repository, tag y digest exactos.
El índice no incluye la plataforma solicitada. Publica una variante compatible o usa emulación conscientemente.
Pueden venir de CA corporativa, hostname incorrecto, proxy o certificado expirado. No marques el registry como insecure sin analizar el modelo de amenaza.
Distingue:
Continúa usando el contenido local anterior. Dos hosts con el mismo tag pueden ejecutar digests distintos.
Un host existente puede seguir ejecutándolo, pero nuevos hosts no podrán recuperarlo. El rollback ya no es portable.
El tag multi-platform puede cambiar mientras se añaden arquitecturas. Diseña publicación atómica del índice final o evita desplegar durante una ventana inconsistente.
Debe revocarse y rotarse. Ocultar posteriormente el log no invalida una credencial ya expuesta.
Los digests permiten detectar identidad, pero los tags pueden resolver diferente durante sincronización. Para artefactos críticos usa referencias inmutables.
Consecuencia: no puedes demostrar qué manifest se ejecutó.
Corrección: resuelve y registra el digest en cada deployment.
Consecuencia: producción recibe un artefacto que staging nunca probó.
Corrección: promueve el mismo digest y cambia solo configuración externa.
Consecuencia: no hay atribución y una filtración compromete todos los repositories.
Corrección: identidades separadas, scopes mínimos y auditoría.
Consecuencia: puedes eliminar un digest desplegado o necesario para rollback.
Corrección: combinar edad con referencias, ambiente y política de releases.
Consecuencia: distribuyes de forma segura un artefacto no autorizado o vulnerable.
Corrección: verificar identidad del builder, provenance, firmas y políticas.
Útiles para:
Necesarios para:
La práctica madura utiliza ambos: tags para comunicación y digests para identidad.
Publica o utiliza una imagen de prueba y observa la resolución:
docker pull alpine:3.22
docker image inspect alpine:3.22 --format '{{json .RepoDigests}}'Después, ejecuta por digest:
docker run --rm alpine@sha256:<digest> cat /etc/alpine-releaseCompara con el tag. Comprueba además las plataformas:
docker buildx imagetools inspect alpine:3.22El objetivo es distinguir la referencia humana, el índice y la variante concreta.
Lifecycle de contenedores, para comprender cómo un artefacto distribuido se convierte en una instancia, atraviesa estados y termina de forma segura.