Docker Build Args: De ultieme gids voor dataprofessionals

Beveiligingsimplicaties en risicobeperking

Hoewel build-argumenten flexibiliteit bieden, introduceren ze ook potentiële beveiligingsrisico's die je moet begrijpen om je Docker-images veilig te houden.

Kanalen voor uitlekken van argumenten

Build-argumenten zijn niet zo privé als je misschien denkt. De waarden van build-argumenten kunnen lekken via verschillende kanalen die veel ontwikkelaars over het hoofd zien. Ten eerste onthult de Docker-imagegeschiedenis al je build-argumenten. Iedereen met toegang tot je image kan docker history uitvoeren om de waarden te zien die je tijdens de build hebt gebruikt, inclusief mogelijk gevoelige informatie zoals API-sleutels of tokens.

docker history flaskapp:devMogelijk gemaakt door

Afbeelding 4 - Docker history

Tussentijdse lagen kunnen ook build-argumenten lekken. Zelfs als je een multistage-build gebruikt en de laag met gevoelige informatie niet kopieert, blijven de waarden van build-argumenten in de layercache op de buildmachine. Dat betekent dat iedereen met toegang tot de Docker-daemon op je buildserver deze informatie mogelijk kan achterhalen.

CI/CD-logs vormen een ander aanzienlijk risico. De meeste CI/CD-systemen loggen het volledige build-commando, inclusief eventuele build-argumenten die via de commandoregel zijn doorgegeven.

Dit volledige commando, inclusief API_KEY, is bijvoorbeeld zichtbaar in CI/CD-logs:

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

Deze logs zijn vaak toegankelijk voor een bredere groep ontwikkelaars of zelfs opgeslagen bij derden, wat het aanvalsoppervlak van gevoelige waarden vergroot.

Veilige alternatieven

Voor gevoelige informatie moet je de secretsfunctie van Docker BuildKit gebruiken in plaats van build-argumenten. BuildKit laat je secrets mounten tijdens het buildproces zonder ze te bewaren in de uiteindelijke image of de geschiedenis.

Hier is een voorbeeld-Dockerfile die Docker BuildKit-secrets gebruikt:

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"]Mogelijk gemaakt door

Om deze image met een secret te bouwen, maak je eerst het bestand api_key.txt aan:

echo "my-secret-api-key" > api_key.txtMogelijk gemaakt door

En bouw vervolgens de image met het secret:

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

Afbeelding 5 - Images bouwen met BuildKit-secrets

Voor configuratie die tijdens runtime beschikbaar moet zijn, blijven omgevingsvariabelen de voorkeursaanpak. Je kunt ze instellen wanneer je een container start, zonder ze in de image te bakken:

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

Om gevoelige configuratie in productie veilig te verwerken, kun je overwegen om containerorkestratieplatforms zoals Kubernetes te gebruiken, die veilige methoden zoals Secrets bieden voor het beheren van gevoelige informatie. Docker Swarm biedt vergelijkbare mogelijkheden met zijn secretsbeheer.

> Docker is niet het enige containerisatieplatform. Lees over Podman om te bepalen welk hulpmiddel beter bij je past.

Onthoud de vuistregel: gebruik build-argumenten voor build-time configuratie die niet gevoelig is, gebruik BuildKit-secrets voor gevoelige behoeften tijdens het bouwen, en gebruik omgevingsvariabelen of secrets van je orkestratieplatform voor runtimeconfiguratie.

Integratie met container-ecosystemen

Nu de basis duidelijk is, gaan we bekijken hoe je build-argumenten benut binnen bredere Docker-ecosystemen en moderne buildtools.

Docker Compose

Docker Compose maakt het eenvoudig om build-argumenten te definiëren en te delen over je multi-containerapplicaties.

Als je wilt meedoen, is hier een complete projectstructuur voor twee eenvoudige Flask-services:

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 dependenciesMogelijk gemaakt door

Ik loop snel de bestandsinhoud één voor één door:

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)Mogelijk gemaakt door

web/requirements.txt

flask==3.1.0Mogelijk gemaakt door

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"]Mogelijk gemaakt door

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)Mogelijk gemaakt door

api/requirements.txt

flask==3.1.0Mogelijk gemaakt door

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"]Mogelijk gemaakt door

.env

PYTHON_VERSION=3.10
ENVIRONMENT=developmentMogelijk gemaakt door

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"Mogelijk gemaakt door

Kort gezegd is dit een heel eenvoudige manier om twee applicaties in geïsoleerde omgevingen tegelijk te starten, beide met een specifieke set build-argumenten.

Je kunt dit commando gebruiken om de multi-containersetup te draaien:

docker compose up --buildMogelijk gemaakt door

Afbeelding 6 - Build-argumenten met Docker Compose

Na een paar seconden zie je dat beide services draaien:

Afbeelding 7 - Build-argumenten met Docker Compose (2)

Het is best een breedsprakige setup voor twee zulke simpele apps, maar je ziet het grote plaatje: build-argumenten staan in het compose-bestand en worden in de afzonderlijke Dockerfiles gebruikt.

Terzijde: je kunt ook variabele waarden uit je omgeving doorgeven aan build-argumenten, wat handig is voor CI/CD-pijplijnen:

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

En om deze waarden te overschrijven wanneer je docker-compose draait, kun je omgevingsvariabelen gebruiken:

PYTHON_VERSION=3.10 docker-compose up --buildMogelijk gemaakt door

Met deze aanpak behoud je consistente builds binnen je team, terwijl je toch flexibiliteit hebt wanneer dat nodig is.

BuildKit-functies

BuildKit, de moderne build-engine van Docker, geeft je buildproces een boost met functies die het gebruik van build-argumenten nog krachtiger maken. Wanneer je BuildKit inschakelt (door DOCKER_BUILDKIT=1 te zetten), ontgrendel je een aantal nieuwe mogelijkheden.

Inline cache verbetert de buildprestaties door de buildcache van een remote image te gebruiken. Je kunt met de vlag --cache-from een bronimage als cache opgeven, en BuildKit gebruikt die lagen vervolgens slim:

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

Een andere waardevolle BuildKit-functie is deterministische output, die ervoor zorgt dat je builds reproduceerbaar zijn. Dat is cruciaal wanneer je exact dezelfde image wilt, ongeacht wanneer of waar die gebouwd is:

# 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 \
  .Mogelijk gemaakt door

BuildKit's redactie van secrets in logs beschermt gevoelige informatie tijdens builds. 

In tegenstelling tot gewone build-argumenten, die in buildlogs verschijnen, verbergt BuildKit automatisch de waarden van secrets:

# 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 .Mogelijk gemaakt door

In je Dockerfile krijg je toegang tot dit secret met:

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

Deze BuildKit-functies werken samen met build-argumenten om een veiliger, efficiënter en reproduceerbaar buildsystem te creëren dat zich kan aanpassen aan vrijwel elke containerworkflow.

Best practices voor enterprise-adoptie

Het implementeren van Docker-buildargumenten in grote teams vereist gestandaardiseerde aanpakken, tenminste als je verwarring wilt minimaliseren en de beveiligings- en prestatiewinst wilt maximaliseren.

Begin bij adoptie van build-argumenten in enterprise-omgevingen met juiste validatie van argumenten. 

Geef altijd verstandige standaardwaarden voor elk build-argument, zodat builds niet onverwacht falen wanneer argumenten niet worden doorgegeven. Voeg ook validatiechecks toe in je Dockerfile om te verifiëren dat kritieke build-argumenten aan je eisen voldoen.

Hier is een voorbeeld dat de Python-versie valideert:

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; \
    fiMogelijk gemaakt door

Optimalisatie van layercaching is cruciaal om buildtijden in CI/CD-pijplijnen te verkorten. 

Orden je Dockerfile-instructies om cachehits te maximaliseren door zelden veranderende content (zoals het installeren van dependencies) vóór vaak veranderende content (zoals applicatiecode) te plaatsen. 

Als je build-argumenten gebruikt die vaak kunnen wijzigen, plaats ze dan na stabiele stappen om te voorkomen dat je de hele cache ongeldig maakt:

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 cacheMogelijk gemaakt door

Metadatabeheer via build-argumenten verbetert traceerbaarheid en compliance. Gebruik build-argumenten om build-time metadata als labels in te voegen:

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}"Mogelijk gemaakt door

Deze gestandaardiseerde labels volgen de specificatie van de Open Container Initiative (OCI), wat betekent dat je images compatibel zijn met verschillende containermanagementtools.

Documentatie wordt vaak over het hoofd gezien, maar is cruciaal voor enterprise-adoptie. 

Maak een duidelijke README-sectie die alle beschikbare build-argumenten documenteert, met hun doel, standaardwaarden en gebruiksvoorbeelden. Vermeld welke build-argumenten verplicht zijn en welke optioneel, en documenteer eventuele interacties tussen verschillende argumenten. Overweeg om deze informatie ook als commentaar toe te voegen aan je CI/CD-pijplijnconfiguratiebestanden, zodat ontwikkelaars begrijpen welke waarden ze moeten aanleveren:

# 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} .Mogelijk gemaakt door

Voor echte enterprise-grade adoptie kun je overwegen een schema voor build-argumenten te implementeren dat versieerbaar en valideerbaar is. Zo kun je je buildconfiguratie in de tijd doorontwikkelen en toch backward compatible blijven.

Vergelijkende analyse: Build-argumenten vs. omgevingsvariabelen

Als je veilige en flexibele Docker-images wilt maken die best practices volgen, moet je begrijpen wanneer je build-argumenten gebruikt en wanneer omgevingsvariabelen.

Hier is een tabel waar je altijd op kunt terugvallen:

Het belangrijkste verschil zit in timing en doel. Build-argumenten configureren het buildproces zelf, terwijl omgevingsvariabelen de draaiende applicatie configureren. Je gebruikt bijvoorbeeld een build-argument om te kiezen welk basisimage je gebruikt (ARG PYTHON_VERSION=3.10), maar een omgevingsvariabele om je applicatie te vertellen op welke poort die moet luisteren (ENV PORT=8080).

Vanuit beveiligingsperspectief vormen build-argumenten een hoger risico voor gevoelige informatie, omdat ze in de imagegeschiedenis achterblijven. 

Overweeg deze workflow voor het afhandelen van verschillende soorten configuratie:

# 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 myimageMogelijk gemaakt door

In de praktijk is een veelvoorkomend patroon om geselecteerde build-argumenten om te zetten naar omgevingsvariabelen wanneer ze tijdens runtime beschikbaar moeten zijn:

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

Voor enterprise-applicaties maakt deze scheiding het mogelijk dat verschillende teams verschillende aspecten van de levenscyclus beheren. DevOps-teams kunnen build-argumenten aanpassen voor de imageconstructie, terwijl operators omgevingsvariabelen kunnen bijstellen tijdens deployment zonder images opnieuw te bouwen.

Samenvatting van Docker Build Args

Docker-buildargumenten zijn niet zomaar een technische feature - het zijn je go-to tools om images te maken die consistent werken binnen je team en omgevingen. 

Ik heb laten zien hoe je ze gebruikt in eenvoudige Python-projecten, terwijl je gevoelige informatie veilig houdt. Je hebt ook gezien hoe je build-argumenten integreert met tools zoals Docker Compose.

Zie build-argumenten als de fundering van een flexibele containerisatiestrategie. Begin klein door je Python-versie te parameteriseren in je volgende project. Als dat vertrouwd voelt, voeg dan voorwaardelijke logica toe voor verschillende omgevingen. Voor je het weet, maak je geavanceerde multistage-builds die je team kan aanpassen zonder de Dockerfile te wijzigen.

Klaar om dieper te duiken? Deze cursussen van DataCamp zijn je beste volgende stap:

• Introduction to Docker
• Intermediate Docker
• Containerization and Virtualization Concepts
• Containerization and Virtualization with Docker and Kubernetes
• CI/CD for Machine Learning