chore: sync staging workspace
This commit is contained in:
262
deployment/docs/guides/vault-password.md
Normal file
262
deployment/docs/guides/vault-password.md
Normal file
@@ -0,0 +1,262 @@
|
||||
# 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` |
|
||||
Reference in New Issue
Block a user