diff --git a/docs/README.md b/docs/README.md index 077519a..050bf3b 100644 --- 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=` 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.