kestra-scripts/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this repo is

A collection of Kestra workflow flows (YAML) and helper scripts (Python) for homelab automation. The flows run inside Kestra and use this Git repository as the source for versioned logic.

Core separation of concerns:

• *.yaml — Kestra flows (orchestration, task sequencing, SSH commands)
• *.py — Python scripts called at runtime by Kestra (data processing, transformation)
• .env — Secrets and credentials, never committed (see .env.example)

Testing the Python script locally

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

The script reads OPTIONS_B64_JSON (a JSON array of base64-encoded per-host results) and writes select_options.json.

Architecture: how flows use Python scripts

The docker_stack_inventory_scan flow does not bundle the Python script inline. Instead, it clones this Git repo at runtime via io.kestra.plugin.git.Clone inside a WorkingDirectory task, then finds and runs build_select_options.py dynamically using find. This means:

• Changes to .py files take effect on the next flow run without redeploying the flow
• The flow variable git_repo_url and git_branch control which repo/branch is used

Kestra secrets

Secrets are referenced in flows as {{ secret('SECRET_NAME') }}. For Kestra OSS, secrets must be stored base64-encoded in .env with the SECRET_ prefix:

# Encode a value
echo -n "my-secret-value" | base64 -w 0

# Encode an SSH private key
base64 -w 0 ~/.ssh/id_ed25519

Then in .env:

SECRET_SSH_PRIVATE_KEY=base64_encoded_value

KV-Store data format

The docker_stack_inventory_scan flow writes to the KV key docker_stack_select_options. Each entry is a semicolon-delimited string:

hostname;ip-address;ssh-user;/path/to/compose-dir

The docker_hosts variable in the flow uses the same hostname;ip-address format.

Flow namespaces

All flows use the homelab.docker namespace.

Compose file discovery

The SSH scan uses find -maxdepth 2 under base_dir. Compose files must be named exactly compose.yml, compose.yaml, docker-compose.yml, or docker-compose.yaml and located at most 2 levels deep to be detected.