Cómo versionar imágenes Docker con tags

como-versionar-imagenes-docker-con-tags
como-versionar-imagenes-docker-con-tags

Versionar imágenes Docker con tags es una práctica esencial para saber exactamente qué versión de una aplicación estás ejecutando, probando o desplegando. Un tag no es solo una etiqueta bonita: es una referencia que te ayuda a controlar cambios, hacer rollback y evitar sorpresas entre entornos.

El error habitual es depender siempre de latest. Puede funcionar en pruebas rápidas, pero en proyectos reales hace más difícil reproducir errores, auditar despliegues o saber qué imagen llegó a producción. Por eso conviene definir una estrategia clara de etiquetas.

En esta lección vas a aprender cómo versionar imágenes Docker con tags, qué formatos usar, cómo etiquetar imágenes ya construidas y qué buenas prácticas aplicar para trabajar con registros y pipelines de forma más segura.

👉 Y recuerda, si quieres aprender más de Linux, visita el curso de Linux gratis.

🐳 Si quieres aprender más de Docker, visita el curso de Docker gratis.

Qué es un tag en una imagen Docker

Un tag es la parte final del nombre de una imagen y normalmente identifica una versión, variante o estado. En una referencia como mi-app:1.4.2, el repositorio es mi-app y el tag es 1.4.2.

docker image ls
docker pull nginx:1.27-alpine
docker pull nginx:stable

Docker permite usar distintos tags para la misma imagen o para variantes diferentes. Algunos tags apuntan a versiones concretas; otros, como stable o latest, pueden moverse con el tiempo. Esa diferencia es clave al diseñar una estrategia de despliegue.

Tipo de tagEjemploUso recomendado
Versión semántica1.4.2Releases estables y reproducibles.
Versión mayor o menor1 / 1.4Canales controlados con cierto margen de actualización.
Commit cortoa1b2c3dTrazabilidad desde CI/CD hasta el código fuente.
Entornostaging / prodSolo como alias operativo, no como única fuente de verdad.
latestlatestPruebas rápidas; evitar como referencia principal en producción.

Cómo versionar imágenes Docker al construir

La forma más directa de asignar un tag es usar la opción -t durante el build. Puedes crear una imagen con una versión clara desde el primer momento.

docker build -t mi-app:1.0.0 .
docker build -t mi-app:1.0.1 .
docker image ls mi-app

Este patrón deja claro qué versión estás construyendo. Si además tu proyecto usa releases, puedes alinear el tag de la imagen con la versión del código o del paquete.

También puedes asignar varios tags a la misma construcción, por ejemplo una versión exacta y un alias de rama o entorno.

docker build -t mi-app:1.0.1 -t mi-app:stable .

Esto no crea dos builds distintos: crea dos referencias hacia la imagen resultante. Úsalo con cuidado y evita que los alias oculten cuál es la versión exacta desplegada.

Etiquetar imágenes ya existentes

Si ya tienes una imagen local, puedes crear un nuevo tag con docker tag. Es útil antes de subir una imagen a un registry o cuando necesitas cambiar el nombre hacia un repositorio remoto.

docker tag mi-app:1.0.1 registry.example.com/mi-equipo/mi-app:1.0.1
docker tag mi-app:1.0.1 registry.example.com/mi-equipo/mi-app:stable

El comando docker tag no copia capas ni reconstruye la imagen. Solo crea una nueva referencia. Por eso es rápido, pero también exige disciplina: si mueves stable, asegúrate de que el equipo sabe qué versión representa ahora.

docker image inspect registry.example.com/mi-equipo/mi-app:1.0.1

Inspeccionar la imagen ayuda a revisar metadatos, digest y configuración. Para trazabilidad fuerte en producción, el digest es incluso más preciso que un tag, porque identifica el contenido exacto de la imagen.

Subir tags a un registry

Para compartir una imagen, necesitas subirla a un registry como Docker Hub, GHCR, GitLab Registry, ECR, ACR o Artifact Registry. El nombre de la imagen debe incluir el repositorio correcto antes de hacer push.

docker login registry.example.com
docker push registry.example.com/mi-equipo/mi-app:1.0.1
docker push registry.example.com/mi-equipo/mi-app:stable

En entornos reales no conviene hacer login manual en servidores de producción si puedes usar un pipeline seguro. Las credenciales del registry deben gestionarse como secretos y no quedar escritas en scripts o logs.

Si publicas varios tags para la misma imagen, empuja cada tag que quieras tener disponible en el registry. Que exista localmente no significa que ya exista remotamente.

Estrategia de tags recomendada

Una estrategia práctica suele combinar un tag inmutable y uno o varios alias móviles. El tag inmutable te da trazabilidad; el alias móvil facilita operaciones humanas.

mi-app:1.4.2
mi-app:1.4
mi-app:1
mi-app:sha-a1b2c3d
mi-app:staging

Para producción, la referencia más segura suele ser una versión concreta o un digest. Para entornos de desarrollo o staging, puedes permitir alias móviles si el equipo entiende que pueden cambiar.

  • Usa tags inmutables para releases y despliegues que deban poder reproducirse.
  • Usa el commit SHA cuando necesites conectar una imagen con una ejecución de CI/CD.
  • Usa alias móviles solo como comodidad operativa, no como única trazabilidad.
  • Evita latest como referencia principal de producción.
  • Documenta la política para que todo el equipo etiquete igual.

Errores comunes al usar tags

  • Creer que latest significa última versión estable: latest solo es un tag más y puede apuntar a lo que el publicador decida.
  • Sobrescribir tags sin control: mover una etiqueta usada por producción rompe la reproducibilidad.
  • No subir todos los tags necesarios: etiquetar localmente no publica automáticamente en el registry.
  • No conectar tag y código fuente: sin versión, commit o release, es difícil saber qué contiene una imagen.
  • Usar nombres distintos en cada equipo: una convención inconsistente complica despliegues y soporte.

El problema de fondo es tratar los tags como algo improvisado. Cuando empiezan los despliegues, los rollbacks y los incidentes, la estrategia de versionado deja de ser un detalle y se convierte en una herramienta de diagnóstico.

Buenas prácticas para versionar imágenes Docker

Automatiza el etiquetado en CI/CD. El pipeline puede generar tags a partir de la versión del proyecto, el commit y la rama. Así reduces errores manuales y mantienes una relación clara entre código, build e imagen.

No cambies tags inmutables una vez publicados. Si la versión 1.4.2 ya fue subida, corregir un fallo debería producir una nueva versión, no reemplazar silenciosamente el contenido anterior con el mismo nombre.

Usa digests cuando necesites máxima precisión. Un tag puede moverse, pero un digest identifica el contenido exacto. En auditorías, entornos críticos o investigaciones de incidentes, esta diferencia importa.

En resumen, versionar imágenes Docker correctamente te ayuda a desplegar con más control, reproducir errores y hacer rollback sin depender de suposiciones. La clave es combinar tags legibles, trazabilidad desde CI/CD y una política clara para no mover referencias críticas sin control.

Lecciones relacionadas del curso Docker

Documentación oficial y recursos

Con esta base, ya puedes definir una convención de tags más fiable: versiones exactas para releases, identificadores de commit para trazabilidad y alias móviles solo cuando estén documentados y controlados.

Comentarios

No hay comentarios aún. ¿Por qué no comienzas el debate?

Deja una respuesta

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *