Build Args

ARG y valores por build

Los argumentos de build permiten parametrizar la construcción de imágenes Docker, haciendo posible personalizar el proceso sin modificar el Dockerfile. La instrucción ARG define variables que están disponibles únicamente durante el proceso de construcción de la imagen.

Definición de argumentos con ARG

La instrucción ARG declara una variable que puede recibir valores externos durante el build. Su sintaxis básica es:

ARG <nombre>
ARG <nombre>=<valor_por_defecto>

Un ejemplo práctico muestra cómo usar argumentos para personalizar versiones de software:

FROM node:18

# Definir argumentos con valores por defecto
ARG APP_VERSION=1.0.0
ARG NODE_ENV=production

# Usar los argumentos en el build
LABEL version=${APP_VERSION}
LABEL environment=${NODE_ENV}

WORKDIR /app
COPY package*.json ./
RUN npm install --only=${NODE_ENV}

COPY . .
EXPOSE 3000
CMD ["npm", "start"]

Paso de valores con --build-arg

Los valores de los argumentos se proporcionan durante el build usando la opción --build-arg:

docker build --build-arg APP_VERSION=2.1.0 --build-arg NODE_ENV=development -t myapp:dev .

Si no se proporciona un valor para un argumento que tiene valor por defecto, se usará el valor predefinido. Los argumentos sin valor por defecto deben ser proporcionados explícitamente o quedarán vacíos.

Casos de uso prácticos

Los argumentos de build son especialmente útiles para configurar versiones base y parámetros de construcción:

# Dockerfile para aplicación Python con versión configurable
ARG PYTHON_VERSION=3.11
ARG REQUIREMENTS_FILE=requirements.txt

FROM python:${PYTHON_VERSION}-slim

ARG APP_USER=appuser
ARG APP_DIR=/app

# Crear usuario no privilegiado
RUN useradd -m ${APP_USER}

WORKDIR ${APP_DIR}
COPY ${REQUIREMENTS_FILE} .
RUN pip install -r ${REQUIREMENTS_FILE}

USER ${APP_USER}
COPY --chown=${APP_USER}:${APP_USER} . .

CMD ["python", "app.py"]

Para construir esta imagen con diferentes configuraciones:

# Build para desarrollo con Python 3.12
docker build --build-arg PYTHON_VERSION=3.12 --build-arg REQUIREMENTS_FILE=requirements-dev.txt -t myapp:dev .

# Build para producción con configuración por defecto
docker build -t myapp:prod .

Configuración de proxies y redes corporativas

Los argumentos son fundamentales para builds en entornos corporativos con proxies:

FROM nginx:alpine

# Argumentos para configuración de proxy
ARG HTTP_PROXY
ARG HTTPS_PROXY
ARG NO_PROXY=localhost,127.0.0.1

# Configurar proxy si se proporciona
RUN if [ -n "${HTTP_PROXY}" ]; then \
        echo "Acquire::http::Proxy \"${HTTP_PROXY}\";" > /etc/apt/apt.conf.d/proxy; \
    fi

# Instalar paquetes adicionales
RUN apk add --no-cache curl

# Copiar configuración personalizada
COPY nginx.conf /etc/nginx/nginx.conf

Build con configuración de proxy:

docker build \
  --build-arg HTTP_PROXY=http://proxy.company.com:8080 \
  --build-arg HTTPS_PROXY=http://proxy.company.com:8080 \
  --build-arg NO_PROXY=localhost,127.0.0.1,.company.com \
  -t nginx-corporate .

Alcance y disponibilidad de ARG

Los argumentos tienen un alcance limitado al proceso de build y no están disponibles en el contenedor en ejecución. Su disponibilidad depende de su posición en el Dockerfile:

# ARG antes del primer FROM - disponible para FROM
ARG BASE_IMAGE=postgres:15

FROM ${BASE_IMAGE}

# ARG después de FROM - disponible solo en este stage
ARG DB_VERSION=15.5
ARG POSTGRES_DB=myapp

# Usar argumentos para configurar la imagen
ENV POSTGRES_DB=${POSTGRES_DB}
LABEL postgresql.version=${DB_VERSION}

# Crear directorio con nombre basado en argumento
RUN mkdir -p /data/${POSTGRES_DB}

Buenas prácticas con argumentos

Al trabajar con argumentos de build, es recomendable proporcionar valores por defecto sensatos:

# Definir argumentos con valores razonables
ARG USER_ID=1000
ARG GROUP_ID=1000
ARG WORKDIR=/app

FROM alpine:latest

# Crear usuario con IDs configurables
RUN addgroup -g ${GROUP_ID} appgroup && \
    adduser -D -u ${USER_ID} -G appgroup appuser

WORKDIR ${WORKDIR}
RUN chown appuser:appgroup ${WORKDIR}

USER appuser

Esta configuración permite adaptar los IDs de usuario para evitar conflictos de permisos en diferentes entornos:

# Build con IDs específicos del host
docker build --build-arg USER_ID=$(id -u) --build-arg GROUP_ID=$(id -g) -t myapp .

Los argumentos de build proporcionan la flexibilidad necesaria para crear imágenes adaptables a diferentes entornos y requisitos, manteniendo un único Dockerfile que puede servir múltiples propósitos mediante parametrización externa.

Diferencia ARG vs ENV

La distinción entre ARG y ENV es fundamental para entender cuándo y dónde están disponibles las variables en el ciclo de vida de una imagen Docker. Ambas instrucciones manejan variables, pero operan en momentos completamente diferentes.

Disponibilidad temporal

La diferencia más importante radica en cuándo están disponibles estas variables:

FROM nginx:alpine

# ARG: solo durante el build
ARG BUILD_VERSION=1.0.0
ARG API_URL=https://api.example.com

# ENV: durante build Y runtime
ENV APP_ENV=production
ENV LOG_LEVEL=info

# Usar ARG para decisiones de build
RUN echo "Building version: ${BUILD_VERSION}" > /tmp/build.log

# Usar ENV para configuración runtime
RUN echo "export LOG_LEVEL=${LOG_LEVEL}" >> /etc/profile

# ARG se puede usar para definir ENV
ENV VERSION=${BUILD_VERSION}

Al ejecutar este build y después inspeccionar el contenedor:

# Durante el build, ambas están disponibles
docker build --build-arg BUILD_VERSION=2.1.0 -t myapp .

# En runtime, solo ENV está disponible
docker run myapp env | grep -E "(BUILD_VERSION|APP_ENV|VERSION)"
# Resultado: APP_ENV=production, VERSION=2.1.0
# BUILD_VERSION no aparece

Persistencia en la imagen

Las variables ENV se almacenan en los metadatos de la imagen, mientras que ARG no persisten:

FROM postgres:15

ARG POSTGRES_VERSION=15.5
ARG BUILD_DATE

# ENV persiste en el contenedor
ENV POSTGRES_DB=myapp
ENV POSTGRES_USER=appuser

# ARG solo para build-time
RUN echo "PostgreSQL ${POSTGRES_VERSION} built on ${BUILD_DATE}" > /var/lib/postgresql/build-info.txt

# Transferir ARG a ENV si necesitas persistencia
ENV DB_VERSION=${POSTGRES_VERSION}

Sobrescritura y configuración

Ambas instrucciones permiten sobrescritura, pero con mecanismos diferentes:

# Sobrescribir ARG durante el build
docker build \
  --build-arg POSTGRES_VERSION=16.1 \
  --build-arg BUILD_DATE=$(date -u +%Y%m%d) \
  -t mypostgres .

# Sobrescribir ENV durante la ejecución
docker run -e POSTGRES_DB=newdb -e LOG_LEVEL=debug mypostgres

Casos de uso específicos

ARG es ideal para configuraciones que afectan la construcción:

FROM node:18-alpine

# Configuraciones de build que no necesitan persistir
ARG NODE_ENV=production
ARG SKIP_TESTS=false

WORKDIR /app
COPY package*.json ./

# Instalar dependencias según el entorno
RUN if [ "${NODE_ENV}" = "development" ]; then \
        npm install; \
    else \
        npm ci --only=production; \
    fi

# Ejecutar tests condicionalmente
RUN if [ "${SKIP_TESTS}" = "false" ]; then \
        npm test; \
    fi

# ENV para configuración runtime
ENV NODE_ENV=production
ENV PORT=3000

COPY . .
EXPOSE ${PORT}
CMD ["npm", "start"]

ENV es ideal para configuraciones que necesita la aplicación en ejecución:

FROM nginx:alpine

# Configuración que la aplicación necesitará
ENV NGINX_HOST=localhost
ENV NGINX_PORT=80
ENV CLIENT_MAX_BODY_SIZE=1m

# Crear configuración dinámica usando ENV
RUN envsubst '${NGINX_HOST} ${NGINX_PORT} ${CLIENT_MAX_BODY_SIZE}' \
    < /etc/nginx/templates/default.conf.template \
    > /etc/nginx/conf.d/default.conf

Seguridad y visibilidad

Un aspecto crítico es que ENV es visible en el contenedor en ejecución, mientras que ARG no persiste:

FROM alpine:latest

# ARG no aparece en el contenedor final
ARG API_SECRET=default-secret

# ENV será visible con 'docker inspect' y 'env'
ENV PUBLIC_CONFIG=visible-config

# Usar ARG para operaciones sensibles en build
RUN wget --header="Authorization: Bearer ${API_SECRET}" \
    https://api.example.com/config -O /tmp/config.json && \
    rm -f /tmp/sensitive-data

# ENV para configuración no sensible
ENV APP_NAME=myapp

Interacción entre ARG y ENV

ARG puede inicializar valores de ENV, creando un patrón útil para configuraciones flexibles:

FROM mysql:8.0

# ARG para personalización durante build
ARG MYSQL_DATABASE=myapp
ARG MYSQL_USER=appuser
ARG MYSQL_ROOT_PASSWORD

# ENV para runtime, inicializadas desde ARG
ENV MYSQL_DATABASE=${MYSQL_DATABASE}
ENV MYSQL_USER=${MYSQL_USER}
ENV MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}

# Configuración adicional solo para build
ARG INIT_SCRIPTS=./sql/*.sql
COPY ${INIT_SCRIPTS} /docker-entrypoint-initdb.d/

Esta configuración permite tanto personalización en build como configuración en runtime:

# Personalizar durante build
docker build --build-arg MYSQL_DATABASE=production --build-arg MYSQL_ROOT_PASSWORD=secret123 -t mydb .

# Sobrescribir durante ejecución si es necesario
docker run -e MYSQL_ROOT_PASSWORD=newsecret mydb

La regla fundamental es simple: ARG para decisiones de construcción, ENV para configuración de aplicación. Esta distinción garantiza que las imágenes contengan solo la información necesaria para su ejecución, mientras permiten flexibilidad durante el proceso de build.