Docker Build Args: Der ultimative Leitfaden für Datenexperten

Auswirkungen auf die Sicherheit und Risikominderung

Build-Argumente bieten zwar Flexibilität, aber sie bergen auch potenzielle Sicherheitsrisiken, die du kennen musst, um deine Docker-Images sicher zu halten.

Argument-Leck-Vektoren

Baustreitigkeiten sind nicht so privat, wie du vielleicht denkst. Die Werte von Build-Args können über verschiedene Vektoren durchsickern, die viele Entwickler übersehen. Erstens legt die Docker-Image-Historie alle deine Build-Args offen. Das bedeutet, dass jeder, der Zugriff auf dein Image hat, docker history ausführen kann, um die Werte zu sehen, die du während der Build-Zeit verwendet hast, einschließlich potenziell sensibler Informationen wie API-Schlüssel oder Token.

docker history flaskapp:dev

Abbildung 4 - Docker Geschichte

Auch Zwischenschichten können Argumente für den Aufbau preisgeben. Auch wenn du einen mehrstufigen Build verwendest und den Layer mit den sensiblen Informationen nicht kopierst, bleiben die Build-Arg-Werte im Layer-Cache auf der Build-Maschine. Das bedeutet, dass jeder, der Zugriff auf den Docker-Daemon auf deinem Build-Server hat, diese Informationen möglicherweise auslesen kann.

CI/CD-Logs stellen ein weiteres großes Risiko dar. Die meisten CI/CD-Systeme protokollieren den gesamten Build-Befehl, einschließlich aller Build-Args, die auf der Kommandozeile übergeben werden.

Zum Beispiel wird dieser gesamte Befehl, einschließlich API_KEY, in den CI/CD-Logs sichtbar sein:

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

Diese Logs sind oft für eine breitere Gruppe von Entwicklern zugänglich oder werden sogar in Systemen von Drittanbietern gespeichert, was die Angriffsfläche für sensible Werte vergrößert.

Sichere Alternativen

Für sensible Informationen solltest du die secrets-Funktion von Docker BuildKit anstelle von build args verwenden. Mit BuildKit kannst du Geheimnisse während des Build-Prozesses einbinden, ohne dass sie im endgültigen Image oder in der Historie bestehen bleiben.

Hier ist ein Beispiel für eine Dockerdatei, die Docker BuildKit-Geheimnisse verwendet:

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"]

Um dieses Bild mit einem Geheimnis zu erstellen, musst du zuerst die Datei api_key.txt erstellen:

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

Und dann baue das Bild mit dem Geheimnis:

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

Abbildung 5 - Bilder mit BuildKit-Geheimnissen bauen

Für Konfigurationen, die zur Laufzeit verfügbar sein müssen, sind Umgebungsvariablen nach wie vor die beste Lösung. Sie können beim Starten eines Containers gesetzt werden, ohne dass sie in das Bild eingebacken werden:

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

Um sensible Konfigurationen in der Produktion sicher zu handhaben, solltest du Container-Orchestrierungsplattformen wie Kubernetes verwenden, die sichere Methoden wie Secrets für die Verwaltung sensibler Informationen bieten. Auch Docker Swarm bietet mit seinem Secrets Management ähnliche Möglichkeiten.

> Docker ist nicht die einzige Plattform zur Containerisierung. Lies über Podman, um herauszufinden, welches Tool besser für dich geeignet ist.

Als Faustregel gilt: Verwende Build-Args für die Build-Time-Konfiguration, die nicht sensibel ist, verwende BuildKit-Geheimnisse für sensible Build-Time-Anforderungen und verwende Umgebungsvariablen oder Geheimnisse der Orchestrierungsplattform für die Laufzeitkonfiguration.

Integration mit Container-Ökosystemen

Nachdem die Grundlagen nun geklärt sind, wollen wir uns ansehen, wie man Build-Argumente in einem breiteren Docker-Ökosystem und modernen Build-Tools nutzen kann.

Docker Compose

Docker Compose macht es einfach, Build-Argumente für deine Multi-Container-Anwendungen zu definieren und gemeinsam zu nutzen.

Wenn du das nachvollziehen möchtest, findest du hier eine komplette Projektstruktur für zwei einfache Flask-Dienste:

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

Ich werde den Inhalt der Datei kurz nacheinander durchgehen:

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/requirements.txt

flask==3.1.0

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"]

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/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"]

.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"

Kurz gesagt, ist dies eine sehr einfache Methode, um zwei Anwendungen in isolierten Umgebungen zu starten, beide zur gleichen Zeit und beide mit einem bestimmten Satz von Build-Args.

Du kannst diesen Befehl verwenden, um das Multi-Container-Setup auszuführen:

docker compose up --build

Abbildung 6 - Args mit Docker Compose bauen

Nach ein paar Sekunden siehst du, dass beide Dienste laufen:

Abbildung 7 - Args mit Docker Compose bauen (2)

Für so einfache Anwendungen wie diese beiden ist das ein ziemlich ausführliches Setup, aber du verstehst das große Ganze: Die Build-Argumente werden in der Compose-Datei festgelegt und in den einzelnen Dockerdateien referenziert.

Nebenbei bemerkt, kannst du auch Variablenwerte aus deiner Umgebung an die Build-Args übergeben, was für CI/CD-Pipelines praktisch ist:

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

Und um diese Werte beim Ausführen von docker-compose zu überschreiben, kannst du Umgebungsvariablen verwenden:

PYTHON_VERSION=3.10 docker-compose up --build

Dieser Ansatz ermöglicht es dir, konsistente Builds in deinem Team aufrechtzuerhalten und trotzdem flexibel zu sein, wenn es nötig ist.

BuildKit-Funktionen

BuildKit, die moderne Build-Engine von Docker, optimiert deinen Build-Prozess mit Funktionen, die die Verwendung von Build-Args noch leistungsfähiger machen. Wenn du BuildKit aktivierst (indem du DOCKER_BUILDKIT=1 einstellst), schaltest du eine Reihe neuer Funktionen frei.

Der Inline-Cache verbessert die Build-Leistung, indem er den Build-Cache des Remote-Images nutzt. Mit dem Flag --cache-from kannst du ein Quellbild angeben, das als Cache verwendet werden soll, und BuildKit wird die Ebenen dieses Bildes intelligent nutzen:

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

Eine weitere wertvolle Funktion von BuildKit sind deterministische Ausgaben, die sicherstellen, dass deine Builds reproduzierbar sind. Das ist wichtig, wenn du genau das gleiche Bild haben willst, egal wann und wo es gebaut wird:

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

Die geheime Redigierung von BuildKit in den Protokollen schützt sensible Informationen während der Builds. 

Im Gegensatz zu normalen Build-Args, die in den Build-Logs erscheinen, verbirgt BuildKit automatisch die Werte von 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 .

In deinem Dockerfile greifst du auf dieses Geheimnis mit zu:

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

Diese BuildKit-Funktionen arbeiten mit Build-Args zusammen, um ein sichereres, effizienteres und reproduzierbares Build-System zu schaffen, das sich an praktisch jeden Containerisierungs-Workflow anpassen kann.

Best Practices für die Einführung in Unternehmen

Die Implementierung von Docker-Build-Argumenten in großen Teams erfordert standardisierte Ansätze, zumindest wenn du die Verwirrung minimieren und die Sicherheits- und Leistungsvorteile maximieren willst.

Wenn du Build-Args in Unternehmensumgebungen einführst, solltest du mit der richtigen Validierung der Argumente beginnen. 

Gib immer sinnvolle Standardwerte für jedes Build-Argument an, um sicherzustellen, dass Builds nicht unerwartet fehlschlagen, wenn die Argumente nicht übergeben werden. Du solltest auch Validierungsprüfungen in dein Dockerfile einbauen, um sicherzustellen, dass kritische Build-Args deinen Anforderungen entsprechen.

Hier ist ein Beispiel, das die Python-Version überprüft:

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

Die Optimierung des Layer-Cachings ist entscheidend für die Reduzierung der Build-Zeiten in CI/CD-Pipelines. 

Ordne deine Dockerfile-Anweisungen so an, dass du die Cache-Treffer maximierst, indem du selten wechselnde Inhalte (wie die Installation von Abhängigkeiten) vor häufig wechselnden Inhalten (wie dem Anwendungscode) platzierst. 

Wenn du Build-Args verwendest, die sich häufig ändern können, platziere sie nach stabilen Operationen, damit nicht der gesamte Cache ungültig wird:

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

Die Verwaltung von Metadaten durch Build-Args verbessert die Rückverfolgbarkeit und die Einhaltung von Vorschriften. Verwende Build-Args, um Metadaten zur Build-Zeit als Labels einzufügen:

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

Diese standardisierten Labels folgen der Spezifikation der Open Container Initiative (OCI), was bedeutet, dass deine Images mit verschiedenen Container-Management-Tools kompatibel sind.

Die Dokumentation wird oft übersehen, aber sie ist entscheidend für die Akzeptanz in Unternehmen. 

Erstelle einen übersichtlichen README Abschnitt, der alle verfügbaren Build-Args, ihren Zweck, ihre Standardwerte und Anwendungsbeispiele dokumentiert. Gib an, welche Build-Argumente erforderlich und welche optional sind, und dokumentiere alle Wechselwirkungen zwischen den verschiedenen Argumenten. Erwäge, diese Informationen auch als Kommentare in die Konfigurationsdateien deiner CI/CD-Pipeline aufzunehmen, damit die Entwickler wissen, welche Werte sie angeben müssen:

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

Für eine wirklich unternehmenstaugliche Einführung solltest du ein Schema für Build-Argumente einführen, das versioniert und validiert werden kann. Mit diesem Ansatz kannst du deine Build-Konfiguration im Laufe der Zeit weiterentwickeln und gleichzeitig die Abwärtskompatibilität wahren.

Vergleichende Analyse: Build Args vs. Umgebungsvariablen

Wenn du sichere und flexible Docker-Images erstellen willst, die den Best Practices folgen, musst du wissen, wann du Build-Argumente und wann du Umgebungsvariablen verwenden solltest.

Hier ist eine Tabelle, die du jederzeit nachschlagen kannst:

Der entscheidende Unterschiedliegt in ihrem Zeitpunkt und ihrem Zweck. Build-Args konfigurieren den Build-Prozess selbst, während Umgebungsvariablen die laufende Anwendung konfigurieren. Du würdest zum Beispiel ein Build-Arg verwenden, um das zu verwendende Basis-Image auszuwählen (ARG PYTHON_VERSION=3.10), aber du würdest eine Umgebungsvariable verwenden, um deiner Anwendung mitzuteilen, auf welchem Port sie lauschen soll (ENV PORT=8080).

Aus einer Sicherheitsperspektive stellen Build-Args ein höheres Risiko für sensible Informationen dar, da sie in der Image History verbleiben.

Betrachte diesen Arbeitsablauf für die Handhabung verschiedener Arten von Konfigurationen:

# 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

In der Praxis ist es üblich, ausgewählte Build-Args in Umgebungsvariablen umzuwandeln, wenn sie zur Laufzeit verfügbar sein sollen:

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

Bei Unternehmensanwendungen ermöglicht die Trennung, dass verschiedene Teams unterschiedliche Aspekte des Lebenszyklus der Anwendung verwalten. DevOps-Teams können die Build-Args für die Image-Erstellung ändern, während die Betreiber die Umgebungsvariablen während der Bereitstellung anpassen können, ohne die Images neu zu erstellen.

Zusammenfassung der Docker Build Args

Docker-Build-Args sind nicht nur ein weiteres technisches Feature - sie sind dein wichtigstes Werkzeug, um Images zu erstellen, die in deinem Team und deinen Umgebungen einheitlich funktionieren. 

Ich habe dir gezeigt, wie du sie in einfachen Python-Projekten einsetzen kannst, ohne dass deine sensiblen Daten in Gefahr geraten. Du hast auch gesehen, wie man Build-Args in Tools wie Docker Compose integriert.

Betrachte Build-Args als Grundlage für eine flexible Containerisierungsstrategie. Fang klein an, indem du deine Python-Version in deinem nächsten Projekt parametrisierst. Wenn du dich damit wohlfühlst, kannst du versuchen, bedingte Logik für verschiedene Umgebungen hinzuzufügen. Im Handumdrehen erstellst du ausgefeilte mehrstufige Builds, die dein Team anpassen kann, ohne die Dockerdatei zu verändern.

Bist du bereit, tiefer einzutauchen? Diese Kurse von DataCamp sind die beste Anlaufstelle für dich:

• Einführung in Docker
• Docker für Fortgeschrittene
• Konzepte für Containerisierung und Virtualisierung
• Containerisierung und Virtualisierung mit Docker und Kubernetes
• CI/CD für maschinelles Lernen