Configuration

Two surfaces: leoflow.yaml (per-DAG, authoring) and server environment (LEOFLOW_*, the control plane). The canonical leoflow.yaml schema is docs/api/leoflow-yaml-schema.json.

leoflow.yaml

See DAG authoring for the override layers.

Python version support

Every value the schema accepts has a published, multi-arch, cosign-signed base image at ghcr.io/neochaotic/leoflow-runtime:py<version>. Nothing else does — if a version is not in the table above, no base image exists for it and the build fails on the pull.

Published until is the last date on which a release publishes that leg; a release cut after it ships no py<line> image. A — means the line is supported with no removal date set. The Status and Published-until cells are generated from nothing — they are written by hand — but scripts/check-python-runtime-matrix.sh reconciles them against the x-leoflow-python-deprecations block in the authoring schema, so a deprecation that moves in the schema and not here fails the build rather than leaving this table quietly telling you the opposite.

3.13 is the current ceiling, and it is set by the dbt adapters rather than by Airflow: dbt-core and dbt-postgres publish for 3.14, but dbt-snowflake, dbt-bigquery, dbt-databricks and dbt-duckdb stop at 3.13. A py3.14 base would give you an image where dbt-postgres installs and dbt-snowflake does not — discovered inside your build, not ours — so it is not published.

3.10 is deprecated. Python 3.10 reaches upstream end-of-life on 2026-10-31, and docker-library/python stops rebuilding an EOL line the day after (python:3.9-slim was last rebuilt 2025-11-01, one day after 3.9 went EOL). From that point python:3.10-slim — and so leoflow-runtime:py3.10 — receives no further OS security updates and accumulates unfixed CVEs indefinitely. The py3.10 leg keeps being published until 2026-10-31, so nothing breaks today; leoflow validate, leoflow compile and leoflow deploy warn when your project resolves to it.

There are two ways to resolve to it, and they have different fixes:

• You set python_version: "3.10". Set python_version: "3.11" (or later) and rebuild.
• You pinned base_image to a published py3.10 tag (…:py3.10, …:py3.10-v0.4.5). Repoint base_image to the matching py3.11 tag and rebuild. Changing python_version here does nothing: when base_image is set it is used verbatim and python_version is not consulted for the FROM.

Existing images keep running either way; the rebuild is what moves you.

This matters more than for most images because it is inherited: a DAG image is built FROM this base, so pinning base_image freezes your DAG on whatever the base was on the day you pinned it.

Defaults

Every field in leoflow.yaml is optional. Zero-valued fields are filled by LeoflowConfig.ApplyDefaults() (internal/domain/config.go) from the values declared in leoflow-yaml-schema.json. Defaults are hardcoded for v1; making them workspace-configurable is a v2 roadmap item.

Server environment (LEOFLOW_*)

This page is hand-maintained against the server’s configuration struct and default map in internal/config/server.go — treat that source as the final authority. Every LEOFLOW_* variable maps to a config key by upper-casing it and replacing . (and -) with _: e.g. auth.oidc.client_id → LEOFLOW_AUTH_OIDC_CLIENT_ID. The same keys can be set in a YAML config file. The Helm chart models many of them as values, but not all: a key with no chart value has to go through extraEnv. The two OIDC maps below are the exception in both directions: no env var can carry them, so extraEnv is not a route, and the chart delivers them by writing a partial config file into a mounted ConfigMap (auth.oidc.tenantClaims, auth.oidc.roleMappings).

Values resolve in increasing order of precedence — a later source overrides an earlier one:

flowchart LR
  D["Built-in defaults<br/>(serverDefaults)"] --> C["Config file<br/>(YAML)"]
  C --> E["LEOFLOW_* env vars"]
  E --> F["CLI flags"]

The Edition column reads both (Lite and Pro), Pro (Pro / Kubernetes topologies only), or dev-only. leoflow lite sets the dev-appropriate values automatically (isolated DB, port 8088, admin login on, no Redis).

List-valued keys (CORS origins, OIDC scopes, allowed email domains, break-glass emails, trusted proxies) DO come from a single env var: viper’s decode hook splits a comma-separated value into a list, so LEOFLOW_AUTH_OIDC_SCOPES=openid,email works. That is how the Helm chart sets them, since it ships no server config file. In a config file they are ordinary YAML lists.

Map-valued keys do not. auth.oidc.role_mappings and auth.oidc.tenant_claims are read only from a YAML config file, because their keys may contain dots (an IdP group name, a Google Workspace domain) and a dotted key is ambiguous in both env and viper’s own key space. The chart sets them through auth.oidc.tenantClaims and auth.oidc.roleMappings, which it renders into a ConfigMap mounted as the server’s LEOFLOW_CONFIG file, with the keys quoted so a dotted domain survives (#1143). That file is deliberately partial: it carries only these two keys, so it can never override a setting the chart delivers as an env var.

In the tables below, the row name tells you which of these two groups a key is in: a row named after its LEOFLOW_* env var binds from that env var (and so from extraEnv or a chart value that sets it); a row named after its dotted config key (e.g. auth.oidc.role_mappings) is config-file-only.

Server (server.*)

Database (database.*)

Redis (redis.*)

Auth (auth.*)

OIDC / SSO (auth.oidc.*)

Read only when LEOFLOW_AUTH_PROVIDER=oidc, which is Pro-gated (ui.edition: pro) and fails boot closed unless issuer, client_id, redirect_url and the tenant pin (tenant_claim + tenant_claims) are all set. The pin is in that set because every login resolves a tenant from it and an absent or unmapped claim value fails the login closed, never falling back to default, so a deployment without it boots green and rejects 100% of logins (#1143). tenant_claims is a map, so it loads only from the YAML config file named by LEOFLOW_CONFIG; no env var can carry it. A blank name on either side of an entry in tenant_claims or role_mappings fails boot: corp.example: with nothing after it is valid YAML that binds to the empty string, and it would deny every login it governs while looking like a key you had filled in. Verification is keyless (the ID token is validated against the issuer’s public JWKS), so no secret is stored for the verify path.

Every key in this section has a modeled Helm value under auth.oidc.*, off by default (auth.oidc.enabled: false, which renders nothing at all). The chart sends the scalars and lists as LEOFLOW_AUTH_OIDC_* env vars, the two maps as a mounted config file, and the client secret through the chart-managed Secret or auth.oidc.existingSecret. It refuses to render an enabled: true block that lacks the tenant pin. See the chart README’s SSO section and helm/leoflow/examples/values-oidc-google.yaml.

Scheduler (scheduler.*)

Executor (executor.*)

Executor task defaults (executor.defaults.*)

Lowest-precedence (L0) per-cluster task defaults, applied at dispatch to fill gaps the DAG artifact left empty (ADR 0023). They never override a value baked into dag.json, keeping the artifact portable across clusters.

Warm worker pools (execution.*)

Pro-gated N:1 pod reuse (ADR 0058). Every field is operator-set. The default is a byte-for-byte no-op — warm pools OFF means a dedicated pod per task attempt.

Logs (logs.*)

External secrets (secrets.*)

Operator-only (ADR 0060): delivered to the task pod as LEOFLOW_SECRETS_*, which an author’s task env can never set. Empty backend keeps the Leoflow vault as the only source — byte-identical to having no external secrets at all. See External secrets and run the cluster validation runbook before enabling it in production.

Observability (observability.*)

UI (ui.*)

Trusted proxies and the client IP

By default Leoflow trusts no proxy: X-Forwarded-For is ignored and the client IP (used by the login rate-limiter and the audit log) is the direct peer. This is the safe default — it stops a spoofed X-Forwarded-For from forging the client IP — and is correct for Lite (exposed directly) and for any deployment reached without a reverse proxy.

When the API runs behind a reverse proxy or ingress, set server.trusted_proxies (env LEOFLOW_SERVER_TRUSTED_PROXIES) to the proxy’s IP or CIDR — e.g. your ingress controller’s pod CIDR. Only then is the left-most X-Forwarded-For entry honored, so rate-limiting and audit see the real client instead of the proxy. Do not set this to a broad private range (e.g. all of 10.0.0.0/8) in a cluster where task pods run: a task pod inside that range could then spoof the client IP. Scope it to the ingress. An invalid value fails secure (trust none) with a logged error.

The value is a list. Via the env var (the Helm chart’s only override path — it ships no server config file) set it comma-separated, e.g. LEOFLOW_SERVER_TRUSTED_PROXIES=10.0.0.0/8,192.168.1.1; viper splits it back into a list. In the chart set the config.trustedProxies value (a YAML list) and it is rendered comma-joined for you. In a config file it is an ordinary YAML list.