Guide zu Docker Build Secrets: Sichere Entwicklung von Container-Images

Ich habe unzählige Docker-Images gesehen, die versehentlich mit fest codierten API-Schlüsseln, Datenbankpasswörtern und Authentifizierungs-Token in ihren Layern veröffentlicht wurden. Solche Sicherheitslücken entstehen oft während des Build-Prozesses: Entwicklerinnen und Entwickler benötigen temporären Zugang zu privaten Ressourcen und backen dabei ungewollt Zugangsdaten ins finale Image ein.

Das Problem: Klassische Methoden für Zugangsdaten im Build, etwa Umgebungsvariablen oder Build-Argumente, sind nicht für kurzlebige Nutzung gedacht. Sie hinterlassen dauerhafte Spuren in Metadaten oder Layern des Images und schaffen so Sicherheitsrisiken, die weit über den Build hinaus bestehen. Die zentrale Frage lautet also: Wie authentifizierst du dich während des Builds gegenüber privaten Ressourcen, ohne die Sicherheit zu gefährden?

Docker Build Secrets lösen dieses Problem, indem sie sensible Daten während des Build-Prozesses nutzbar machen, ohne Spuren im finalen Artefakt zu hinterlassen. 

In diesem Tutorial zeige ich dir Schritt für Schritt, wie du Build Secrets effektiv einsetzt – von den Grundlagen bis zur fortgeschrittenen CI/CD-Integration – damit deine Container-Builds sicher bleiben.

Wenn du neu bei Docker bist, empfehle ich dir unsere Kurse wie Introduction to Docker, Containerization and Virtualization with Docker and Kubernetes oder Intermediate Docker. 

Was sind Docker Build Secrets?

Schauen wir uns an, was Build Secrets von anderen Ansätzen zur Verwaltung von Zugangsdaten unterscheidet. Docker Build Secrets sind kurzlebige, sensible Informationen, die während des Build-Prozesses verfügbar sind, aber nie in Image-Layern oder im Dateisystem gespeichert werden. Sie existieren nur im Speicher während bestimmter RUN-Schritte und verschwinden sofort danach.

Die Notwendigkeit ergibt sich aus modernen Entwicklungs-Workflows. 

Oft musst du dich während des Builds bei privaten Paketregistern authentifizieren, private Git-Repositories klonen, lizenzierte Software herunterladen oder interne APIs ansprechen. 

Ohne Build Secrets greifen Entwickler zu riskanten Workarounds: Zugangsdaten im Dockerfile hart codieren, Secrets als Build-Argumente übergeben (die in Metadaten fortbestehen) oder zu großzügige Base-Images mit eingebetteten Credentials erstellen.

Die Risiken einer mangelhaften Geheimnisverwaltung sind erheblich: Offengelegte Zugangsdaten können zu unbefugtem Zugriff auf Produktionssysteme, Datenpannen, Compliance-Verstößen und massiven Reputationsschäden führen. Häufige Leaks betreffen API-Schlüssel für Paketmanager, SSH-Schlüssel für Git-Operationen, Tokens für interne Dienste sowie Datenbankzugänge für Build-Zeiten.

Docker BuildKit: Das Fundament sicherer Build Secrets

Bevor wir loslegen, solltest du BuildKit kennen, die moderne Build-Engine, die sichere Secrets erst möglich macht. BuildKit ist der Next-Gen-Builder von Docker und löst die klassische Engine ab – mit großen Verbesserungen in Performance, Caching und Sicherheit.

BuildKit nutzt ein graphbasiertes Ausführungsmodell, das Abhängigkeiten zwischen Build-Schritten verfolgt. Dadurch kann BuildKit Secrets als temporäre Dateisysteme mounten, die nur während bestimmter RUN-Anweisungen existieren – so landen sie nie in den Image-Layern. 

Im Gegensatz zu klassischen Docker-Builds, bei denen alles im Build-Kontext potenziell im Cache landet, behandelt BuildKit Secrets als spezielle Ressourcen, die den Layer-Cache vollständig umgehen.

BuildKit zu aktivieren ist einfach. Ab Docker 23.0 ist BuildKit standardmäßig aktiv. Für frühere Versionen setzt du vor dem Build die Umgebungsvariable DOCKER_BUILDKIT=1:

export DOCKER_BUILDKIT=1
docker build -t myapp .

Alternativ kannst du es dauerhaft über den Docker-Daemon aktivieren oder Docker Buildx nutzen, das immer BuildKit verwendet. Der entscheidende Unterschied: In klassischen Builds könnten Secrets in Zwischenlayern landen, wenn man nicht extrem aufpasst. BuildKit garantiert dagegen, dass Secrets flüchtig sind und nie als Teil des Images auf die Platte geschrieben werden.

Auf dieser sicheren Basis schauen wir uns nun die verschiedenen Secret-Typen an und wie du sie sauber implementierst.

Arten und Umsetzung von Docker Build Secrets

BuildKit unterstützt drei primäre Mechanismen für Secrets im Build – jeweils für spezifische Anwendungsfälle. Zu wissen, wann du welchen Typ einsetzt, sorgt für optimale Sicherheit und Funktionalität.

Secret-Mounts: Allzweck für sensible Daten

Secret-Mounts sind der flexibelste Ansatz. Sie erlauben dir, Secrets während RUN-Anweisungen als Dateien an definierten Pfaden zu mounten. So stehen Credentials Build-Befehlen zur Verfügung, ohne in Layern zu persistieren.

Das Vorgehen hat zwei Schritte: das Secret an den Build übergeben und es im Dockerfile mounten. Lege zunächst lokal eine Secret-Datei an oder nutze eine Umgebungsvariable. Referenziere sie dann im Build:

docker build --secret id=api_key,src=./api_key.txt -t myapp .

Im Dockerfile mountest du das Secret in der benötigten RUN-Anweisung:

RUN --mount=type=secret,id=api_key \
    API_KEY=$(cat /run/secrets/api_key) && \
    curl -H "Authorization: Bearer $API_KEY" https://api.example.com/package > /app/data.json

Standardmäßig werden Secrets unter /run/secrets/<id> gemountet, du kannst aber mit dem Parameter target ein eigenes Ziel angeben. 

Bewährte Praxis: Secrets nur in genau den RUN-Befehlen mounten, die sie benötigen, Secrets niemals ins Image-Dateisystem kopieren und Multi-Stage-Builds nutzen, um Secret-abhängige Stages vom finalen Image zu trennen. 

Die Quelle kann ein Dateipfad sein oder du nutzt env, um Secrets aus Umgebungsvariablen zu übergeben: --secret id=token,env=API_TOKEN.

Wenn du ein Secret statt als Datei als Umgebungsvariable mounten willst, nutze die Option env:

RUN --mount=type=secret,id=db_user,env=DB_USER \
    --mount=type=secret,id=db_password,env=DB_PASSWORD \
    ./setup-database.sh

Du kannst target und env kombinieren, um ein Secret zugleich als Datei und als Umgebungsvariable bereitzustellen. 

Best Practices: Secrets nur in spezifischen RUN-Befehlen mounten, nie ins Image-Dateisystem kopieren und mit Multi-Stage-Builds Secret-Nutzung von finalen Images trennen.

SSH-Mounts: Sicherer Zugriff auf private Ressourcen

SSH-Mounts decken speziell SSH-basierte Authentifizierung ab – vor allem für den Zugriff auf private Git-Repositories während des Builds. Anstatt SSH-Schlüssel ins Image zu kopieren (ein Sicherheitsalbtraum) stellen SSH-Mounts temporären Zugriff auf deinen lokalen SSH-Agent während des Builds bereit.

Voraussetzung ist ein lokal laufender SSH-Agent mit geladenen Schlüsseln. Im Dockerfile referenzierst du den SSH-Mount so:

RUN --mount=type=ssh \
    git clone git@github.com:myorg/private-repo.git /app

Baue das Image mit aktiviertem SSH-Forwarding:

docker build --ssh default -t myapp .

Für mehrere Hosts mit unterschiedlichen Schlüsseln kannst du benannte SSH-Mounts verwenden:

RUN --mount=type=ssh,id=github \
    git clone git@github.com:myorg/repo.git

Und beim Build gezielt Schlüssel angeben:

docker build --ssh github=$HOME/.ssh/github_key -t myapp .

So bleiben private Schlüssel stets außerhalb des Images, während du während des Builds authentifizierten Zugriff auf private Repos erhältst.

Git-Authentifizierung für Remote-Kontexte

Wenn dein Docker-Build auf private Git-Repositories zugreifen muss – sei es als Build-Kontext selbst oder zum Laden von Abhängigkeiten – brauchst du eine Authentifizierung ohne eingebettete Credentials. Typisch etwa beim Build aus einer privaten Repository-URL oder bei ADD-Anweisungen, die privaten Code holen.

BuildKit bietet hierfür zwei vordefinierte Secrets: GIT_AUTH_TOKEN und GIT_AUTH_HEADER. Diese „Pre-Flight“-Secrets authentifizieren den Builder, bevor Dockerfile-Anweisungen ausgeführt werden, und sichern so bereits den initialen Repository-Fetch ab.

Am häufigsten nutzt du GIT_AUTH_TOKEN für Token-basierte HTTPS-Authentifizierung:

GIT_AUTH_TOKEN=$(cat ~/.github-token) docker build \
    --secret id=GIT_AUTH_TOKEN \
    https://github.com/myorg/private-repo.git

Das funktioniert nahtlos mit ADD-Anweisungen, die private Repositories abrufen:

FROM alpine
ADD https://github.com/myorg/private-configs.git /configs

In kurzlebigen CI/CD-Umgebungen injizierst du Tokens aus dem Secret-Store deiner Plattform:

- name: Build from private repo
  env:
    GIT_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: |
    docker build --secret id=GIT_AUTH_TOKEN https://github.com/myorg/app.git

Das Secret GIT_AUTH_HEADER ist eine Alternative für individuelle Authentifizierungsschemata, wenn ein Standard-Token nicht reicht.

So nutzt du Docker Build Secrets

Nachdem wir die Secret-Typen geklärt haben, sehen wir uns an, wie du sie in der Praxis sicher einsetzt.

Secrets für den Build vorbereiten und strukturieren

Saubere Vorbereitung ist entscheidend. Lege Secrets in Dateien außerhalb deines Build-Kontexts ab, nimm sie in .gitignore und .dockerignore auf und vergib restriktive Dateirechte (600 oder 400).

Für mehrere Secrets bietet sich ein eigenes Verzeichnis an:

mkdir -p .secrets
echo "my-api-key" > .secrets/api_key
chmod 600 .secrets/*

So referenzierst du sie im Build:

docker build \
    --secret id=api_key,src=.secrets/api_key \
    --secret id=db_password,src=.secrets/db_password \
    -t myapp .

Für CI/CD-typische Secrets aus Umgebungsvariablen:

docker build \
    --secret id=api_key,env=API_KEY \
    --secret id=db_pass,env=DB_PASSWORD \
    -t myapp .

Einsatz in Multi-Stage-Builds

Multi-Stage-Builds sind in Kombination mit Build Secrets besonders stark. Nutze Secrets in frühen Stages zum Abrufen von Abhängigkeiten und kopiere anschließend nur die benötigten Artefakte in die finale Stage:

# Build-Stage – hier werden Secrets verwendet
FROM python:3.11 AS builder
WORKDIR /app
COPY requirements.txt .
RUN --mount=type=secret,id=api_key \
    API_KEY=$(cat /run/secrets/api_key) && \
    curl -H "Authorization: Bearer $API_KEY" https://api.company.com/data.json -o data.json && \
    pip install -r requirements.txt

# Finale Stage – keine Secrets vorhanden
FROM python:3.11-slim
WORKDIR /app
COPY --from=builder /usr/local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages
COPY --from=builder /app/data.json ./data.json
COPY . .
CMD ["python", "app.py"]

So existieren Secrets ausschließlich in der Builder-Stage und landen nie im finalen Image.

Multi-Stage-Builds sind ideal für einzelne Secrets, in der Praxis wird es aber oft komplexer. 

Schauen wir uns an, wie du mehrere Secrets oder anspruchsvollere Build-Anforderungen handhabst.

Mehrere Secrets und komplexe Szenarien

Komplexe Builds benötigen oft mehrere Secrets in derselben RUN-Anweisung. BuildKit unterstützt das parallele Mounten mehrerer Secrets:

RUN --mount=type=secret,id=api_key \
    --mount=type=secret,id=db_password \
    API_KEY=$(cat /run/secrets/api_key) && \
    DB_PASS=$(cat /run/secrets/db_password) && \
    ./configure.sh

Wenn mehrere Kommandos dieselben Secrets brauchen, fasse sie in einer RUN-Anweisung zusammen oder mounte die Secrets erneut – so minimierst du Mounts und hältst Sicherheitsgrenzen ein.

Sicherheitsbest Practices für Docker Build Secrets

Damit Build Secrets wirklich sicher sind, solltest du bewährten Praktiken folgen. Hier sind Muster, die sich in der Praxis besonders bewährt haben.

Exponierung und Leaks verhindern

Prüfe nach dem Build, ob Secrets nicht doch in Layern gelandet sind, indem du sie inspizierst:

docker history myapp:latest
docker save myapp:latest | tar -x

Untersuche die extrahierten Layer auf sensible Daten. Trenne außerdem strikt zwischen Build-Time-Secrets (temporär, nur während des Builds) und Runtime-Secrets (benötigt beim Ausführen der Container). Nutze Build-Secrets niemals für Laufzeit-Credentials. Für die Laufzeit setze auf Docker Secrets, Kubernetes Secrets oder zur Laufzeit injizierte Umgebungsvariablen.

Füge Secret-Dateien immer in .gitignore ein:

# .gitignore
.secrets/
*.key

Und in .dockerignore, damit sie nicht versehentlich im Build-Kontext landen:

# .dockerignore
.secrets/
*.key
.env

Secrets in CI/CD-Umgebungen verwalten

CI/CD-Plattformen bieten nativen Secret-Storage, der sich nahtlos mit Docker Build Secrets integrieren lässt. In GitHub Actions etwa:

- name: Build Docker image
  env:
    API_KEY: ${{ secrets.API_KEY }}
  run: |
    docker build \
      --secret id=api_key,env=API_KEY \
      -t myapp .

Wichtig ist, die Secret-Stores der Plattform zu nutzen statt Secrets im Repository zu speichern. CI/CD-Secrets werden als Umgebungsvariablen injiziert, die BuildKit direkt via env-Quelle konsumieren kann.

Berechtigungen und Zugriffskontrolle

Wenn du als Nicht-Root-User baust, achte auf passende Leserechte. Falls dein Dockerfile mit USER auf einen Nicht-Root-User wechselt, mounte Secrets an Orte, auf die dieser zugreifen kann:

FROM python:3.11-slim
RUN useradd -m appuser
USER appuser

RUN --mount=type=secret,id=token,uid=1000 \
    cat /run/secrets/token > /dev/null

Für erhöhte Compliance-Anforderungen implementierst du Secret-Rotation: Verwende kurzlebige Tokens, automatisiere die Rotation in CI/CD-Pipelines und führe Audit-Logs über die Secret-Nutzung. 

Setze Ablaufdaten und automatische Erneuerung ein, um Zeitfenster der Exponierung zu minimieren.

Bisher haben wir einzelne Container betrachtet, moderne Anwendungen bestehen jedoch oft aus mehreren Services. Docker Compose erweitert Build Secrets für solche Multi-Service-Architekturen.

Build Secrets mit Docker Compose integrieren

Docker Compose vereinfacht das Secret-Management über mehrere Services hinweg. Definiere Secrets auf oberster Ebene deiner docker-compose.yml und referenziere sie in den Service-Builds:

services:
  app:
    build:
      context: .
      secrets:
        - api_key
        - db_password
  
secrets:
  api_key:
    file: ./.secrets/api_key
  db_password:
    environment: DB_PASSWORD

Im Dockerfile mountest du sie wie gewohnt:

RUN --mount=type=secret,id=api_key \
    --mount=type=secret,id=db_password \
    ./setup.sh

Build mit Compose:

docker-compose build

Dieses Muster skaliert gut für Anwendungen mit mehreren Services und unterschiedlichen Secrets. Es zentralisiert das Secret-Management und wahrt zugleich die Sicherheitsgrenzen zwischen Services.

Bei der Umsetzung wirst du auf typische Stolperfallen stoßen. Hier sind die häufigsten Herausforderungen und wie du sie löst.

Häufige Herausforderungen und Troubleshooting

Selbst bei korrekter Implementierung treten Probleme auf. Hier die gängigsten Issues und Lösungen.

Syntaxfehler und Mount-Deklarationen

Die --mount-Syntax ist strikt. Häufige Fehler: fehlende Kommata zwischen Parametern, falsche Parameternamen oder Mount-Typen. Korrekte Syntax:

RUN --mount=type=secret,id=secret_name,target=/path \
    command

Wenn der Build mit „secret not found“ scheitert, prüfe, ob BuildKit aktiviert ist und ob die ID im Dockerfile zur --secret id im Build-Befehl passt.

Secrets nicht verfügbar oder nicht gefunden

Wenn Secrets nicht zugreifbar sind, prüfe, ob die Quelldatei existiert und lesbar ist:

cat .secrets/api_key
docker build --secret id=api_key,src=.secrets/api_key .

Für Umgebungsvariablen verifiziere, dass sie gesetzt sind:

echo $API_KEY
docker build --secret id=api_key,env=API_KEY .

Verwechslung: Umgebungsvariable vs. Datei

Build-Secrets werden standardmäßig als Dateien unter /run/secrets/<id> gemountet. Willst du sie als Umgebungsvariable nutzen, lies den Dateiinhalt aus:

RUN --mount=type=secret,id=token \
    export TOKEN=$(cat /run/secrets/token) && \
    curl -H "Authorization: Bearer $TOKEN" https://api.example.com

Nutze niemals Build-Argumente (ARG) für Secrets – sie bleiben in den Image-Metadaten erhalten.

Persistenz- und Caching-Probleme

Secrets bestehen absichtlich nicht zwischen RUN-Anweisungen fort. Wenn mehrere RUNs dasselbe Secret benötigen, kombiniere die Befehle oder mounte das Secret erneut:

RUN --mount=type=secret,id=token \
    command1

RUN --mount=type=secret,id=token \
    command2

BuildKit stellt sicher, dass Secrets niemals in den Layer-Cache gelangen.

Wenn du die Grundlagen beherrschst, wirst du auf fortgeschrittene Szenarien treffen. Werfen wir einen Blick auf anspruchsvollere Anwendungsfälle und Edge Cases.

Fortgeschrittene Nutzung von Docker Build Secrets

Für komplexe Deployments brauchst du zusätzliche Überlegungen über die Basisimplementierung hinaus.

Secrets in komplexen CI/CD-Pipelines

Mehrstufige CI/CD-Pipelines benötigen oft Secrets in unterschiedlichen Phasen. Implementiere phasenspezifische Secrets statt allgemeiner Zugangsdaten. Nutze Secret-Scoping der Plattform, um zu begrenzen, welche Pipeline-Phasen welche Secrets sehen. Automatisiere das Aufräumen nach Builds, um Exponierungsfenster zu verkleinern.

Secrets mit Non-Docker-Buildern

Alternative Builder wie Buildah und Kaniko unterstützen BuildKit-Syntax unterschiedlich. Buildah bietet ähnliche Secret-Mounts per --secret-Flags. Kaniko, für Kubernetes-Umgebungen, setzt meist auf Kubernetes-Secrets, die als Volumes gemountet werden. Prüfe bei Non-Docker-Buildern stets die jeweilige Doku, da sich die Implementierungen deutlich unterscheiden.

Secrets und Compliance

Build Secrets unterstützen Compliance-Anforderungen, da sie prüfbare, kurzlebige Zugriffe auf Credentials ermöglichen. 

Für die DSGVO sorge dafür, dass keine personenbezogenen Daten in Layer gelangen. SOC2 profitiert von Audit Trails zur Secret-Nutzung – protokolliere, wann und von wem Secrets genutzt werden. Pflege Nachweise für Audits.

Secrets rotieren und aktualisieren

Etabliere Prozesse zur Secret-Rotation, ohne Builds zu stören. Nutze versionierte Secret-Dateien oder Namenskonventionen für Umgebungsvariablen, um zwischen Versionen zu wechseln. 

Automatisiere die Rotation in CI/CD-Pipelines aus zentralen Stores. Überwache Ablaufdaten und erneuere Tokens automatisch.

Fazit: Best Practices und Empfehlungen

Docker Build Secrets sind ein grundlegender Sicherheitsgewinn für containerisierte Entwicklungen. In diesem Tutorial hast du gelernt, wie du Secrets sicher einsetzt – von Secret-Mounts bis zur CI/CD-Integration.

Die wichtigsten Punkte: Nutze immer BuildKits Secret-Mounting statt Build-Argumenten oder hart codierten Credentials, setze Multi-Stage-Builds ein, um Secret-Stages vom finalen Image zu trennen, verwende das Secret-Management deiner CI/CD-Plattform für Automatisierung und prüfe regelmäßig Images, damit keine Secrets in Layern landen.

Wenn dein Unternehmen diese Praktiken einführt, starte mit einer Secret-Policy, die festlegt, welche Secrets Build-Zugriff benötigen, etabliere automatische Rotationspläne, teste systematisch, dass Secrets nicht im Image verbleiben, und schule Teams im richtigen Umgang. So reduzierst du die Angriffsfläche deutlich und baust sicherere containerisierte Anwendungen.

Zum Weiterlernen empfehle ich dir diese Ressourcen:

• Docker for Data Science Cheat Sheet
• Run a Docker Image as a Container: A Practical Beginner’s Guide
• Top 18 Docker Commands to Build, Run, and Manage Containers
• Containerization: Docker and Kubernetes for Machine Learning