263 lines
7.8 KiB
Markdown
263 lines
7.8 KiB
Markdown
# 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` |
|