# 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:

```bash
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

```bash
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:

```bash
# 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

```bash
# 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:**
```yaml
- 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:

```bash
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:
   ```bash
   cat deployment/ansible/secrets/.vault_pass
   ```
2. Korrekten Pfad verwenden:
   ```bash
   --vault-password-file secrets/.vault_pass
   ```
3. Berechtigungen pr?fen:
   ```bash
   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:**
```bash
# 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:**
```bash
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`](../../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`](../../ansible/README.md)
- **Setup-Guide:** [`deployment/docs/guides/setup-guide.md`](setup-guide.md)

## Referenzen

- [Ansible Vault Dokumentation](https://docs.ansible.com/ansible/latest/user_guide/vault.html)
- [Ansible Vault Best Practices](https://docs.ansible.com/ansible/latest/user_guide/vault.html#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` |