michaelschiemer/deployment/docs/guides/vault-password.md

Ansible Vault Password Dokumentation

?bersicht

Das Ansible Vault-Passwort wird verwendet, um verschl?sselte Secrets-Dateien (production.vault.yml) zu sch?tzen. Diese Dokumentation beschreibt, wie das Vault-Passwort angelegt, gespeichert und verwendet wird.

Historischer Kontext

Erstellungsdatum

• Erstellt am: 30. Oktober 2025, 21:42:27
• Datei: deployment/ansible/secrets/.vault_pass
• Erstes Setup-Script: 31. Oktober 2025 (Commit e26eb2a)
• Script-Datei: deployment/ansible/scripts/init-secrets.sh

Einf?hrung

Das Vault-Passwort-System wurde im Rahmen des CI/CD-Pipeline-Setups eingef?hrt, um die sichere Verwaltung von Production-Secrets zu erm?glichen. Das automatische Setup-Script wurde am 31. Oktober 2025 hinzugef?gt, um die manuelle Erstellung zu vereinfachen.

Speicherort und Sicherheit

Dateispeicherort

• Pfad: deployment/ansible/secrets/.vault_pass
• Berechtigungen: 600 (nur Owner lesbar/schreibbar)
• Gitignored: ? Ja (in .gitignore hinterlegt)
• Inhalt: Eine Zeile mit dem Vault-Passwort (plaintext)

Sicherheitshinweise

?? WICHTIG:

• Das Passwort ist in Klartext in der Datei gespeichert
• Die Datei ist gitignored und wird nie ins Repository committet
• Berechtigungen sind auf 600 gesetzt (nur Owner-Zugriff)
• Das Passwort sollte zus?tzlich im Passwort-Manager gespeichert werden
• F?r verschiedene Umgebungen (dev/staging/prod) sollten unterschiedliche Passw?rter verwendet werden

Erstellung des Vault-Passworts

Methode 1: Automatisiertes Script (Empfohlen)

Das Script init-secrets.sh f?hrt Sie interaktiv durch den Setup-Prozess:

cd deployment/ansible
./scripts/init-secrets.sh

Was das Script macht:

1. Pr?ft, ob .vault_pass bereits existiert
2. Falls nicht vorhanden: Fragt interaktiv nach dem Passwort (mit Best?tigung)
3. Speichert das Passwort in secrets/.vault_pass
4. Setzt Berechtigungen auf 600
5. Erstellt und verschl?sselt production.vault.yml (optional)

Vorteile:

• Automatische Berechtigungen
• Passwort-Best?tigung verhindert Tippfehler
• Vollst?ndiger Setup-Workflow inkl. Vault-Datei-Erstellung

Methode 2: Manuelle Erstellung

cd deployment/ansible/secrets

# Passwort erstellen
echo "your-secure-vault-password-here" > .vault_pass

# Sicherheit: Berechtigungen setzen
chmod 600 .vault_pass

Wichtig: Verwenden Sie ein sicheres, zuf?lliges Passwort!

Verwendung des Vault-Passworts

In Ansible Playbooks

Das Vault-Passwort wird bei der Ausf?hrung von Playbooks ?bergeben:

# Beispiel: Production Secrets deployen
ansible-playbook playbooks/setup-production-secrets.yml \
  --vault-password-file secrets/.vault_pass

# Beispiel: Infrastructure deployen
ansible-playbook playbooks/setup-infrastructure.yml \
  -i inventory/production.yml \
  --vault-password-file secrets/.vault_pass

# Beispiel: Application Update deployen
ansible-playbook playbooks/deploy-update.yml \
  -e "image_tag=sha-abc123" \
  --vault-password-file secrets/.vault_pass

Vault-Dateien verwalten

# Vault-Datei entschl?sseln und anzeigen
ansible-vault view secrets/production.vault.yml \
  --vault-password-file secrets/.vault_pass

# Vault-Datei bearbeiten
ansible-vault edit secrets/production.vault.yml \
  --vault-password-file secrets/.vault_pass

# Neue Vault-Datei erstellen und verschl?sseln
ansible-vault encrypt secrets/production.vault.yml \
  --vault-password-file secrets/.vault_pass

# Vault-Datei entschl?sseln (dauerhaft)
ansible-vault decrypt secrets/production.vault.yml \
  --vault-password-file secrets/.vault_pass

CI/CD Integration

Gitea Actions

In Gitea Actions wird das Vault-Passwort als Secret gespeichert:

• Secret-Name: ANSIBLE_VAULT_PASSWORD
• Verwendung: Wird automatisch in Workflows verwendet, die Ansible-Vault ben?tigen

Hinzuf?gen des Secrets in Gitea:

1. Gehe zu: Repository Settings ? Secrets
2. Erstelle neues Secret: ANSIBLE_VAULT_PASSWORD
3. Wert: Das Vault-Passwort aus .vault_pass

Workflow-Beispiel:

- name: Deploy with Ansible
  run: |
    ansible-playbook playbooks/deploy-update.yml \
      --vault-password-file <(echo "${{ secrets.ANSIBLE_VAULT_PASSWORD }}")

Passwort zur?cksetzen/?ndern

Passwort ?ndern

Wenn das Vault-Passwort ge?ndert werden muss:

cd deployment/ansible

# 1. Alte Vault-Datei entschl?sseln (mit altem Passwort)
ansible-vault decrypt secrets/production.vault.yml \
  --vault-password-file secrets/.vault_pass

# 2. Neues Passwort setzen
echo "new-secure-vault-password" > secrets/.vault_pass
chmod 600 secrets/.vault_pass

# 3. Vault-Datei mit neuem Passwort verschl?sseln
ansible-vault encrypt secrets/production.vault.yml \
  --vault-password-file secrets/.vault_pass

# 4. Passwort im Passwort-Manager aktualisieren
# 5. CI/CD Secret in Gitea aktualisieren (ANSIBLE_VAULT_PASSWORD)

Passwort vergessen

?? Wenn das Vault-Passwort verloren geht:

• Die verschl?sselte production.vault.yml kann nicht mehr entschl?sselt werden
• Eine neue Vault-Datei muss erstellt werden
• Alle Secrets m?ssen neu konfiguriert werden
• L?sung: Passwort im Passwort-Manager speichern!

Troubleshooting

Problem: "Decryption failed"

Fehler:

ERROR! Decryption failed (no vault secrets were found)

L?sung:

1. Passwort-Datei pr?fen:

   cat deployment/ansible/secrets/.vault_pass
   

2. Korrekten Pfad verwenden:

   --vault-password-file secrets/.vault_pass
   

3. Berechtigungen pr?fen:

   ls -la deployment/ansible/secrets/.vault_pass
   # Sollte: -rw------- (600)
   

Problem: "Vault password file not found"

Fehler:

ERROR! the vault password file secrets/.vault_pass was not found

L?sung:

# Pr?fen ob Datei existiert
ls -la deployment/ansible/secrets/.vault_pass

# Falls nicht vorhanden, neu erstellen (siehe "Erstellung des Vault-Passworts")

Problem: "Permission denied"

Fehler:

Permission denied: secrets/.vault_pass

L?sung:

chmod 600 deployment/ansible/secrets/.vault_pass

Best Practices

? Empfohlene Vorgehensweise

1. Passwort-Manager: Vault-Passwort im Passwort-Manager speichern
2. Sichere Passw?rter: Verwendung von zuf?lligen, starken Passw?rtern
3. Separate Passw?rter: Verschiedene Passw?rter f?r dev/staging/prod
4. Regelm??ige Rotation: Passwort regelm??ig ?ndern (z.B. viertelj?hrlich)
5. Backup: Passwort an sicherem Ort (Passwort-Manager) sichern
6. Zugriffskontrolle: Nur autorisierte Personen sollten Zugriff haben

? Zu vermeiden

• Passwort ins Repository committen (gitignored!)
• Passwort in unverschl?sselten Dokumenten speichern
• Passwort per Email oder Chat teilen
• Einfache/erratbare Passw?rter verwenden
• Passwort mehreren Umgebungen teilen

Verwandte Dateien

• Setup-Script: deployment/ansible/scripts/init-secrets.sh
• Vault-Datei: deployment/ansible/secrets/production.vault.yml
• Vault-Template: deployment/ansible/secrets/production.vault.yml.example
• Gitignore: deployment/ansible/secrets/.gitignore
• Haupt-Dokumentation: deployment/ansible/README.md
• Setup-Guide: deployment/docs/guides/setup-guide.md

Referenzen

• Ansible Vault Dokumentation
• Ansible Vault Best Practices

Zusammenfassung

Aspekt	Details
Erstellt am	30. Oktober 2025, 21:42:27
Speicherort	deployment/ansible/secrets/.vault_pass
Berechtigungen	600 (nur Owner)
Gitignored	? Ja
Setup-Script	scripts/init-secrets.sh
CI/CD Secret	ANSIBLE_VAULT_PASSWORD
Verwendung	--vault-password-file secrets/.vault_pass