os-upgrade-automation/docs/README.md

## Enterprise Auto-Upgrade Playbook für SLES & RHEL

### Ü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 (Auszug)
```
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 (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]]

Installation Collections:
```
make deps
```

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

2) Globale Variablen prüfen
- `playbook/group_vars/all.yml` enthält Standardwerte (u.a. Skip-Flags, Mail-Empfänger, Wartungsfenster, Log-Verzeichnis).

3) Dynamic Inventory (ServiceNow)
- `playbook/servicenow_inventory.yml` nutzt den ServiceNow-Inventory-Plugin.
- Erwartet in Vault: `servicenow_instance`, `servicenow_user`, `servicenow_pass`.

### Nutzung (lokal)
- Lint:
```
make lint
```

- Playbook ausführen (Beispiele):
```
# App-Gruppe patchen, Ziel-CLM setzen
make run APP=pdp-portal CLM=prod-2024-06 EXTRA="debug_mode=true"

# Direkter Aufruf
./scripts/run_patch.sh pdp-portal prod-2024-06 "skip_compliance=true skip_smoke_tests=false"
```

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`

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

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