Instrucción ONBUILD Dockerfile: guía práctica

instruccion-onbuild
instruccion-onbuild

La instrucción ONBUILD Dockerfile permite preparar una imagen base que ejecutará instrucciones automáticamente cuando otra imagen la use en su FROM. Es decir, no se ejecuta al construir la imagen base, sino cuando una imagen hija se construye a partir de ella.

Esta característica puede ser útil para crear imágenes base reutilizables en equipos, frameworks internos o plantillas de proyecto. Pero también puede ser confusa: el Dockerfile hijo ejecuta acciones que no aparecen directamente en su archivo, y eso puede complicar la depuración si no está bien documentado.

En esta lección vas a ver cómo funciona la instrucción ONBUILD Dockerfile, cuándo tiene sentido usarla, cómo comprobar sus disparadores y qué riesgos conviene evitar antes de incorporarla a una imagen compartida.

👉 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é hace ONBUILD en Dockerfile

ONBUILD registra una instrucción pendiente dentro de la imagen. Esa instrucción queda guardada como un disparador y se ejecuta más adelante, justo después del FROM, cuando otra imagen usa esa imagen base.

Por ejemplo, una imagen base puede dejar preparado un disparador para copiar el código de la aplicación o instalar dependencias. La imagen hija solo declara FROM, pero durante su build se ejecutan automáticamente las instrucciones registradas por la base.

FROM node:22-alpine
WORKDIR /app
ONBUILD COPY package*.json ./
ONBUILD RUN npm ci
ONBUILD COPY . .

Este Dockerfile crea una imagen base con disparadores. Cuando otra imagen use esa base, Docker ejecutará las instrucciones COPY y RUN definidas con ONBUILD en el contexto de construcción de la imagen hija.

Sintaxis de la instrucción ONBUILD Dockerfile

La sintaxis es sencilla: escribes ONBUILD seguido de otra instrucción válida de Dockerfile. La dificultad no está en la forma, sino en entender cuándo y dónde se ejecuta.

ONBUILD INSTRUCCION argumentos
ONBUILD COPY . /app
ONBUILD RUN npm ci
ElementoQué significaRecomendación
ONBUILDRegistra una instrucción pendiente en la imagen base.Úsalo solo si el comportamiento oculto está muy justificado.
COPY o ADDCopia archivos desde el contexto de la imagen hija.Evita asumir rutas que no existirán en todos los proyectos.
RUNEjecuta comandos durante el build de la imagen hija.Debe ser determinista y estar bien documentado.
FROM hijoActiva los disparadores de la imagen base.Revisa la imagen base antes de usarla en producción.
docker inspectPermite ver los disparadores ONBUILD registrados.Úsalo para auditar imágenes base.

No todas las instrucciones deberían convertirse en disparadores. Si el comportamiento es crítico, sorprendente o específico de un proyecto, suele ser mejor dejarlo explícito en el Dockerfile final.

Ejemplo práctico con imagen base

Imagina que quieres crear una base para proyectos Node.js pequeños. La imagen base define el directorio de trabajo y registra pasos comunes, pero la aplicación real se construye en otra imagen.

mkdir base-onbuild app-demo
cd base-onbuild
cat > Dockerfile <<EOF
FROM node:22-alpine
WORKDIR /app
ONBUILD COPY package*.json ./
ONBUILD RUN npm ci --omit=dev
ONBUILD COPY . .
CMD ["node", "server.js"]
EOF
docker build -t node-onbuild-base:1.0 .

La imagen node-onbuild-base contiene los disparadores, pero todavía no copia el código de ninguna aplicación. Esos pasos se ejecutarán cuando una imagen hija use esta base.

cd ../app-demo
cat > Dockerfile <<EOF
FROM node-onbuild-base:1.0
EOF

# Aquí tendrías package.json, package-lock.json y server.js
docker build -t app-demo:1.0 .

Cuando construyes app-demo, Docker activa los disparadores definidos en la base. Por eso este patrón puede ahorrar repetición, pero también puede esconder pasos importantes si el equipo no conoce cómo está creada la imagen base.

Cómo inspeccionar disparadores ONBUILD

Antes de confiar en una imagen base con ONBUILD, revisa sus metadatos. Docker guarda los disparadores en la configuración de la imagen, y puedes consultarlos con docker inspect.

docker inspect --format="{{json .Config.OnBuild}}" node-onbuild-base:1.0
docker image inspect node-onbuild-base:1.0

Si el resultado contiene instrucciones pendientes, significa que se ejecutarán al construir una imagen hija. Esta comprobación es especialmente importante cuando usas imágenes internas de equipo o imágenes antiguas que no has creado tú.

También puedes revisar el historial de la imagen para entender cómo se construyó. No sustituye una auditoría completa del Dockerfile original, pero ayuda a detectar capas y comandos relevantes.

docker history node-onbuild-base:1.0

Cuándo usar ONBUILD y cuándo evitarlo

ONBUILD encaja cuando tienes una imagen base muy controlada, una estructura de proyecto repetida y un equipo que entiende el contrato. Por ejemplo, plantillas internas donde todos los proyectos tienen los mismos archivos, comandos y rutas.

En cambio, no suele ser buena idea para imágenes públicas genéricas, builds complejos o proyectos donde la claridad del Dockerfile es más importante que ahorrar unas pocas líneas. Si el comportamiento sorprende al lector, probablemente debería estar explícito.

  • Úsalo para bases internas con contrato estable y documentación clara.
  • Evítalo si cada proyecto necesita pasos diferentes de build.
  • Evítalo si el equipo no inspecciona ni versiona la imagen base.
  • Evítalo para acciones destructivas, descarga de secretos o comandos dependientes del entorno local.
  • Prefiere Dockerfile explícito cuando estás enseñando, auditando o depurando una imagen.

Errores comunes con ONBUILD

  • No documentar los disparadores: quien lee el Dockerfile hijo no ve todos los pasos que realmente se ejecutan.
  • Asumir archivos que no existen: un ONBUILD COPY package*.json fallará si el proyecto hijo no tiene esos archivos.
  • Usar comandos demasiado específicos: cuanto más particular sea el build, menos reutilizable será la base.
  • Actualizar la imagen base sin controlar versiones: un cambio en la base puede alterar muchos proyectos hijos.
  • Depurar solo el Dockerfile hijo: si algo falla, también tienes que revisar los disparadores de la imagen base.

El problema más frecuente es la falta de visibilidad. Una imagen hija puede parecer demasiado simple y aun así ejecutar pasos relevantes durante el build. Por eso conviene inspeccionar la base y fijar versiones claras.

Buenas prácticas para la instrucción ONBUILD Dockerfile

Versiona la imagen base y comunica su contrato. Si una base espera package.json, requirements.txt o una estructura concreta de carpetas, esa expectativa debe estar documentada y validada.

Mantén los disparadores pequeños y previsibles. No uses ONBUILD para operaciones con secretos, comandos destructivos, descargas no verificadas o pasos que dependan de condiciones externas frágiles.

Para proyectos nuevos, valora si un Dockerfile explícito, una plantilla de repositorio o un generador interno son opciones más claras. Muchas veces es mejor repetir unas líneas visibles que ocultar lógica de build en una imagen base.

En resumen, la instrucción ONBUILD Dockerfile puede ser útil para estandarizar builds, pero debe usarse con moderación. Su mayor ventaja es la reutilización; su mayor riesgo es esconder comportamiento importante.

Lecciones relacionadas del curso Docker

Documentación oficial y recursos

Con esta base, ya puedes decidir si ONBUILD encaja en tu flujo o si es mejor mantener los pasos visibles en cada Dockerfile. Si lo usas, inspecciona la imagen base, fija versiones y evita cualquier comportamiento que sorprenda al equipo durante el build.

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 *