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/dexadata/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.

Which base you get when you do not pin one

When base_image is unset, leoflow compile --build writes the FROM itself, and it chooses between two tag shapes based on the CLI you are running:

• a released leoflow pins leoflow-runtime:py<ver>-v<X.Y.Z>, which is immutable, so a compile from that release reproduces byte for byte (ADR 0003)
• a development build, from source or a dirty tree, falls back to leoflow-runtime:py<ver>, a line every release republishes

So two people compiling the same project can end up on different bases if one runs a released CLI and the other runs one built from source. Setting base_image explicitly overrides both rules and is used verbatim. The full tag scheme for every published image is in Published images.

Which interpreter reads your DAG

python_version is a statement about the interpreter your DAG runs on, and the cluster honours it through the task base image. Every local tool that reads your dag.py honours it too, because a tool that judges your code with a different minor gives the wrong answer in the most confusing direction: type Alias[T] is valid from 3.12 and a SyntaxError on 3.11, so a 3.11 checker rejects a DAG the cluster runs correctly, and phrases it as a mistake in your code.

Three things follow from this that are worth knowing:

• Only an older interpreter is refused, not every different one. Python’s grammar grows, so a 3.11 checker rejects valid 3.13 code while a 3.13 checker accepts valid 3.11 code. Refusing every mismatch would have been the larger bug: leoflow init writes python_version explicitly, so every scaffolded project takes this path, and most hosts carry a newer python3 than the 3.11 it writes.
• A skipped check is reported, never silent. When only an older interpreter is around, validate would rather tell you it could not check than hand you an answer it does not trust. Install the named minor, or run leoflow setup, to turn the check back on. Your leoflow.yaml is validated either way.
• The fallback is not as strict as the declared minor. Checked under a newer interpreter, syntax that only the newer one accepts passes here and then fails on the task image. Installing the minor you declare is what makes the check exact; the fallback only guarantees that what it rejects is genuinely wrong.
• leoflow compile does not honour it yet. The parser executes your dag.py, so its own interpreter decides which syntax is legal, and today that is whichever interpreter leoflow setup baked into parser_cmd. A project declaring a newer minor can still see a SyntaxError from compile for code the cluster runs (#1095). Running leoflow setup under the minor you declare is the workaround.
• The three exemptions are the same everywhere. A version you never wrote is not a statement (the default applies), a declared base_image makes the field inert because you chose the FROM by hand, and a deprecated version warns rather than demanding you install an interpreter we are asking you to leave.

Values that reach the generated Dockerfile

Every value the generated Dockerfile interpolates is checked, because the Dockerfile format and Docker’s own operand lexer give some characters a meaning no quoting can take away. The refusal always names the field and the value, since a stray control character in YAML is invisible in the source.

Refused everywhere: a line break, a vertical tab or a form feed. These end a Dockerfile instruction or split it into new words, so a value carrying one closes the instruction it sits in and whatever follows becomes an instruction of its own. Docker splits a line on [\t\v\f\r ]+, which is why the vertical tab and form feed count alongside the newline. This covers base_image in the FROM; dbt.project, dbt_groups.*.project, dag_source and include_paths in their COPY lines; exclude_paths in the generated .dockerignore; and the dependencies and system_packages entries that already had the guard.

Refused in a COPY path: ', ", \, $ and <. After a Dockerfile is parsed, every COPY operand goes through a second pass that strips quotes, eats backslashes and expands $VAR. That pass runs whatever quoting the line used, so COPY ["d'a't.py", "..."] copies dat.py, not the file you named. None of these can be quoted into safety, so they are refused rather than silently copying the wrong path.

Refused in a COPY path: <. A different mechanism, not the operand lexer: COPY is heredoc-capable, so COPY <<EOF opens a heredoc that swallows the rest of the generated Dockerfile and then fails on the missing terminator.

This is a breaking change if one of those characters is already in your dag_source, dbt.project, dbt_groups.*.project or include_paths. An apostrophe in a directory name is not exotic. Such a project used to build, but it was copying the wrong path into the image the whole time: raw/$schema expanded to whatever the base image set, and sql\queries copied sqlqueries. The build fails now and names the field, which is the point.

Refused in base_image: any whitespace. An image reference cannot contain one, FROM has no quoting, and the rest of the line would be read as the FROM <image> AS <stage> form.

Refused in a COPY path: a leading --, which Docker reads as one of COPY’s own flags rather than as a path.

A path containing a space or a tab, or starting with [, is legal and is quoted rather than refused. Paths without any of those keep rendering exactly as before, so a project’s generated Dockerfile does not change because this guard exists.

exclude_paths is checked on the patterns that are actually emitted, not on the field alone: a dbt project path reaches the same .dockerignore through the build-artifact exclusions leoflow adds for it, so checking only the field left the class reachable through dbt.project and dbt_groups.

The same guards apply to the Dockerfile leoflow lite --executor=k8s generates when a project ships none. That one writes <project>/Dockerfile and leaves it there, and a project-supplied Dockerfile is afterwards used verbatim, so a value that slipped through there would outlive the command that wrote it.

Rotating the encryption key

LEOFLOW_SECRET_KEY takes a comma-separated list. The first entry encrypts and decrypts; every later entry only decrypts, and nothing is ever written under one. It is the same rule as Airflow’s fernet_key.

LEOFLOW_SECRET_KEY="<new key>,<old key>"

The control plane re-encrypts the stored connection secrets onto the first key at startup, logs how many it moved, and then the old key is no longer needed:

secret key rotation complete for the stored connections re_encrypted=7

Remove the old entry once every replica has started with the list. Until then it is still required, because a replica that has not restarted is still reading rows only the old key opens.

A row that no configured key can open is left untouched and reported at ERROR. Its ciphertext is the only copy of that credential, so the rotation never overwrites or deletes it; put the missing key in the list and restart.

Trying keys in order is safe because AES-256-GCM is authenticated: a wrong key fails to open rather than returning plausible garbage.

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.