jhummel
9f7cc45e86
Mark linux_apt-upgrade.yaml as work-in-progress in README, add dedicated section for it. Add CLAUDE.md with repo architecture guidance. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
326 lines
5.3 KiB
Markdown
326 lines
5.3 KiB
Markdown
# 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` *(in Arbeit)*
|
|
* `.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.
|
|
|
|
---
|
|
|
|
### `linux_apt-upgrade.yaml` *(in Arbeit)*
|
|
|
|
Kestra-Flow zum Ausführen von `apt update && apt upgrade` auf einem Linux-Server per SSH.
|
|
|
|
> **Hinweis:** Dieser Flow befindet sich noch in der Entwicklung und ist noch nicht vollständig implementiert.
|
|
|
|
---
|
|
|
|
### `.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
|
|
```
|
|
|