TL;DR — Kurzzusammenfassung

Ansible Vault verschluesselt Geheimnisse in Playbooks mit AES-256. Lernen Sie vault create, encrypt_string, Vault IDs, CI/CD-Integration und Passwortrotation.

ANSIBLE VAULT — AES-256-VERSCHLUESSELUNG VON GEHEIMNISSEN KLARTEXT (GEFAHR) db_pass: supersecret api_key: abc123xyz ssl_key: -----BEGIN... Sichtbar im Git-Verlauf! ansible-vault encrypt VERSCHLUESSELT (GIT-SICHER) $ANSIBLE_VAULT;1.1;AES256 66386439653763616335616... 32663930343936663766303... 61373039636131336531353... AES-256-verschluesselter Blob --vault-password -file / --ask-vault -pass LAUFZEIT (ARBEITSSPEICHER) db_pass: supersecret api_key: abc123xyz ssl_key: -----BEGIN... Nur im Speicher entschluesselt Das Vault-Passwort beruehrt nie die Festplatte — nur der verschluesselte Blob wird in git gespeichert

Datenbankpasswoerter, API-Schluessel und private SSL-Schluessel im Klartext in Ihren Ansible-Playbooks zu speichern ist einer der haeufigsten Sicherheitsfehler bei der Infrastrukturautomatisierung. Sobald ein Geheimnis unverschluesselt in einem Git-Repository landet, ist es faktisch kompromittiert — der Git-Verlauf bleibt dauerhaft erhalten, und jeder mit Lesezugriff auf das Repository kann es abrufen. Ansible Vault loest dieses Problem, indem Geheimnisse direkt in Ihrem Repository mit AES-256 verschluesselt werden, sodass Sie verschluesselte Credential-Dateien neben Ihren Playbooks committen koennen, ohne sensible Daten preiszugeben.

Voraussetzungen

Bevor Sie mit diesem Leitfaden arbeiten, sollten Sie haben:

  • Ansible 2.8 oder spaeter auf Ihrem Steuerknoten installiert (ansible --version zur Verifizierung)
  • Grundlegende Vertrautheit mit Ansible-Playbooks und der group_vars-Verzeichnisstruktur
  • Ein bestehendes Ansible-Projekt mit Inventar und mindestens einem Playbook
  • Einen Texteditor als Ihr $EDITOR konfiguriert (nano, vim oder VS Code)
  • Fuer CI/CD-Abschnitte: eine GitHub Actions-, GitLab CI- oder Jenkins-Pipeline, die Sie anpassen koennen

Neu bei Ansible? Lesen Sie zuerst unseren Ansible-Einstiegsleitfaden, um Ihre Projektstruktur einzurichten, bevor Sie Vault hinzufuegen.

Warum Klartext-Geheimnisse in Playbooks Gefaehrlich Sind

Jedes im Klartext gespeicherte Geheimnis in einem Git-Repository tragt dasselbe Risiko: Exposition. Betrachten Sie, was typischerweise ohne Vault in Ansible-Variablendateien landet:

  • Datenbank-Root-Passwoerter in group_vars/dbservers.yml
  • AWS-Zugriffsschluessel in host_vars/deploy.yml
  • SMTP-Zugangsdaten in roles/notifications/defaults/main.yml
  • Privater SSL-Schlussel-Inhalt in einem vars:-Block in einem Playbook

Jedes der folgenden Ereignisse legt diese Geheimnisse sofort offen: ein versehentlich oeffentlich gemachtes Repository, ein kompromittiertes GitHub-Konto eines Mitarbeiters, ein durchgesickertes CI/CD-Protokoll oder ein unzufriedener ehemaliger Mitarbeiter. Ansible Vault verhindert dies, indem sichergestellt wird, dass in git gespeicherte Dateien nur AES-256-verschluesselten Chiffretext enthalten, nicht die eigentlichen Geheimniswerte.

Das Vault-Passwort selbst gelangt nie in Ihr Repository. Es bleibt in Ihrem Gedaechtnis, in einem Passwortmanager oder im Secrets-Store Ihres CI/CD-Systems — getrennt vom Code.

Verschluesselte Dateien mit ansible-vault create Erstellen

Der Unterbefehl create oeffnet Ihren konfigurierten $EDITOR mit einer leeren Datei, laesst Sie Ihre Geheimnisse eingeben und speichert die Datei verschluesselt beim Schliessen des Editors:

ansible-vault create group_vars/all/vault.yml

Sie werden nach einem neuen Vault-Passwort gefragt (zweimal zur Bestaetigung). Der Editor oeffnet sich. Geben Sie Ihre Geheimnisse ein:

vault_db_password: "Tr0ub4dor&3"
vault_db_root_password: "R4nd0mS33d#9"
vault_api_key: "sk-live-abc123def456ghi789"
vault_smtp_password: "M@ilS3rv1c3P@ss"
vault_ssl_private_key: |
  -----BEGIN RSA PRIVATE KEY-----
  MIIEpAIBAAKCAQEA3cH7...
  -----END RSA PRIVATE KEY-----

Speichern und schliessen. Die Datei auf der Festplatte enthaelt jetzt nur den verschluesselten Blob:

$ANSIBLE_VAULT;1.1;AES256
66386439653763616335616230333934356262313032393132376163633335636630
34663437326664303537373561373039636131336531353364386530636431343739
...

Verschluesselte Dateien bearbeiten und anzeigen

# Im Editor fuer Aenderungen oeffnen
ansible-vault edit group_vars/all/vault.yml

# Entschluesselten Inhalt ohne Bearbeiten anzeigen
ansible-vault view group_vars/all/vault.yml

# Eine bestehende Klartext-Datei verschluesseln
ansible-vault encrypt secrets.yml

# Eine Datei zurueck in Klartext entschluesseln (mit Vorsicht verwenden)
ansible-vault decrypt secrets.yml

Einzelne Variablen mit encrypt_string Verschluesseln

Manchmal moechten Sie ein einzelnes Geheimnis in einer Nicht-Vault-Datei — vielleicht weil Sie den umgebenden Kontext ohne Entschluesseln von allem sichtbar haben moechten. Der Unterbefehl encrypt_string erzeugt einen verschluesselten Wert, den Sie direkt in eine YAML-Datei einfuegen koennen:

ansible-vault encrypt_string --name 'vault_stripe_key' 'sk_live_abc123xyz'

Ausgabe:

vault_stripe_key: !vault |
  $ANSIBLE_VAULT;1.1;AES256
  66653465346564383664396631316639
  37313739623731633864333736396230
  ...

Fuegen Sie diesen Block direkt in eine beliebige YAML-Variablendatei ein. Ansible entschluesselt ihn transparent zur Laufzeit, genauso wie es mit einer vollstaendig verschluesselten Vault-Datei umgeht.

Wann encrypt_string vs. verschluesselte Dateien verwenden:

AnsatzVerwenden wenn
ansible-vault create vault.ymlDie meisten Faelle — haelt Geheimnisse organisiert, einfach zu pruefen
encrypt_stringEinzelnes Geheimnis in einer hauptsaechlich klaren Datei; Inline-Geheimnisse in Roles
Ganzes Playbook verschluesseltSelten benoetigt; beeintraechtigt die Lesbarkeit

Vault IDs: Mehrere Passwoerter fuer Verschiedene Geheimnis-Sets

Vault IDs ermoglichen die Kennzeichnung verschluesselter Inhalte, damit Ansible weiss, welches Passwort anzuwenden ist. Dies ist entscheidend, wenn Staging und Produktion unterschiedliche Passwoerter verwenden oder wenn Sie ein Passwort rotieren moechten, ohne alles neu zu verschluesseln.

Mit einer Vault ID verschluesseln

# Mit einer benannten Vault ID verschluesseln
ansible-vault create --vault-id prod@prompt group_vars/production/vault.yml
ansible-vault create --vault-id staging@prompt group_vars/staging/vault.yml

# Oder auf eine Passwortdatei zeigen
ansible-vault create --vault-id prod@~/.vault_prod group_vars/production/vault.yml

Mit mehreren Vault IDs entschluesseln

ansible-playbook site.yml \
  --vault-id prod@~/.vault_prod \
  --vault-id staging@~/.vault_staging

Ansible ordnet jeden verschluesselten Block automatisch seiner Vault-ID-Bezeichnung zu und verwendet das richtige Passwort. Inhalte, die ohne explizite Vault ID verschluesselt wurden, verwenden standardmaessig die Bezeichnung default.

CI/CD-Integration mit —vault-password-file

Interaktive Passworteingaben blockieren automatisierte Pipelines. Das Flag --vault-password-file akzeptiert einen Pfad zu einer Datei, die nur das Vault-Passwort enthaelt, und ermoeglicht eine vollstaendig nicht interaktive Ausfuehrung.

Beispiel mit GitHub Actions

# .github/workflows/deploy.yml
name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Ansible installieren
        run: pip install ansible

      - name: Vault-Passwort in Datei schreiben
        run: echo "${{ secrets.ANSIBLE_VAULT_PASSWORD }}" > ~/.vault_pass

      - name: Playbook ausfuehren
        run: |
          ansible-playbook -i inventory/production site.yml \
            --vault-password-file ~/.vault_pass

      - name: Vault-Passwortdatei entfernen
        if: always()
        run: rm -f ~/.vault_pass

Speichern Sie ANSIBLE_VAULT_PASSWORD in den GitHub Actions Secrets des Repositories (Einstellungen → Secrets → Actions). Das Vault-Passwort erscheint nie in Protokollen, da GitHub Geheimniswerte maskiert.

Beispiel mit GitLab CI

# .gitlab-ci.yml
deploy:
  script:
    - echo "$ANSIBLE_VAULT_PASSWORD" > ~/.vault_pass
    - ansible-playbook -i inventory/production site.yml --vault-password-file ~/.vault_pass
    - rm -f ~/.vault_pass
  variables:
    ANSIBLE_VAULT_PASSWORD: $ANSIBLE_VAULT_PASSWORD

Ein Vault-Passwortskript verwenden

Fuer dynamische Vault-Passwoerter (zur Laufzeit von HashiCorp Vault, AWS Secrets Manager oder Azure Key Vault abgerufen) erstellen Sie ein ausfuehrbares Skript, das das Passwort ausgibt:

#!/bin/bash
# ~/.get_vault_pass.sh
aws secretsmanager get-secret-value \
  --secret-id ansible/vault-password \
  --query SecretString \
  --output text
chmod +x ~/.get_vault_pass.sh
ansible-playbook site.yml --vault-password-file ~/.get_vault_pass.sh

Best Practices: Vault-Variablen Organisieren

Das wartbarste Muster trennt Ihre Variablendateien in zwei parallele Dateien pro Gruppe:

group_vars/
  all/
    vars.yml      # einfache Variablen + Referenzen auf vault_-Variablen
    vault.yml     # verschluesselt, nur vault_-Praefix-Variablen
  production/
    vars.yml
    vault.yml
  staging/
    vars.yml
    vault.yml

group_vars/all/vars.yml — Klartext, sicher in git zu pruefen:

# group_vars/all/vars.yml
db_host: "db.internal.example.com"
db_port: 5432
db_name: "myapp_prod"
db_password: "{{ vault_db_password }}"    # Referenz, nicht der Wert

api_endpoint: "https://api.stripe.com/v1"
stripe_key: "{{ vault_stripe_key }}"

smtp_host: "smtp.sendgrid.net"
smtp_user: "apikey"
smtp_password: "{{ vault_smtp_password }}"

group_vars/all/vault.yml — verschluesselt, alle mit vault_-Praefix:

# group_vars/all/vault.yml  (diese Datei ist auf der Festplatte verschluesselt)
vault_db_password: "Tr0ub4dor&3"
vault_stripe_key: "sk_live_abc123"
vault_smtp_password: "SG.abc123xyz"

Vorteile dieses Musters:

  • Playbooks referenzieren lesbare Namen (db_password), nicht Vault-Variablen direkt
  • git diff zeigt Aenderungen in der vars.yml-Struktur ohne das Vault-Passwort zu benoetigen
  • Sie koennen pruefen, welche Variablen in der Vault-Datei nach Namen existieren (fuehren Sie ansible-vault view aus)
  • Neue Teammitglieder koennen vars.yml lesen, um die Variablenstruktur ohne Vault-Zugang zu verstehen

Vault-Passwoerter mit rekey Rotieren

Das Rotieren des Vault-Passworts ist ein Einzeilen-Befehl:

ansible-vault rekey group_vars/all/vault.yml

Sie werden nach dem aktuellen Vault-Passwort gefragt, dann muessen Sie das neue Passwort eingeben und bestaetigen. Die Datei wird an Ort und Stelle neu verschluesselt. Waehrend dieses Vorgangs werden keine Geheimnisse auf die Festplatte entschluesselt.

Fuer mehrere Vault-Dateien auf einmal:

# Alle Vault-Dateien im Projekt neu verschluesseln
find . -name "vault.yml" -exec ansible-vault rekey {} \;

# Oder mit --new-vault-password-file fuer nicht interaktive Rotation
ansible-vault rekey \
  --vault-password-file ~/.old_vault_pass \
  --new-vault-password-file ~/.new_vault_pass \
  group_vars/all/vault.yml group_vars/production/vault.yml

Aktualisieren Sie nach dem Rekey Ihren CI/CD-Secret-Store mit dem neuen Passwort, bevor die naechste Pipeline ausgefuehrt wird.

Ansible Vault mit AWX und Semaphore Verwenden

AWX / Ansible Tower

AWX verfuegt ueber einen nativen Credential-Typ fuer Ansible Vault. Erstellen Sie ein Credential vom Typ Vault (Einstellungen → Credentials → Hinzufuegen → Vault), geben Sie das Vault-Passwort ein und weisen Sie es Ihrer Job-Vorlage zu. AWX uebergibt das Passwort sicher ohne es in der Job-Ausgabe preiszugeben.

Fuer mehrere Vault IDs in AWX erstellen Sie ein Vault-Credential pro ID und weisen alle der Job-Vorlage zu.

Semaphore UI

Semaphore speichert Vault-Passwoerter in seinem Key Store. Navigieren Sie zu Key Store → Neuer Schluessel, waehlen Sie den Typ Passwort, geben Sie Ihr Vault-Passwort ein und benennen Sie es (z.B. vault-production). Beim Erstellen einer Task-Vorlage waehlen Sie den Vault-Schluessel im Feld Vault Password.

Semaphore uebergibt den Schluessel an Ansible ueber eine temporaere Datei, die nach dem Playbook-Durchlauf geloescht wird — entsprechend dem gleichen Sicherheitsmodell wie der Passwortdatei-Ansatz in CI/CD.

Vergleich: Ansible Vault vs. Alternativen

ToolVerschluesselungGit-nativCI/CDDynamische GeheimnisseKomplexitaet
Ansible VaultAES-256Ja — Dateien im RepoPasswortdateiUeber SkriptNiedrig
HashiCorp VaultAES-256-GCMNein — externer DienstAPI + TokenJa (Leases)Hoch
SOPSAES-256 / PGP / KMSJa — verschluesselte WerteKMS-SchluesselNeinMittel
git-cryptAES-256Ja — transparentGPG-SchluesselNeinMittel

Waehlen Sie Ansible Vault, wenn Ihre Geheimnisse nur von Ansible-Playbooks zugreifbar sein muessen und Sie keine zusaetzliche Infrastruktur wollen. Waehlen Sie HashiCorp Vault, wenn Sie dynamische Geheimnisse, feinkoernigen Lease-Ablauf oder Multi-Anwendungs-Geheimniszugang benoetigen. SOPS ist nuetzlich, wenn Sie verschluesselte Dateien benoetigen, die von anderen Tools als Ansible (Terraform, Helm) gelesen werden koennen. git-crypt funktioniert gut fuer allgemeine verschluesselte Dateien in einem Repo, hat aber keine Ansible-spezifischen Integrationen.

Praxisszenario: DB-Zugangsdaten und API-Schluessel in Mehreren Umgebungen

Sie verwalten drei Umgebungen (Entwicklung, Staging, Produktion) fuer eine Webanwendung. Jede Umgebung hat eine PostgreSQL-Datenbank, einen Stripe-API-Schluessel und ein SendGrid-SMTP-Passwort. Die Entwicklung verwendet schwache lokale Passwoerter; die Produktion verwendet starke Zugangsdaten, die vom Sicherheitsteam verwaltet werden.

Verzeichnisstruktur:

projekt/
  ansible.cfg
  inventory/
    development/hosts
    staging/hosts
    production/hosts
  group_vars/
    all/
      vars.yml         # gemeinsame Variablenstruktur
    development/
      vars.yml         # nicht sensible Dev-Konfiguration
      vault.yml        # verschluesselte Dev-Geheimnisse (getrenntes Passwort)
    staging/
      vars.yml
      vault.yml        # verschluesselte Staging-Geheimnisse
    production/
      vars.yml
      vault.yml        # verschluesselte Produktions-Geheimnisse (am meisten eingeschraenkt)
  playbooks/
    deploy.yml
    db_setup.yml

Die vault.yml jeder Umgebung verwendet eine separate Vault ID und ein separates Passwort, verwaltet vom jeweiligen Team:

# Entwicklungs-Vault erstellen (Passwort des Entwicklerteams)
ansible-vault create --vault-id dev@prompt group_vars/development/vault.yml

# Staging-Vault erstellen (Passwort des QA-Teams)
ansible-vault create --vault-id staging@prompt group_vars/staging/vault.yml

# Produktions-Vault erstellen (Passwort des Ops-Teams)
ansible-vault create --vault-id prod@prompt group_vars/production/vault.yml

Deployment-Pipeline (nur Produktion):

ansible-playbook -i inventory/production playbooks/deploy.yml \
  --vault-id prod@~/.vault_prod

Das Produktions-Vault-Passwort wird nie mit Entwicklern oder QA geteilt. Wenn der Staging-Vault kompromittiert wird, sind die Produktionsgeheimnisse nicht betroffen, da sie ein vollstaendig getrenntes Passwort verwenden.

Fallstricke und Sonderfaelle

Das Vault-Passwort zu vergessen ist permanent. Es gibt keinen Wiederherstellungsmechanismus. Die verschluesselten Daten sind verloren. Speichern Sie Vault-Passwoerter sofort nach der Erstellung in einem Passwortmanager und in einem CI/CD-Geheimnis.

Vermeiden Sie --ask-vault-pass in der Automatisierung. Dies blockiert Pipelines und erfordert interaktive Eingabe. Verwenden Sie immer --vault-password-file in nicht interaktiven Kontexten.

ansible.cfg kann Vault-Standardwerte setzen. Fuegen Sie vault_password_file = ~/.vault_pass zu Ihrer ansible.cfg hinzu, um die Angabe bei jedem Befehl zu vermeiden.

vault.yml-Dateien sollten nie in .gitignore sein. Das Ziel ist, sie verschluesselt zu committen. Wenn Sie versucht sind, eine Vault-Datei in git zu ignorieren, haben Sie sie wahrscheinlich versehentlich im Klartext belassen.

Verschluesselte Dateien erscheinen bei identischer Neu-Verschluesselung immer noch als geaendert in git. AES-256 im CBC-Modus erzeugt bei jeder Verschluesselung unterschiedlichen Chiffretext fuer denselben Klartext. Fuehren Sie ansible-vault encrypt nicht bei unveraenderten Dateien aus, da dies den Git-Verlauf verschmutzt.

Binaere Dateien koennen ebenfalls verschluesselt werden. SSL-Zertifikate, Keystore-Dateien und SSH-Schluessel im Binaerformat koennen alle mit ansible-vault encrypt verschluesselt werden. Ansible entschluesselt sie in eine temporaere Datei, bevor es den Pfad an das jeweilige Modul uebergibt.

Fehlerbehebung

Fehler “Decryption failed” (Entschluesselung fehlgeschlagen):

# Ueberpruefen Sie, ob das Passwort korrekt ist, indem Sie die Datei anzeigen
ansible-vault view group_vars/all/vault.yml

# Pruefen Sie, ob die Vault ID uebereinstimmt, wenn Sie Vault IDs verwenden
ansible-vault view --vault-id prod@prompt group_vars/production/vault.yml

Das Playbook wird ohne Aufforderung nach dem Vault-Passwort ausgefuehrt und verwendet den falschen Wert:

Pruefen Sie, ob vault_password_file in ansible.cfg gesetzt ist. Wenn die Datei nicht existiert oder leer ist, ueberspringt Ansible die Vault-Entschluesselung stillschweigend. Fuegen Sie voruebergehend --ask-vault-pass hinzu, um zu bestaetigen.

Fehler “File is not encrypted” (Datei ist nicht verschluesselt) beim Bearbeiten:

Die Datei wird als Klartext gespeichert. Verschluesseln Sie sie zuerst: ansible-vault encrypt filename.yml.

Die Variable zeigt den Literalstring {{ vault_db_password }} in der Task-Ausgabe:

Die Variable wird referenziert, aber die Vault-Datei wurde nicht geladen. Vergewissern Sie sich, dass die Vault-Datei in einem Pfad liegt, den Ansible automatisch laedt (group_vars/, host_vars/), oder fuegen Sie sie explizit mit vars_files: im Playbook hinzu.

Die CI/CD-Pipeline zeigt das Vault-Passwort in den Protokollen:

Uebergeben Sie das Vault-Passwort nie als Befehlszeilenargument. Schreiben Sie immer zuerst in eine Datei. Bestaetigen Sie, dass Ihr CI-Anbieter die geheime Variable in der Protokollausgabe maskiert.

Zusammenfassung

  • Speichern Sie alle Geheimnisse in mit ansible-vault create verschluesselten group_vars/*/vault.yml-Dateien
  • Verwenden Sie die vault_-Praefix-Konvention, um verschluesselte Variablen von einfachen zu unterscheiden
  • Referenzieren Sie Vault-Variablen aus einfachen vars.yml-Dateien mit {{ vault_varname }}, damit Playbooks lesbar bleiben
  • Verwenden Sie encrypt_string nur fuer einzelne Inline-Geheimnisse, nicht als Hauptmuster fuer Geheimnisse
  • Verwenden Sie Vault IDs, um separate Passwoerter fuer verschiedene Umgebungen oder Teams zu verwalten
  • Integrieren Sie mit CI/CD ueber --vault-password-file und speichern Sie das Passwort in Ihrem Secrets-Manager
  • Rotieren Sie Vault-Passwoerter mit ansible-vault rekey und aktualisieren Sie CI/CD-Geheimnisse sofort
  • Speichern Sie niemals Vault-Passwoerter in Dateien, die in git committet werden
  • AWX und Semaphore haben nativen Vault-Credential-Support — bevorzugen Sie diesen gegenueber alternativen Loesungen

Verwandte Artikel