docs: README aktualisiert (CI/CD, OAuth, Secrets, Nutzung)
This commit is contained in:
Automation Admin
parent
65b4fa9717
commit
3b17e5b405
253
docs/README.md
253
docs/README.md
|
|
@ -1,135 +1,148 @@
|
||||||
# Enterprise Auto-Upgrade Playbook für SLES & RHEL
|
## Enterprise Auto-Upgrade Playbook für SLES & RHEL
|
||||||
|
|
||||||
## Übersicht
|
### Ü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:
|
Modulares, Enterprise-taugliches Ansible-Playbook für automatisierte Upgrades/Patching von SLES und RHEL. Enthält:
|
||||||
- Automatische OS-Erkennung
|
- Automatische OS-Erkennung und OS-spezifische Rollen (RHEL/SLES)
|
||||||
- Upgrade nach Hersteller-Best-Practice
|
- Upgrade nach Hersteller-Best-Practices (dnf/yum, zypper)
|
||||||
- **VMware-Snapshots für Backup/Rollback**
|
- VMware-Snapshots für Backup/Rollback (vCenter API)
|
||||||
- Logging
|
- SUSE Manager API: dynamische CLM-Zuweisung via `target_clm_version`
|
||||||
- Mail-Benachrichtigung (lokal & extern via mailx)
|
- Wartungsfenster-Handling, Preflight-Checks
|
||||||
- Dynamische Zuweisung von CLM-Channels via SUSE Manager API
|
- 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/
|
os-upgrade-automation/
|
||||||
├── group_vars/
|
├── ansible.cfg
|
||||||
│ ├── all.yml # Globale Variablen
|
├── docs/
|
||||||
│ └── vault.yml # Verschlüsselte Zugangsdaten (Vault)
|
│ ├── README.md
|
||||||
├── host_vars/ # (Optional) Host-spezifische Variablen
|
│ ├── CHANGELOG.md
|
||||||
├── inventories/ # (Optional) Inventare
|
│ └── Runbook_SelfService.md
|
||||||
├── playbook.yml # Haupt-Playbook
|
├── playbook/
|
||||||
├── README.md # Diese Datei
|
│ ├── group_vars/
|
||||||
└── roles/
|
│ │ ├── all.yml
|
||||||
├── common/ # Gemeinsame Tasks (z.B. Logging, mailx)
|
│ │ └── vault.yml # Mit Ansible Vault verschlüsseln
|
||||||
├── rhel_upgrade/ # RHEL-spezifische Upgrade-Tasks
|
│ ├── host_vars/
|
||||||
├── sles_upgrade/ # SLES-spezifische Upgrade-Tasks
|
│ ├── playbook.yml
|
||||||
├── post_upgrade/ # Reboot etc.
|
│ ├── requirements.yml
|
||||||
├── suma_api_assign_clm/ # SUSE Manager API Integration
|
│ ├── servicenow_inventory.yml # Dynamic Inventory (ServiceNow)
|
||||||
└── vmware_snapshot/ # VMware Snapshot Handling
|
│ └── 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
|
### Voraussetzungen
|
||||||
- Ansible >= 2.9
|
- Ansible (empfohlen ≥ 2.14)
|
||||||
- python3-pyvmomi auf dem Ansible-Host (für VMware)
|
- Collections: `community.vmware`, `servicenow.servicenow`, `community.general`
|
||||||
- Zielsysteme: SLES oder RHEL, angebunden an SUSE Manager (ggf. venv-salt-minion)
|
- vCenter-Zugriff (API), SUSE Manager API-Zugang
|
||||||
- Zugang zur SUSE Manager API (XML-RPC, meist Port 443)
|
- Zielsysteme: SLES oder RHEL (ggf. via SUSE Manager, venv-salt-minion)
|
||||||
- Zugang zum vCenter (API)
|
- Ansible Vault für Secrets (zwingend empfohlen) [[Speicherpräferenz]]
|
||||||
- Optional: Ansible Vault für sichere Zugangsdaten
|
|
||||||
|
|
||||||
## Nutzung
|
Installation Collections:
|
||||||
1. **Zugangsdaten für SUSE Manager & vCenter sicher speichern**
|
```
|
||||||
- Erstelle eine Datei `vault.yml` in `group_vars`:
|
make deps
|
||||||
```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"
|
|
||||||
```
|
|
||||||
|
|
||||||
2. **VMware Snapshot Handling**
|
### Konfiguration
|
||||||
- Vor jedem Upgrade wird automatisch ein Snapshot erstellt.
|
1) Secrets sicher ablegen (Vault)
|
||||||
- Bei aktiviertem Rollback (Variable `rollback: true`) wird die VM auf den Snapshot zurückgesetzt.
|
- `playbook/group_vars/vault.yml` befüllen (ServiceNow, SUSE Manager, vCenter, SMTP, Slack, DB)
|
||||||
- Die Snapshot-Tasks laufen auf dem Ansible-Host (`delegate_to: localhost`).
|
- Datei sofort verschlüsseln:
|
||||||
|
```
|
||||||
|
ansible-vault encrypt playbook/group_vars/vault.yml
|
||||||
|
```
|
||||||
|
|
||||||
3. **Upgrade auf bestimmte CLM-Version**
|
2) Globale Variablen prüfen
|
||||||
- Beim Playbook-Aufruf die gewünschte Version angeben:
|
- `playbook/group_vars/all.yml` enthält Standardwerte (u.a. Skip-Flags, Mail-Empfänger, Wartungsfenster, Log-Verzeichnis).
|
||||||
```bash
|
|
||||||
ansible-playbook playbook.yml -e "target_clm_version=prod-2024-06"
|
|
||||||
```
|
|
||||||
- Das System wird per SUSE Manager API dem passenden Channel zugewiesen.
|
|
||||||
|
|
||||||
4. **Rollback aktivieren (optional)**
|
3) Dynamic Inventory (ServiceNow)
|
||||||
- In `group_vars/all.yml`:
|
- `playbook/servicenow_inventory.yml` nutzt den ServiceNow-Inventory-Plugin.
|
||||||
```yaml
|
- Erwartet in Vault: `servicenow_instance`, `servicenow_user`, `servicenow_pass`.
|
||||||
rollback: true
|
|
||||||
```
|
|
||||||
- Das Playbook setzt die VM dann auf den Snapshot zurück.
|
|
||||||
|
|
||||||
5. **Mail-Benachrichtigung konfigurieren**
|
### Nutzung (lokal)
|
||||||
- Lokale Mail: `mail_to: "root@localhost"`
|
- Lint:
|
||||||
- Externer SMTP:
|
```
|
||||||
```yaml
|
make lint
|
||||||
mail_smtp_host: "smtp.example.com"
|
```
|
||||||
mail_smtp_port: 587
|
|
||||||
mail_smtp_user: "user@example.com"
|
|
||||||
mail_smtp_pass: "dein_passwort"
|
|
||||||
```
|
|
||||||
|
|
||||||
## Wichtige Variablen (group_vars/all.yml)
|
- Playbook ausführen (Beispiele):
|
||||||
- `upgrade_dry_run`: true/false (Simulation)
|
```
|
||||||
- `reboot_after_upgrade`: true/false
|
# App-Gruppe patchen, Ziel-CLM setzen
|
||||||
- `log_dir`: Logverzeichnis
|
make run APP=pdp-portal CLM=prod-2024-06 EXTRA="debug_mode=true"
|
||||||
- `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)
|
|
||||||
|
|
||||||
## Sicherheitshinweis
|
# Direkter Aufruf
|
||||||
**Lege Zugangsdaten (API, Mail, vCenter) niemals im Klartext ab!** Nutze immer Ansible Vault für sensible Daten.
|
./scripts/run_patch.sh pdp-portal prod-2024-06 "skip_compliance=true skip_smoke_tests=false"
|
||||||
|
```
|
||||||
|
|
||||||
## Erweiterungsideen
|
Wichtige Extra-Variablen / Skip-Flags:
|
||||||
- Integration mit Monitoring/Alerting
|
- `target_clm_version` (z.B. `prod-2024-06`)
|
||||||
- Approval-Workflows
|
- `debug_mode=true|false`
|
||||||
- Reporting
|
- `skip_vmware_snapshot`, `skip_suma_api`, `skip_post_upgrade`
|
||||||
- Zusätzliche OS-Unterstützung
|
- `skip_smoke_tests`, `skip_self_healing`, `skip_compliance`
|
||||||
|
- `upgrade_security_only=true|false`
|
||||||
|
|
||||||
## Support & Doku
|
### Rollenüberblick
|
||||||
- [SUSE Manager API Doku](https://documentation.suse.com/suma/)
|
- `preflight_check`: Diskspace, Wartungsfenster, Erreichbarkeit, Channel-Sync, pyVmomi-Check
|
||||||
- [Red Hat Upgrade Guide](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/)
|
- `vmware_snapshot`: Snapshot anlegen, optional Revert, optional Cleanup
|
||||||
- [SLES Upgrade Guide](https://documentation.suse.com/sles/)
|
- `suma_api_assign_clm`: System dynamisch CLM-Channel zuordnen
|
||||||
- [Ansible VMware Doku](https://docs.ansible.com/ansible/latest/collections/community/vmware/vmware_guest_snapshot_module.html)
|
- `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
|
||||||
**Fragen oder Wünsche? Einfach melden!**
|
- 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.
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue