En esta lección aprenderás qué hace la Instrucción LABEL Dockerfile y por qué es útil cuando quieres añadir metadatos a una imagen. No cambia cómo arranca el contenedor, pero sí ayuda a documentar, clasificar y automatizar imágenes.
La idea es simple: una label es una etiqueta clave-valor guardada dentro de la imagen. Puedes usarla para indicar versión, descripción, autor, repositorio, licencia o información que después leerán tus scripts y herramientas de CI/CD.
👉 Y recuerda, si quieres aprender más de Linux, pincha en este curso de Linux gratis
🐳 Si quieres aprender más de Docker, pincha en este curso de Docker gratis
Para qué sirve LABEL en Dockerfile
Problema: cuando tienes muchas imágenes, el nombre y el tag no siempre explican quién la mantiene, qué versión representa o de dónde salió.
Qué aporta Docker: LABEL permite guardar metadatos dentro de la imagen para consultarlos más tarde con inspect, filtros o herramientas externas.
| Uso | Ejemplo |
|---|---|
| Identificar la imagen | Título, descripción o componente al que pertenece. |
| Trazabilidad | Versión, commit, fecha de build o repositorio fuente. |
| Automatización | Filtros para scripts de limpieza, inventario o auditoría. |
| Documentación | Responsable, licencia o URL del proyecto. |
Ejemplo de Instrucción LABEL Dockerfile
Puedes escribir una o varias labels dentro del Dockerfile. En proyectos reales conviene usar nombres claros y, si encaja, seguir las claves de Open Container Initiative.
FROM nginx:alpine
LABEL org.opencontainers.image.title="web-demo"
LABEL org.opencontainers.image.description="Imagen de ejemplo para practicar LABEL"
LABEL org.opencontainers.image.version="1.0.0"
LABEL maintainer="[email protected]"Este ejemplo no instala paquetes ni modifica el proceso principal. Solo añade metadatos a la imagen resultante, por eso es una práctica segura para empezar.
Construir y verificar labels
Después de construir la imagen, no des por hecho que la metadata quedó bien. Verifícala con docker image inspect y revisa el objeto de labels.
docker build -t web-demo:label .
docker image inspect web-demo:label --format '{{json .Config.Labels}}' Resultado esperado: inspect debe mostrar las claves que escribiste en el Dockerfile. Si no aparecen, revisa que estás inspeccionando la imagen correcta y que hiciste build después de editar el archivo.
Filtrar imágenes por label
Una ventaja práctica es que Docker puede filtrar imágenes por label. Esto ayuda cuando quieres encontrar imágenes de un proyecto, una versión o una familia concreta sin depender solo del nombre.
docker image ls --filter label=org.opencontainers.image.version=1.0.0
docker image inspect web-demo:label --format '{{ index .Config.Labels "org.opencontainers.image.title" }}' - Usa nombres consistentes: evita mezclar claves inventadas en cada Dockerfile.
- No metas secretos: las labels quedan visibles al inspeccionar la imagen.
- No reemplaza al tag: una label documenta; el tag sigue siendo parte del nombre de la imagen.
- Verifica después del build: la label pertenece a la imagen construida, no al contenedor por arte de magia.
Errores comunes
- Usar LABEL para guardar contraseñas, tokens o datos sensibles.
- Pensar que cambiar una label modifica el comportamiento de la aplicación.
- Editar el Dockerfile y olvidarse de reconstruir la imagen.
- Inspeccionar un contenedor antiguo en vez de la imagen recién creada.
- Crear claves diferentes para el mismo concepto en cada proyecto.
- Confundir LABEL con ENV: ENV define variables de entorno; LABEL guarda metadatos.
La regla práctica para Instrucción LABEL Dockerfile es clara: úsala para describir la imagen, no para configurar la aplicación ni para guardar información privada.
Lecciones relacionadas del curso Docker
- Qué es un Dockerfile: ubica LABEL dentro de la construcción de imágenes.
- Instrucción ENV Dockerfile: diferencia metadatos y variables de entorno.
- Instrucción ARG: entiende valores de build frente a labels finales.
- Cómo funcionan las capas de una imagen: conecta instrucciones y capas de imagen.
- guía completa de Docker: vuelve al índice del curso.
Documentación oficial y recursos
- Dockerfile LABEL: referencia oficial de la instrucción LABEL.
- docker image inspect: consulta labels y configuración de imagen.
- docker image ls: filtra imágenes por label.
- OCI image annotations: convenciones de metadatos para imágenes OCI.
- Build variables: diferencias útiles entre ARG, ENV y metadatos de build.
En resumen, la Instrucción LABEL Dockerfile sirve para añadir información descriptiva a una imagen. Esa información mejora trazabilidad, inventario y automatización, siempre que no la uses para secretos ni configuración sensible.
Si documentas bien tus imágenes desde el Dockerfile, después será más fácil saber qué versión estás usando, quién la mantiene y cómo encaja dentro de tu flujo de construcción y despliegue.
