docs: README aktualisiert (CI/CD, OAuth, Secrets, Nutzung)

2025-08-08 01:04:20 +00:00 · 2025-08-08 01:04:20 +00:00 · 3b17e5b405
parent 65b4fa9717
commit 3b17e5b405
1 changed files with 133 additions and 120 deletions
--- a/docs/README.md
+++ b/docs/README.md
@ -1,135 +1,148 @@
-# Enterprise Auto-Upgrade Playbook für SLES & RHEL
+## Enterprise Auto-Upgrade Playbook für SLES & RHEL

-## Übersicht
-Dieses Projekt bietet ein modulares, Enterprise-taugliches Ansible-Playbook für automatisierte Upgrades und Patch-Management von SLES (SUSE Linux Enterprise Server) und RHEL (Red Hat Enterprise Linux) Systemen. Es unterstützt:
- Automatische OS-Erkennung
- Upgrade nach Hersteller-Best-Practice
- **VMware-Snapshots für Backup/Rollback**
- Logging
- Mail-Benachrichtigung (lokal & extern via mailx)
- Dynamische Zuweisung von CLM-Channels via SUSE Manager API
+### Übersicht
+Modulares, Enterprise-taugliches Ansible-Playbook für automatisierte Upgrades/Patching von SLES und RHEL. Enthält:
+- Automatische OS-Erkennung und OS-spezifische Rollen (RHEL/SLES)
+- Upgrade nach Hersteller-Best-Practices (dnf/yum, zypper)
+- VMware-Snapshots für Backup/Rollback (vCenter API)
+- SUSE Manager API: dynamische CLM-Zuweisung via `target_clm_version`
+- Wartungsfenster-Handling, Preflight-Checks
+- Smoke-Tests (HTTP/Port/DB, inkl. Oracle SID/Listener-Erkennung)
+- Self-Healing (Service-Restarts, Cleanup, Netzwerk)
+- Compliance-Checks (OpenSCAP, Lynis)
+- Logging, Mail-Benachrichtigung (mailx), optional Slack
+- CI/CD via Gitea + Woodpecker (OAuth), Collections-Lint + Dry-Run

-## Verzeichnisstruktur
+### Verzeichnisstruktur (Auszug)
 ```
-playbook/
-├── group_vars/
-│   ├── all.yml                # Globale Variablen
-│   └── vault.yml              # Verschlüsselte Zugangsdaten (Vault)
-├── host_vars/                 # (Optional) Host-spezifische Variablen
-├── inventories/               # (Optional) Inventare
-├── playbook.yml               # Haupt-Playbook
-├── README.md                  # Diese Datei
-└── roles/
-    ├── common/                # Gemeinsame Tasks (z.B. Logging, mailx)
-    ├── rhel_upgrade/          # RHEL-spezifische Upgrade-Tasks
-    ├── sles_upgrade/          # SLES-spezifische Upgrade-Tasks
-    ├── post_upgrade/          # Reboot etc.
-    ├── suma_api_assign_clm/   # SUSE Manager API Integration
-    └── vmware_snapshot/       # VMware Snapshot Handling
+os-upgrade-automation/
+├── ansible.cfg
+├── docs/
+│   ├── README.md
+│   ├── CHANGELOG.md
+│   └── Runbook_SelfService.md
+├── playbook/
+│   ├── group_vars/
+│   │   ├── all.yml
+│   │   └── vault.yml            # Mit Ansible Vault verschlüsseln
+│   ├── host_vars/
+│   ├── playbook.yml
+│   ├── requirements.yml
+│   ├── servicenow_inventory.yml # Dynamic Inventory (ServiceNow)
+│   └── roles/
+│       ├── common/
+│       ├── preflight_check/
+│       ├── vmware_snapshot/
+│       ├── suma_api_assign_clm/
+│       ├── rhel_upgrade/
+│       ├── sles_upgrade/
+│       ├── post_upgrade/
+│       ├── smoke_tests/
+│       ├── self_healing/
+│       └── compliance_check/
+├── scripts/
+│   ├── install_collections.sh
+│   └── run_patch.sh
+└── .woodpecker.yml
 ```

-## Voraussetzungen
- Ansible >= 2.9
- python3-pyvmomi auf dem Ansible-Host (für VMware)
- Zielsysteme: SLES oder RHEL, angebunden an SUSE Manager (ggf. venv-salt-minion)
- Zugang zur SUSE Manager API (XML-RPC, meist Port 443)
- Zugang zum vCenter (API)
- Optional: Ansible Vault für sichere Zugangsdaten
+### Voraussetzungen
+- Ansible (empfohlen ≥ 2.14)
+- Collections: `community.vmware`, `servicenow.servicenow`, `community.general`
+- vCenter-Zugriff (API), SUSE Manager API-Zugang
+- Zielsysteme: SLES oder RHEL (ggf. via SUSE Manager, venv-salt-minion)
+- Ansible Vault für Secrets (zwingend empfohlen) [[Speicherpräferenz]]

-## Nutzung
-1. **Zugangsdaten für SUSE Manager & vCenter sicher speichern**
-   - Erstelle eine Datei `vault.yml` in `group_vars`:
-     ```yaml
-     suma_api_url: "https://susemanager.example.com/rpc/api"
-     suma_api_user: "admin"
-     suma_api_pass: "geheim"
-     vcenter_hostname: "vcenter.example.com"
-     vcenter_user: "administrator@vsphere.local"
-     vcenter_password: "dein_passwort"
-     vcenter_datacenter: "DeinDatacenter"
-     vcenter_folder: "/"
-     ```
-   - Verschlüssele die Datei mit Ansible Vault:
-     ```bash
-     ansible-vault encrypt playbook/group_vars/vault.yml
-     ```
-   - Passe `group_vars/all.yml` an:
-     ```yaml
-     # ... bestehende Variablen ...
-     suma_api_url: "{{ vault_suma_api_url }}"
-     suma_api_user: "{{ vault_suma_api_user }}"
-     suma_api_pass: "{{ vault_suma_api_pass }}"
-     vcenter_hostname: "{{ vault_vcenter_hostname }}"
-     vcenter_user: "{{ vault_vcenter_user }}"
-     vcenter_password: "{{ vault_vcenter_password }}"
-     vcenter_datacenter: "{{ vault_vcenter_datacenter }}"
-     vcenter_folder: "{{ vault_vcenter_folder }}"
-     ```
-   - Lade die Vault-Datei im Playbook:
-     ```yaml
-     vars_files:
-       - group_vars/all.yml
-       - group_vars/vault.yml
-     ```
-   - Playbook-Aufruf mit Vault-Passwort:
-     ```bash
-     ansible-playbook playbook.yml --ask-vault-pass -e "target_clm_version=prod-2024-06"
-     ```
+Installation Collections:
+```
+make deps
+```

-2. **VMware Snapshot Handling**
-   - Vor jedem Upgrade wird automatisch ein Snapshot erstellt.
-   - Bei aktiviertem Rollback (Variable `rollback: true`) wird die VM auf den Snapshot zurückgesetzt.
-   - Die Snapshot-Tasks laufen auf dem Ansible-Host (`delegate_to: localhost`).
+### Konfiguration
+1) Secrets sicher ablegen (Vault)
+- `playbook/group_vars/vault.yml` befüllen (ServiceNow, SUSE Manager, vCenter, SMTP, Slack, DB)
+- Datei sofort verschlüsseln:
+```
+ansible-vault encrypt playbook/group_vars/vault.yml
+```

-3. **Upgrade auf bestimmte CLM-Version**
-   - Beim Playbook-Aufruf die gewünschte Version angeben:
-     ```bash
-     ansible-playbook playbook.yml -e "target_clm_version=prod-2024-06"
-     ```
-   - Das System wird per SUSE Manager API dem passenden Channel zugewiesen.
+2) Globale Variablen prüfen
+- `playbook/group_vars/all.yml` enthält Standardwerte (u.a. Skip-Flags, Mail-Empfänger, Wartungsfenster, Log-Verzeichnis).

-4. **Rollback aktivieren (optional)**
-   - In `group_vars/all.yml`:
-     ```yaml
-     rollback: true
-     ```
-   - Das Playbook setzt die VM dann auf den Snapshot zurück.
+3) Dynamic Inventory (ServiceNow)
+- `playbook/servicenow_inventory.yml` nutzt den ServiceNow-Inventory-Plugin.
+- Erwartet in Vault: `servicenow_instance`, `servicenow_user`, `servicenow_pass`.

-5. **Mail-Benachrichtigung konfigurieren**
-   - Lokale Mail: `mail_to: "root@localhost"`
-   - Externer SMTP:
-     ```yaml
-     mail_smtp_host: "smtp.example.com"
-     mail_smtp_port: 587
-     mail_smtp_user: "user@example.com"
-     mail_smtp_pass: "dein_passwort"
-     ```
+### Nutzung (lokal)
+- Lint:
+```
+make lint
+```

-## Wichtige Variablen (group_vars/all.yml)
- `upgrade_dry_run`: true/false (Simulation)
- `reboot_after_upgrade`: true/false
- `log_dir`: Logverzeichnis
- `rollback`: true/false
- `mail_to`: Empfängeradresse
- `mail_smtp_*`: SMTP-Parameter (optional)
- `target_clm_version`: Ziel-CLM-Channel (z.B. prod-2024-06)
- `suma_api_url`, `suma_api_user`, `suma_api_pass`: SUSE Manager API (empfohlen: Vault)
- `vcenter_hostname`, `vcenter_user`, `vcenter_password`, `vcenter_datacenter`, `vcenter_folder`: VMware/vCenter (empfohlen: Vault)
+- Playbook ausführen (Beispiele):
+```
+# App-Gruppe patchen, Ziel-CLM setzen
+make run APP=pdp-portal CLM=prod-2024-06 EXTRA="debug_mode=true"

-## Sicherheitshinweis
-**Lege Zugangsdaten (API, Mail, vCenter) niemals im Klartext ab!** Nutze immer Ansible Vault für sensible Daten.
+# Direkter Aufruf
+./scripts/run_patch.sh pdp-portal prod-2024-06 "skip_compliance=true skip_smoke_tests=false"
+```

-## Erweiterungsideen
- Integration mit Monitoring/Alerting
- Approval-Workflows
- Reporting
- Zusätzliche OS-Unterstützung
+Wichtige Extra-Variablen / Skip-Flags:
+- `target_clm_version` (z.B. `prod-2024-06`)
+- `debug_mode=true|false`
+- `skip_vmware_snapshot`, `skip_suma_api`, `skip_post_upgrade`
+- `skip_smoke_tests`, `skip_self_healing`, `skip_compliance`
+- `upgrade_security_only=true|false`

-## Support & Doku
- [SUSE Manager API Doku](https://documentation.suse.com/suma/)
- [Red Hat Upgrade Guide](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/)
- [SLES Upgrade Guide](https://documentation.suse.com/sles/)
- [Ansible VMware Doku](https://docs.ansible.com/ansible/latest/collections/community/vmware/vmware_guest_snapshot_module.html)
+### Rollenüberblick
+- `preflight_check`: Diskspace, Wartungsfenster, Erreichbarkeit, Channel-Sync, pyVmomi-Check
+- `vmware_snapshot`: Snapshot anlegen, optional Revert, optional Cleanup
+- `suma_api_assign_clm`: System dynamisch CLM-Channel zuordnen
+- `rhel_upgrade` / `sles_upgrade`: OS-spezifisches Upgrade, Kernel-Erkennung, Reboot-Flag
+- `post_upgrade`: Reboot (optional), Health-Check kritischer Dienste
+- `smoke_tests`: HTTP/Port/DB, Oracle (SIDs/Listener dynamisch erkannt)
+- `self_healing`: Dienst-Restarts, Disk-Cleanup, Netzwerk-Remediation
+- `compliance_check`: OpenSCAP, Lynis, Reporting & Mail
+- `common`: Logging, mailx-Konfiguration, Admin-Mail inkl. Log-Anhänge, Slack (optional)

---
-**Fragen oder Wünsche? Einfach melden!**
+### VMware Snapshot & Rollback
+- Vor dem Upgrade wird ein Snapshot mit Zeitstempel erstellt.
+- Bei Fehlern kann automatisch ein Rollback getriggert werden (`rollback: true`).
+- Optionales automatisches Löschen alter Snapshots nach erfolgreichem Lauf (`snapshot_cleanup`).
+
+### Logging & Benachrichtigung
+- Logs in `log_dir` (Standard: `/var/log/auto-upgrade`).
+- Admin-Mail an `linux_admins_mail` mit Log-Summary + Anhängen.
+- Failsafe-Mail an App- und Host-Kontakte bei Fehler.
+- Optional Slack-Benachrichtigung (wenn `slack_enabled` und `slack_token`).
+
+### CI/CD (Gitea + Woodpecker)
+1) Repo in Woodpecker aktivieren
+- In `https://ci.pp1l.de` auf “Repos” → “Sync” → `os-upgrade-automation` (oder `PurePowerPh1l/os-upgrade-automation`) “Enable”.
+
+2) Secrets in Woodpecker setzen
+- Mindestens `ANSIBLE_VAULT_PASSWORD` (für CI-Läufe ohne Interaktion).
+- Optional: `SERVICENOW_*`, `SUMA_*`, `VCENTER_*`, `SLACK_TOKEN`, SMTP-Variablen, DB-Testdaten.
+
+3) Pipelines
+- `.woodpecker.yml` enthält: `lint`, `dryrun`, manuell `run_preflight`, `run_patch`.
+- Hinweis: Interaktive Prompts (`--ask-vault-pass`) funktionieren in CI nicht. Nutze stattdessen eine Secret-basierte Lösung (z.B. Secret als Datei schreiben und `--vault-password-file` verwenden). Passe die Pipeline bei Bedarf an.
+
+4) OAuth/Troubleshooting
+- “Unregistered Redirect URI”: Stelle sicher, dass die Gitea-OAuth-App `https://ci.pp1l.de/authorize` als Redirect-URI nutzt.
+- “PKCE is required for public clients”: Gitea-OAuth-App als Confidential Client anlegen.
+- “registration_closed”: In Woodpecker `WOODPECKER_OPEN=false`, erlaubte Nutzer via `WOODPECKER_ADMIN=<user1,user2>` whitelisten.
+
+### Sicherheit
+- Keine Secrets im Klartext: Alles in `playbook/group_vars/vault.yml` ablegen und per Vault verschlüsseln [[Speicherpräferenz]].
+- Zugriffsdaten in CI ausschließlich als Secrets verwalten.
+
+### Nützliche Links
+- Gitea: `https://git.pp1l.de`
+- Woodpecker CI: `https://ci.pp1l.de`
+- Ansible VMware Snapshot Modul: `https://docs.ansible.com/ansible/latest/collections/community/vmware/vmware_guest_snapshot_module.html`
+- SUSE Manager: `https://documentation.suse.com/suma/`
+
+—
+Fragen oder Wünsche? Gerne melden.