joachim/kestra-scripts
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
56a5afddc24b18155b5b99aa663a5a75507742ce
kestra-scripts/README.md
T
jhummel 56a5afddc2 add hetzner-vm-provision flow and document it in README 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-06-26 17:59:52 +02:00

7.0 KiB
Raw Blame History

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
  • linux_apt-upgrade.yaml
  • hetzner-vm-provision.yaml
  • .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:

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:

OPTIONS_B64_JSON

Darin erwartet es eine JSON-Liste mit Base64-codierten Host-Ergebnissen.

Ausgabe:

select_options.json

Diese Datei wird anschließend vom Kestra-Flow in den KV-Store geschrieben.

linux_apt-upgrade.yaml

Kestra-Flow zum Ausführen von apt update && apt upgrade auf einem Linux-Server per SSH.

Der Flow:

  1. verbindet sich per SSH mit dem Zielserver
  2. erkennt automatisch ob der Benutzer root ist oder sudo benötigt
  3. führt apt-get update und apt-get upgrade aus
  4. meldet ob ein Reboot erforderlich ist

Der Flow wird manuell gestartet und erwartet folgende Eingaben:

Input Beschreibung
host Server IP oder Hostname
user SSH-Benutzer
sudo_password Sudo-Passwort (Kestra Secret)

Benötigtes Kestra Secret:

SSH_PRIVATE_KEY

linux-apt-upgrade Flow

hetzner-vm-provision.yaml

Kestra-Flow zum Provisionieren einer Hetzner Cloud VM via Terraform — mit KI-gestützter Plan-Analyse und manuellem Approval-Gate.

Namespace: hetzner

Der Flow läuft in vier Phasen:

  1. Terraform Plan — erstellt einen Plan für die neue VM (Ubuntu 24.04) im Hetzner-Datacenter; Terraform State wird im S3-Backend (Hetzner Object Storage) gespeichert
  2. LLM-Analyse — GPT-4o-mini fasst den Plan auf Deutsch zusammen und bewertet ob er sicher aussieht
  3. Approval-Gate — Kestra pausiert und wartet auf manuelle Freigabe
  4. Terraform Apply / Abbruch — bei Freigabe wird die VM erstellt und die IPv4-Adresse ausgegeben; bei Ablehnung wird die Execution abgebrochen

Der Flow erwartet folgende Eingaben:

Input Typ Beschreibung
vm_name STRING Eindeutiger VM-Name, z.B. dev-server-01
server_type SELECT cx23 (2 vCPU / 4 GB) · cx33 · cx43 · cx53
location SELECT nbg1 · fsn1 · hel1
team STRING Label für die VM

Benötigte Kestra Secrets:

HCLOUD_TOKEN
SSH_KEY_NAME
AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
TF_BACKEND_BUCKET
TF_BACKEND_ENDPOINT
OPENAI_API_KEY

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

git clone https://git.unixweb.net/joachim/kestra-scripts.git
cd kestra-scripts

Beispiel-Umgebung kopieren:

cp .env.example .env

Danach die Werte in .env anpassen.

Kestra Secrets

Der Flow verwendet Kestra Secrets, zum Beispiel:

privateKey: "{{ secret('SSH_PRIVATE_KEY') }}"

Bei Kestra OSS müssen SECRET_* Werte in der .env base64-codiert hinterlegt werden.

Beispiel Linux:

echo -n "mein-geheimer-wert" | base64 -w 0

Beispiel macOS:

echo -n "mein-geheimer-wert" | base64

Beispiel für einen SSH Private Key:

base64 -w 0 ~/.ssh/id_ed25519

Dann in .env eintragen:

SECRET_SSH_PRIVATE_KEY=base64_encoded_private_ssh_key

Docker Stack Inventory Scan

Der Flow befindet sich in:

docker_stack_inventory_scan.yaml

Wichtige Variablen im Flow:

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:

docker_hosts:
  - docker1;192.168.100.10
  - docker2;192.168.100.11

Format:

hostname;ip-adresse

Beispiel:

docker1;192.168.100.10

KV-Store Ergebnis

Der Flow schreibt die Dropdown-Liste in diesen Kestra KV-Key:

docker_stack_select_options

Die Werte haben dieses Format:

hostname;ip-adresse;ssh-user;compose-verzeichnis

Beispiel:

docker1;192.168.100.10;meinuser;/home/meinuser/docker/nextcloud

Sicherheit

Dieses Repository darf keine echten Zugangsdaten enthalten.

Nicht committen:

.env
SSH Private Keys
API Tokens
Passwörter
Terraform State Dateien
S3 Zugangsdaten
OpenAI API Keys
SMTP Passwörter

Empfohlene .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:

export OPTIONS_B64_JSON='["WyJkb2NrZXIxOzE5Mi4xNjguMTAwLjEwO21laW51c2VyOy9ob21lL21laW51c2VyL2RvY2tlci9uZXh0Y2xvdWQiXQ=="]'
python3 build_select_options.py
cat select_options.json

Erwartete Ausgabe:

[
  "docker1;192.168.100.10;meinuser;/home/meinuser/docker/nextcloud"
]

Typische Fehler

Python-Script wird nicht gefunden

Fehler:

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:

Kestra = Ablaufsteuerung
Git = versionierte Logik
Secrets = außerhalb des Repositories
KV-Store = Laufzeitdaten für Dropdowns und Auswahlfelder
Reference in New Issue View Git Blame Copy Permalink