Docker Build Args: la guida definitiva per i data professional

Implicazioni di sicurezza e mitigazione dei rischi

Sebbene gli argomenti di build offrano flessibilità, introducono anche potenziali rischi per la sicurezza che devi conoscere per mantenere sicure le tue immagini Docker.

Vettori di leakage degli argomenti

I build args non sono privati come potresti pensare. I loro valori possono fuoriuscire attraverso vari vettori che molti sviluppatori trascurano. Innanzitutto, la cronologia dell'immagine Docker espone tutti i tuoi build args: chiunque abbia accesso all'immagine può eseguire docker history per vedere i valori usati in fase di build, inclusi potenzialmente informazioni sensibili come chiavi API o token.

docker history flaskapp:devOfferto da

Immagine 4 - Docker history

Anche i layer intermedi possono perdere i build args. Anche se usi una build multi-stage e non copi il layer che contiene informazioni sensibili, i valori dei build args restano nella cache dei layer sulla macchina di build. Ciò significa che chiunque abbia accesso al demone Docker sul tuo server di build potrebbe potenzialmente estrarre queste informazioni.

I log di CI/CD rappresentano un altro rischio significativo. La maggior parte dei sistemi CI/CD registra l'intero comando di build, inclusi eventuali build args passati sulla riga di comando.

Ad esempio, questo comando completo, incluso API_KEY, sarà visibile nei log di CI/CD:

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

Questi log sono spesso accessibili a un gruppo ampio di sviluppatori o persino archiviati in sistemi di terze parti, aumentando la superficie di esposizione di valori sensibili.

Alternative sicure

Per informazioni sensibili, dovresti usare la funzionalità dei secret di Docker BuildKit al posto dei build args. BuildKit ti consente di montare segreti durante il processo di build senza persisterli nell'immagine finale o nella cronologia.

Ecco un esempio di Dockerfile che usa i secret di 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"]Offerto da

Per costruire questa immagine con un secret, crea prima il file api_key.txt:

echo "my-secret-api-key" > api_key.txtOfferto da

Poi costruisci l'immagine con il secret:

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

Immagine 5 - Costruire immagini con i secret di BuildKit

Per configurazioni che devono essere disponibili in runtime, le variabili d'ambiente restano l'approccio preferito. Possono essere impostate all'avvio del container senza essere incorporate nell'immagine:

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

Per gestire in modo sicuro configurazioni sensibili in produzione, valuta l'uso di piattaforme di orchestrazione come Kubernetes, che offrono metodi sicuri come i Secret per gestire informazioni riservate. Anche Docker Swarm offre funzionalità simili con la gestione dei secret.

> Docker non è l'unica piattaforma di containerizzazione. Leggi di Podman per scoprire quale strumento fa più al caso tuo.

Ricorda, la regola pratica è: usa i build args per configurazioni di build non sensibili, usa i secret di BuildKit per esigenze sensibili in build-time, e usa variabili d'ambiente o i secret della piattaforma di orchestrazione per la configurazione in runtime.

Integrazione con gli ecosistemi di container

Tolte di mezzo le basi, vediamo come sfruttare i build args all'interno di ecosistemi Docker più ampi e strumenti di build moderni.

Docker Compose

Docker Compose rende semplice definire e condividere i build args tra le tue applicazioni multi-container.

Se vuoi seguire passo passo, ecco una struttura di progetto completa per due semplici servizi 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 dependenciesOfferto da

Passo velocemente sui contenuti dei file, uno per 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)Offerto da

web/requirements.txt

flask==3.1.0Offerto da

web/Dockerfile

# 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"]Offerto da

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)Offerto da

api/requirements.txt

flask==3.1.0Offerto da

api/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 . .

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

EXPOSE 8000

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

.env

PYTHON_VERSION=3.10
ENVIRONMENT=developmentOfferto da

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"Offerto da

In poche parole, è un modo davvero semplice per avviare due applicazioni in ambienti isolati, entrambe contemporaneamente, entrambe con un set specifico di build args.

Puoi usare questo comando per eseguire il setup multi-container:

docker compose up --buildOfferto da

Immagine 6 - Build args con Docker Compose

Dopo qualche secondo vedrai entrambi i servizi in esecuzione:

Immagine 7 - Build args con Docker Compose (2)

È un setup piuttosto verboso per applicazioni semplici come queste due, ma il succo è chiaro: gli argomenti di build sono impostati nel file compose e referenziati nei singoli Dockerfile.

A margine, puoi anche passare valori di variabili dal tuo ambiente ai build args, cosa utile nelle pipeline CI/CD:

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

E per sovrascrivere questi valori quando esegui docker-compose, puoi usare le variabili d'ambiente:

PYTHON_VERSION=3.10 docker-compose up --buildOfferto da

Questo approccio ti permette di mantenere build coerenti in tutto il team offrendo comunque flessibilità quando necessario.

Funzionalità di BuildKit

BuildKit, il motore di build moderno di Docker, potenzia il processo di build con funzionalità che rendono l'uso dei build args ancora più efficace. Quando abiliti BuildKit (impostando DOCKER_BUILDKIT=1), sblocchi un paio di nuove capacità.

L'inline cache migliora le prestazioni sfruttando la cache di build dell'immagine remota. Puoi specificare un'immagine sorgente da usare come cache con il flag --cache-from, e BuildKit utilizzerà in modo intelligente i layer di quell'immagine:

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

Un'altra funzionalità preziosa di BuildKit sono gli output deterministici, che garantiscono build riproducibili. È fondamentale quando vuoi esattamente la stessa immagine a prescindere da quando o dove venga costruita:

# 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 \
  .Offerto da

L'offuscamento dei secret nei log di BuildKit protegge le informazioni sensibili durante le build. 

A differenza dei normali build args, che compaiono nei log di build, BuildKit nasconde automaticamente i valori dei secret:

# 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 .Offerto da

Nel Dockerfile, accederesti a questo secret con:

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

Queste funzionalità di BuildKit lavorano insieme ai build args per creare un sistema di build più sicuro, efficiente e riproducibile, in grado di adattarsi a praticamente qualsiasi workflow di containerizzazione.

Best practice per l'adozione in azienda

Implementare i build args di Docker in team numerosi richiede approcci standardizzati, almeno se vuoi minimizzare la confusione e massimizzare i benefici in termini di sicurezza e prestazioni.

Quando adotti i build args in ambienti enterprise, parti da una corretta validazione degli argomenti. 

Fornisci sempre valori predefiniti sensati per ogni argomento di build, così le build non falliscono inaspettatamente quando gli argomenti non vengono passati. Dovresti anche aggiungere controlli di validazione nel Dockerfile per verificare che i build args critici soddisfino i requisiti.

Ecco un esempio che valida la versione di 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; \
    fiOfferto da

L'ottimizzazione della cache dei layer è cruciale per ridurre i tempi di build nelle pipeline CI/CD. 

Ordina le istruzioni del Dockerfile per massimizzare i cache hit, mettendo i contenuti che cambiano raramente (come l'installazione delle dipendenze) prima di quelli che cambiano spesso (come il codice applicativo). 

Quando usi build args che potrebbero cambiare spesso, posizionali dopo le operazioni stabili per evitare di invalidare l'intera cache:

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 cacheOfferto da

La gestione dei metadati tramite build args migliora la tracciabilità e la conformità. Usa i build args per iniettare metadati di build come label:

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}"Offerto da

Queste label standard seguono la specifica Open Container Initiative (OCI), quindi le tue immagini saranno compatibili con diversi strumenti di gestione dei container.

La documentazione è spesso trascurata, ma è fondamentale per l'adozione a livello enterprise. 

Crea una chiara sezione README che documenti tutti i build args disponibili, il loro scopo, i valori predefiniti e gli esempi d'uso. Indica quali build args sono obbligatori e quali facoltativi, e documenta eventuali interazioni tra argomenti diversi. Valuta di aggiungere queste informazioni anche nei file di configurazione della pipeline CI/CD come commenti, per aiutare gli sviluppatori a capire quali valori devono fornire:

# 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} .Offerto da

Per un'adozione davvero enterprise, valuta l'implementazione di uno schema degli argomenti di build che possa essere versionato e validato. Questo approccio ti consente di evolvere la configurazione di build nel tempo mantenendo la compatibilità all'indietro.

Analisi comparativa: Build Args vs. Variabili d'ambiente

Se vuoi creare immagini Docker sicure e flessibili che seguano le best practice, devi capire quando usare i build arguments e quando usare le variabili d'ambiente.

Ecco una tabella di riferimento rapido:

La differenza chiave sta nel momento e nello scopo. I build args configurano il processo di build, mentre le variabili d'ambiente configurano l'applicazione in esecuzione. Ad esempio, useresti un build arg per scegliere quale immagine di base usare (ARG PYTHON_VERSION=3.10), ma useresti una variabile d'ambiente per dire alla tua applicazione su quale porta ascoltare (ENV PORT=8080).

Dal punto di vista della sicurezza, i build args sono più rischiosi per informazioni sensibili perché restano nella cronologia dell'immagine. 

Considera questo workflow per gestire diversi tipi di configurazione:

# 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 myimageOfferto da

In pratica, un pattern comune è convertire alcuni build args in variabili d'ambiente quando devono essere disponibili in runtime:

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

Per applicazioni enterprise, questa separazione permette a team diversi di gestire aspetti diversi del ciclo di vita dell'applicazione. I team DevOps possono modificare i build args per la costruzione delle immagini, mentre gli operatori possono regolare le variabili d'ambiente in fase di deploy senza ricostruire le immagini.

Riepilogo sui Docker Build Args

I build args di Docker non sono solo un'altra funzionalità tecnica: sono il tuo strumento di riferimento per creare immagini che funzionano in modo coerente nel tuo team e nei vari ambienti. 

Ti ho mostrato come usarli in semplici progetti Python, mantenendo al contempo al sicuro le informazioni sensibili. Hai visto anche come integrare i build args con strumenti come Docker Compose.

Pensa ai build args come alle fondamenta di una strategia di containerizzazione flessibile. Inizia in piccolo parametrizzando la versione di Python nel tuo prossimo progetto. Quando ti sentirai a tuo agio, prova ad aggiungere logica condizionale per diversi ambienti. In breve tempo, creerai build multi-stage sofisticate che il tuo team potrà personalizzare senza modificare il Dockerfile.

Pronto a fare un passo avanti? Questi corsi di DataCamp sono il prossimo passo ideale:

• Introduzione a Docker
• Docker intermedio
• Concetti di containerizzazione e virtualizzazione
• Containerizzazione e virtualizzazione con Docker e Kubernetes
• CI/CD per il Machine Learning