Args de compilación de Docker: La guía definitiva para los profesionales de los datos

Implicaciones de seguridad y mitigación de riesgos

Aunque los argumentos de compilación ofrecen flexibilidad, también introducen riesgos potenciales de seguridad que debes comprender para mantener seguras tus imágenes Docker.

Vectores de fuga de argumentos

Las discusiones de construcción no son tan privadas como podrías pensar. Los valores de los argumentos de compilación pueden filtrarse a través de varios vectores que muchos programadores pasan por alto. En primer lugar, elhistorial de imágenes Dockerde expone todos tus argumentos de compilación, lo que significa que cualquiera con acceso a tu imagen puede ejecutar docker history para ver los valores que utilizaste durante la compilación, incluida información potencialmente sensible como claves de API o tokens.

docker history flaskapp:dev

Imagen 4 - Historia de Docker

Las capas intermedias también pueden filtrar argumentos de construcción. Aunque utilices una construcción en varias fases y no copies la capa que contiene información sensible, los valores arg de la construcción permanecen en la caché de capas de la máquina de construcción. Esto significa que cualquiera con acceso al demonio Docker de tu servidor de compilación podría extraer potencialmente esta información.

Los registros CI/CD plantean otro riesgo importante. La mayoría de los sistemas CI/CD registran la orden de compilación completa, incluidos los argumentos de compilación pasados en la línea de comandos.

Por ejemplo, todo este comando, incluido API_KEY, será visible en los registros de CI/CD:

docker build --build-arg API_KEY=secret123 -t myapp:latest .

A menudo, estos registros son accesibles a un grupo más amplio de programadores o incluso se almacenan en sistemas de terceros, lo que aumenta la superficie de exposición de los valores sensibles.

Alternativas seguras

Para la información sensible, debes utilizar la función secretos de Docker BuildKit en lugar de los argumentos de compilación. BuildKit te permite montar secretos durante el proceso de construcción sin que persistan en la imagen final o en el historial.

Aquí tienes un ejemplo de Dockerfile que utiliza los secretos de Docker BuildKit:

FROM python:3.13-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .

# Use secret mount instead of build arg
RUN --mount=type=secret,id=api_key \
    cat /run/secrets/api_key > api_key.txt

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

Para construir esta imagen con un secreto, crea primero el archivo api_key.txt:

echo "my-secret-api-key" > api_key.txt

Y luego construye la imagen con el secreto:

DOCKER_BUILDKIT=1 docker build \
  --secret id=api_key,src=api_key.txt \
  -t flaskapp:secure .

Imagen 5 - Construir imágenes con los secretos de BuildKit

Para la configuración que debe estar disponible en tiempo de ejecución, las variables de entorno siguen siendo el enfoque preferido. Se pueden establecer al iniciar un contenedor sin que se incorporen a la imagen:

# Set environment variables at runtime
docker run -e API_KEY=secret123 -p 5000:5000 flaskapp:latest

Para manejar con seguridad la configuración sensible en producción, considera el uso de plataformas de orquestación de contenedores como Kubernetes, que proporcionan métodos seguros como Secrets para gestionar la información sensible. Docker Swarm también ofrece capacidades similares con su gestión de secretos.

> Docker no es la única plataforma de contenerización. Lee sobre Podman para saber qué herramienta se adapta mejor a ti.

Recuerda, la regla general es: utiliza argumentos de compilación para la configuración en tiempo de compilación que no sea sensible, utiliza secretos de BuildKit para las necesidades sensibles en tiempo de compilación, y utiliza variables de entorno o secretos de plataforma de orquestación para la configuración en tiempo de ejecución.

Integración con ecosistemas de contenedores

Una vez aclarados los conceptos básicos, vamos a explorar cómo aprovechar los argumentos de construcción dentro de ecosistemas Docker más amplios y herramientas de construcción modernas.

Componer Docker

Docker Compose facilita la definición y el uso compartido de argumentos de compilación en tus aplicaciones multicontenedor.

Si quieres seguirnos, aquí tienes una estructura de proyecto completa para dos sencillos servicios Flask:

flask-project/
├── docker-compose.yml         # Main compose configuration
├── .env                       # Environment variables for compose
├── web/
│   ├── Dockerfile             # Web service Dockerfile
│   ├── app.py                 # Flask application
│   └── requirements.txt       # Python dependencies
├── api/
│   ├── Dockerfile             # API service Dockerfile
│   ├── app.py                 # API Flask application  
│   └── requirements.txt       # API dependencies

Repasaré rápidamente el contenido del archivo uno por uno:

web/app.py

from flask import Flask, render_template

app = Flask(__name__)


@app.route("/")
def index():
    return render_template("index.html", title="Flask Web App")


@app.route("/about")
def about():
    return "About page - Web Service"


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=5000, debug=True)

web/requisitos.txt

flask==3.1.0

web/Fichero del muelle

# Web service Dockerfile
ARG PYTHON_VERSION=3.13

FROM python:${PYTHON_VERSION}-slim

# Redeclare the build arg to use it after FROM
ARG PYTHON_VERSION
ARG ENVIRONMENT=production

# Set environment variables
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1
ENV FLASK_ENV=${ENVIRONMENT}

WORKDIR /app

# Copy and install requirements
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application code
COPY . .

# Create a simple template folder and file if not exists
RUN mkdir -p templates && \
    echo "<html><body><h1>Hello from Web Service</h1><p>Python version: ${PYTHON_VERSION}</p><p>Environment: ${ENVIRONMENT}</p></body></html>" > templates/index.html

EXPOSE 5000

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

api/app.py

from flask import Flask, jsonify

app = Flask(__name__)


@app.route("/api/health")
def health():
    return jsonify({"status": "healthy"})


@app.route("/api/data")
def get_data():
    return jsonify(
        {"message": "Hello from the API service", "items": ["item1", "item2", "item3"]}
    )


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=8000, debug=True)

api/requirements.txt

flask==3.1.0

api/Fichero del muelle

ARG PYTHON_VERSION=3.13

FROM python:${PYTHON_VERSION}-slim

# Redeclare the build arg to use it after FROM
ARG PYTHON_VERSION
ARG ENVIRONMENT=production

# Set environment variables
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1
ENV FLASK_ENV=${ENVIRONMENT}

WORKDIR /app

# Copy and install requirements
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application code
COPY . .

# Add metadata label based on build args
LABEL python.version="${PYTHON_VERSION}" \
      app.environment="${ENVIRONMENT}"

EXPOSE 8000

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

.env

PYTHON_VERSION=3.10
ENVIRONMENT=development

docker-compose.yml

services:
  web:
    build:
      context: ./web
      dockerfile: Dockerfile
      args:
        PYTHON_VERSION: ${PYTHON_VERSION:-3.13}
        ENVIRONMENT: ${ENVIRONMENT:-development}
    ports:
      - "5000:5000"
    depends_on:
      - api
    
  api:
    build:
      context: ./api
      dockerfile: Dockerfile
      args:
        PYTHON_VERSION: ${PYTHON_VERSION:-3.13}
        ENVIRONMENT: ${ENVIRONMENT:-production}
    ports:
      - "8000:8000"

En pocas palabras, se trata de una forma realmente sencilla de iniciar dos aplicaciones en entornos aislados, ambas al mismo tiempo, ambas con un conjunto específico de argumentos de compilación.

Puedes utilizar este comando para ejecutar la configuración multicontenedor:

docker compose up --build

Imagen 6 - Construye argumentos con Docker Compose

Tras un par de segundos, verás que ambos servicios se están ejecutando:

Imagen 7 - Construye argumentos con Docker Compose (2)

Es una configuración bastante prolija para aplicaciones tan sencillas como estas dos, pero puedes hacerte una idea general: los argumentos de construcción se establecen en el archivo de composición y se hace referencia a ellos en archivos Docker individuales.

Como nota al margen, también puedes pasar valores variables de tu entorno a los argumentos de construcción, lo que resulta útil para las canalizaciones CI/CD:

services:
  web:
    build:
      context: .
      args:
        - PYTHON_VERSION=${PYTHON_VERSION:-3.10}

Y para anular estos valores al ejecutar docker-compose, puedes utilizar variables de entorno:

PYTHON_VERSION=3.10 docker-compose up --build

Este enfoque te permite mantener construcciones coherentes en todo tu equipo, sin dejar de ofrecer flexibilidad cuando sea necesario.

Funciones de BuildKit

BuildKit, el moderno motor de compilación de Docker, potencia tu proceso de compilación con funciones que hacen que el uso de argumentos de compilación sea mucho más potente. Cuando activas BuildKit (configurando DOCKER_BUILDKIT=1), desbloqueas un par de nuevas capacidades.

La caché en línea mejora el rendimiento de la compilación aprovechando la caché de compilación de la imagen remota. Puedes especificar una imagen de origen para utilizarla como caché con la bandera --cache-from, y BuildKit utilizará inteligentemente las capas de esa imagen:

DOCKER_BUILDKIT=1 docker build \
  --build-arg PYTHON_VERSION=3.10 \
  --cache-from flaskapp:dev \
  -t flaskapp:latest .

Otra valiosa función de BuildKit son las salidas deterministas, que garantizan que tus construcciones sean reproducibles. Esto es crucial cuando quieres exactamente la misma imagen independientemente de cuándo o dónde se construya:

# Build with deterministic output
DOCKER_BUILDKIT=1 docker build \
  --build-arg PYTHON_VERSION=3.10 \
  --build-arg BUILD_DATE=2025-05-01 \
  --output type=docker,name=flaskapp:stable \
  .

La redacción secreta de BuildKit en los registros protege la información sensible durante las construcciones. 

A diferencia de los argumentos de construcción normales, que aparecen en los registros de construcción, BuildKit oculta automáticamente los valores de los secretos:

# Create a file with the API key
echo "my-api-key-value" > ./api-key.txt

# Build with secret (value won't appear in logs)
DOCKER_BUILDKIT=1 docker build \
  --secret id=api_key,src=./api-key.txt \
  -t flaskapp:secure .

En tu Dockerfile, accederías a este secreto con:

RUN --mount=type=secret,id=api_key \
    cat /run/secrets/api_key > /app/config/api_key.txt

Estas funciones de BuildKit funcionan junto con los argumentos de compilación para crear un sistema de compilación más seguro, eficiente y reproducible que puede adaptarse a prácticamente cualquier flujo de trabajo de contenedorización.

Buenas prácticas para la adopción empresarial

Implementar argumentos de construcción de Docker en grandes equipos requiere enfoques estandarizados, al menos si quieres minimizar la confusión y maximizar las ventajas de seguridad y rendimiento.

Cuando adoptes argumentos de construcción en entornos empresariales, empieza por una validación adecuada de los argumentos. 

Proporciona siempre valores por defecto razonables para cada argumento de compilación, a fin de garantizar que la compilación no falle inesperadamente si no se pasan los argumentos. También debes añadir comprobaciones de validación dentro de tu Dockerfile para verificar que los args de compilación críticos cumplen tus requisitos.

Aquí tienes un ejemplo que valida la versión de Python:

ARG PYTHON_VERSION=3.9
# Validate Python version
RUN if [[ ! "$PYTHON_VERSION" =~ ^3\.[0-9]+$ ]]; then \
      echo "Invalid Python version: ${PYTHON_VERSION}. Must be 3.x"; \
      exit 1; \
    fi

La optimización de la caché de capas es crucial para reducir los tiempos de compilación en los pipelines CI/CD. 

Ordena las instrucciones de tu Dockerfile para maximizar las visitas a la caché colocando el contenido que cambia raramente (como la instalación de dependencias) antes del contenido que cambia con frecuencia (como el código de la aplicación). 

Cuando utilices argumentos de construcción que puedan cambiar a menudo, colócalos después de operaciones estables para evitar invalidar toda la caché:

FROM python:3.13-slim

WORKDIR /app

# Dependencies change less frequently - good cache utilization
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Build args that might change often come AFTER stable operations
ARG BUILD_NUMBER
ARG COMMIT_SHA
# Now these args won't invalidate the dependency cache

La gestión de metadatos mediante argumentos de construcción mejora la trazabilidad y el cumplimiento. Utiliza argumentos de compilación para inyectar metadatos de compilación como etiquetas:

ARG BUILD_DATE
ARG VERSION
ARG COMMIT_SHA
ARG BUILD_URL

LABEL org.opencontainers.image.created="${BUILD_DATE}" Can you please provide me with access to this document?
      org.opencontainers.image.version="${VERSION}" \
      org.opencontainers.image.revision="${COMMIT_SHA}" \
      org.opencontainers.image.url="${BUILD_URL}"

Estas etiquetas estandarizadas siguen la especificación Open Container Initiative (OCI), lo que significa que tus imágenes serán compatibles con distintas herramientas de gestión de contenedores.

A menudo se pasa por alto la documentación, pero es fundamental para la adopción empresarial. 

Crea una sección clara en README que documente todos los argumentos de construcción disponibles, su finalidad, valores por defecto y ejemplos de uso. Incluye qué argumentos de construcción son obligatorios y cuáles opcionales, y documenta cualquier interacción entre los distintos argumentos. Considera también la posibilidad de añadir esta información a los archivos de configuración de tu canalización CI/CD en forma de comentarios, para ayudar a los programadores a comprender qué valores deben proporcionar:

# Example documented CI configuration
build_job:
  script:
    # BUILD_NUMBER: Unique identifier for this build (required)
    # ENVIRONMENT: Target deployment environment [dev|staging|prod] (required)
    # PYTHON_VERSION: Python version to use (optional, default: 3.9)
    - docker build
      --build-arg BUILD_NUMBER=${CI_PIPELINE_ID}
      --build-arg ENVIRONMENT=${DEPLOY_ENV}
      --build-arg PYTHON_VERSION=${PYTHON_VERSION:-3.9}
      -t myapp:${CI_PIPELINE_ID} .

Para una adopción verdaderamente empresarial, considera la posibilidad de implantar un esquema de argumentos de construcción que pueda versionarse y validarse. Este enfoque te permite hacer evolucionar tu configuración de compilación con el tiempo, manteniendo la compatibilidad con versiones anteriores.

Análisis comparativo: Construir Args vs. Variables de entorno

Si quieres crear imágenes Docker seguras y flexibles que sigan las mejores prácticas, debes entender cuándo utilizar argumentos de compilación y cuándo utilizar variables de entorno.

Aquí tienes una tabla que puedes consultar en cualquier momento:

La diferencia clavediferencia radica en el momento y la finalidad. Los argumentos de construcción configuran el propio proceso de construcción, mientras que las variables de entorno configuran la aplicación en ejecución. Por ejemplo, utilizarías un argumento de compilación para seleccionar qué imagen base utilizar (ARG PYTHON_VERSION=3.10), pero utilizarías una variable de entorno para indicar a tu aplicación en qué puerto debe escuchar (ENV PORT=8080).

Desde el punto de vista de la seguridad los argumentos de construcción suponen un mayor riesgo para la información sensible porque permanecen en el historial de imágenes.

Considera este flujo de trabajo para manejar distintos tipos de configuración:

# Build-time configuration (non-sensitive)
ARG PYTHON_VERSION=3.13
FROM python:${PYTHON_VERSION}-slim

# Build-time secrets (use BuildKit secrets)
RUN --mount=type=secret,id=build_key \
    cat /run/secrets/build_key > /tmp/key && \
    # Use the secret for build operations
    rm /tmp/key

# Runtime configuration (non-sensitive)
ENV LOG_LEVEL=info

# Runtime secrets (should be injected at runtime, not here)
# This would be provided at runtime with:
# docker run -e API_KEY=secret123 myimage

En la práctica, un patrón común es convertir los argumentos de construcción seleccionados en variables de entorno cuando necesitan estar disponibles en tiempo de ejecución:

ARG APP_VERSION=1.0.0
# Make the version available at runtime
ENV APP_VERSION=${APP_VERSION}

Para las aplicaciones empresariales, la separación permite que distintos equipos gestionen diferentes aspectos del ciclo de vida de la aplicación. Los equiposDevOpspueden modificar los argumentos de compilación para la construcción de imágenes, mientras que los operadores pueden ajustar las variables de entorno durante el despliegue sin reconstruir las imágenes.

Resumiendo Docker Build Args

Los argumentos de compilación de Docker no son sólo una característica técnica más: son tu herramienta de referencia para crear imágenes que funcionen de forma coherente en todo tu equipo y entornos. 

He explicado cómo utilizarlos en proyectos sencillos de Python, manteniendo a salvo tu información confidencial. También has visto cómo integrar argumentos de construcción con herramientas como Docker Compose.

Piensa en los argumentos de construcción como la base de una estrategia flexible de contenedorización. Empieza poco a poco parametrizando tu versión de Python en tu próximo proyecto. Cuando te sientas cómodo, prueba a añadir lógica condicional para distintos entornos. Antes de que te des cuenta, crearás sofisticadas compilaciones multietapa que tu equipo podrá personalizar sin modificar el archivo Dockerfile.

¿Preparado para profundizar? Estos cursos de DataCamp son tu mejor próxima parada:

• Introducción a Docker
• Docker intermedio
• Conceptos de contenedorización y virtualización
• Containerización y virtualización con Docker y Kubernetes
• CI/CD para el machine learning