Edit Readme

2026-06-26 17:37:29 +02:00
parent 1b2c24b693
commit 544d53c3b0
1 changed files with 316 additions and 1 deletions
@@ -1 +1,316 @@
-Kestra
+# Kestra Scripts
+
+Dieses Repository enthält Kestra-Flows und Hilfsskripte für Homelab-Automatisierung.
+
+Aktuell enthalten:
+
+* `docker_stack_inventory_scan.yaml`
+* `build_select_options.py`
+* `.env.example`
+
+Der erste Flow scannt mehrere Docker-Hosts per SSH, sucht nach Docker-Compose-Stacks und schreibt daraus eine Dropdown-Liste in den Kestra KV-Store.
+
+---
+
+## Zweck
+
+Dieses Repository trennt bewusst:
+
+* **Kestra-Flow**: Ablaufsteuerung und Orchestrierung
+* **Python-Script**: Verarbeitung der Scan-Ergebnisse
+* **Secrets / Zugangsdaten**: außerhalb des Repositories über `.env` bzw. Kestra Secrets
+
+Damit bleibt der Flow übersichtlich, wartbar und sicherer.
+
+---
+
+## Dateien
+
+### `docker_stack_inventory_scan.yaml`
+
+Kestra-Flow zum Scannen mehrerer Docker-Hosts.
+
+Der Flow:
+
+1. verbindet sich per SSH mit definierten Docker-Hosts
+2. durchsucht dort ein Basisverzeichnis nach Compose-Dateien
+3. sammelt gefundene Docker-Stacks ein
+4. übergibt die Ergebnisse an ein Python-Script
+5. schreibt die fertige Dropdown-Liste in den Kestra KV-Store
+
+Gesucht werden unter anderem:
+
+```text
+compose.yml
+compose.yaml
+docker-compose.yml
+docker-compose.yaml
+```
+
+---
+
+### `build_select_options.py`
+
+Python-Script zum Zusammenführen der Scan-Ergebnisse.
+
+Das Script liest die Umgebungsvariable:
+
+```text
+OPTIONS_B64_JSON
+```
+
+Darin erwartet es eine JSON-Liste mit Base64-codierten Host-Ergebnissen.
+
+Ausgabe:
+
+```text
+select_options.json
+```
+
+Diese Datei wird anschließend vom Kestra-Flow in den KV-Store geschrieben.
+
+---
+
+### `.env.example`
+
+Beispiel-Datei für benötigte Umgebungsvariablen und Secrets.
+
+Die Datei enthält bewusst nur Platzhalter.
+
+Die echte `.env` darf nicht ins Git-Repository committed werden.
+
+---
+
+## Installation
+
+Repository klonen:
+
+```bash
+git clone https://git.unixweb.net/joachim/kestra-scripts.git
+cd kestra-scripts
+```
+
+Beispiel-Umgebung kopieren:
+
+```bash
+cp .env.example .env
+```
+
+Danach die Werte in `.env` anpassen.
+
+---
+
+## Kestra Secrets
+
+Der Flow verwendet Kestra Secrets, zum Beispiel:
+
+```yaml
+privateKey: "{{ secret('SSH_PRIVATE_KEY') }}"
+```
+
+Bei Kestra OSS müssen `SECRET_*` Werte in der `.env` base64-codiert hinterlegt werden.
+
+Beispiel Linux:
+
+```bash
+echo -n "mein-geheimer-wert" | base64 -w 0
+```
+
+Beispiel macOS:
+
+```bash
+echo -n "mein-geheimer-wert" | base64
+```
+
+Beispiel für einen SSH Private Key:
+
+```bash
+base64 -w 0 ~/.ssh/id_ed25519
+```
+
+Dann in `.env` eintragen:
+
+```env
+SECRET_SSH_PRIVATE_KEY=base64_encoded_private_ssh_key
+```
+
+---
+
+## Docker Stack Inventory Scan
+
+Der Flow befindet sich in:
+
+```text
+docker_stack_inventory_scan.yaml
+```
+
+Wichtige Variablen im Flow:
+
+```yaml
+variables:
+  ssh_user: meinuser
+  base_dir: /home/meinuser/docker
+  kv_select_options_key: docker_stack_select_options
+```
+
+Die Docker-Hosts werden im Flow als Liste definiert:
+
+```yaml
+docker_hosts:
+  - docker1;192.168.100.10
+  - docker2;192.168.100.11
+```
+
+Format:
+
+```text
+hostname;ip-adresse
+```
+
+Beispiel:
+
+```text
+docker1;192.168.100.10
+```
+
+---
+
+## KV-Store Ergebnis
+
+Der Flow schreibt die Dropdown-Liste in diesen Kestra KV-Key:
+
+```text
+docker_stack_select_options
+```
+
+Die Werte haben dieses Format:
+
+```text
+hostname;ip-adresse;ssh-user;compose-verzeichnis
+```
+
+Beispiel:
+
+```text
+docker1;192.168.100.10;meinuser;/home/meinuser/docker/nextcloud
+```
+
+---
+
+## Sicherheit
+
+Dieses Repository darf keine echten Zugangsdaten enthalten.
+
+Nicht committen:
+
+```text
+.env
+SSH Private Keys
+API Tokens
+Passwörter
+Terraform State Dateien
+S3 Zugangsdaten
+OpenAI API Keys
+SMTP Passwörter
+```
+
+Empfohlene `.gitignore`:
+
+```gitignore
+.env
+.env.*
+!.env.example
+
+*.tfstate
+*.tfstate.*
+.terraform/
+
+*.pem
+*.key
+id_rsa
+id_ed25519
+
+__pycache__/
+*.pyc
+```
+
+Wichtig: Wenn ein Secret einmal versehentlich committed oder öffentlich geteilt wurde, sollte es ausgetauscht werden.
+
+---
+
+## Test des Python-Scripts
+
+Das Python-Script kann lokal getestet werden.
+
+Beispiel:
+
+```bash
+export OPTIONS_B64_JSON='["WyJkb2NrZXIxOzE5Mi4xNjguMTAwLjEwO21laW51c2VyOy9ob21lL21laW51c2VyL2RvY2tlci9uZXh0Y2xvdWQiXQ=="]'
+python3 build_select_options.py
+cat select_options.json
+```
+
+Erwartete Ausgabe:
+
+```json
+[
+  "docker1;192.168.100.10;meinuser;/home/meinuser/docker/nextcloud"
+]
+```
+
+---
+
+## Typische Fehler
+
+### Python-Script wird nicht gefunden
+
+Fehler:
+
+```text
+python3: can't open file ... build_select_options.py
+```
+
+Ursache:
+
+Das Script liegt nicht an der erwarteten Stelle im geklonten Repository.
+
+Lösung:
+
+Im Kestra-Log prüfen, welche Dateien nach dem Git-Clone vorhanden sind. Der aktuelle Flow sucht `build_select_options.py` automatisch.
+
+---
+
+### SSH-Verbindung schlägt fehl
+
+Mögliche Ursachen:
+
+* falscher SSH-Benutzer
+* falscher Host
+* SSH-Key fehlt in Kestra
+* Public Key ist auf dem Zielhost nicht in `authorized_keys`
+* Firewall blockiert Port 22
+
+---
+
+### Keine Stacks gefunden
+
+Mögliche Ursachen:
+
+* falsches `base_dir`
+* Compose-Dateien liegen tiefer als `maxdepth 2`
+* Compose-Dateien heißen anders
+* Benutzer hat keine Leserechte
+
+---
+
+## Grundsatz
+
+Die klassische Aufteilung bleibt:
+
+```text
+Kestra = Ablaufsteuerung
+Git = versionierte Logik
+Secrets = außerhalb des Repositories
+KV-Store = Laufzeitdaten für Dropdowns und Auswahlfelder
+```
+