Configuration

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

dexaflow.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/dexaflow-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 dexaflow-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; dexaflow validate, dexaflow compile and dexaflow 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, dexaflow compile --build writes the FROM itself, and it chooses between two tag shapes based on the CLI you are running:

• a released dexaflow pins dexaflow-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 dexaflow-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: dexaflow 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 dexaflow setup, to turn the check back on. Your dexaflow.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.
• dexaflow 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 dexaflow 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 dexaflow 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 Dexaflow 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 dexaflow 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

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

DEXAFLOW_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 dexaflow.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 (DEXAFLOW_*)

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 DEXAFLOW_* variable maps to a config key by upper-casing it and replacing . (and -) with _: e.g. auth.oidc.client_id → DEXAFLOW_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["DEXAFLOW_* env vars"]
  E --> F["CLI flags"]

The Edition column reads both (Lite and Pro), Pro (Pro / Kubernetes topologies only), or dev-only. dexaflow 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 DEXAFLOW_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 DEXAFLOW_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 DEXAFLOW_* 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 DEXAFLOW_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 DEXAFLOW_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 DEXAFLOW_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/dexaflow/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 DEXAFLOW_SECRETS_*, which an author’s task env can never set. Empty backend keeps the Dexaflow 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.*)

Branding the UI

The bundled UI reads its look from theme in /ui/config, so a theme changes colors, fonts and the navigation icon without touching the bundle. This example uses a blue brand palette and the Outfit and JetBrains Mono fonts, and loads the fonts from Google Fonts:

ui:
  theme:
    tokens:
      colors:
        brand:
          "50":  { value: "#eff6ff" }
          "100": { value: "#dbeafe" }
          "200": { value: "#bfdbfe" }
          "300": { value: "#93c5fd" }
          "400": { value: "#60a5fa" }
          "500": { value: "#3b82f6" }
          "600": { value: "#2563eb" }
          "700": { value: "#1d4ed8" }
          "800": { value: "#1e40af" }
          "900": { value: "#1e3a8a" }
          "950": { value: "#172554" }
      fonts:
        heading: { value: "Outfit, system-ui, sans-serif" }
        body:    { value: "Outfit, system-ui, sans-serif" }
        mono:    { value: "'JetBrains Mono', ui-monospace, monospace" }
  stylesheetUrls:
    - "https://fonts.googleapis.com/css2?family=Outfit:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap"

Set all eleven brand shades: the UI uses different shades for buttons, selections and the navigation highlight, on the light and the dark theme. The UI only exposes part of its styling through the theme; anything else is a globalCss rule, and holds only as long as the bundle keeps the selector it targets.

Trusted-issuer handoff

When Dexaflow is part of a larger platform that already signs its users in, the platform can open a Dexaflow UI session for them without Dexaflow storing a password and without the platform holding Dexaflow’s signing secret:

1. The platform’s issuer signs a short-lived JWT with its own key, carrying iss, aud, sub, iat, exp, a unique jti, the tenant claim and, optionally, email. It publishes the public key as a JWKS.
2. The browser posts that token to POST /api/v2/auth/session as the form field token, with the page to open as next (a same-origin path), from a page on one of allowed_origins. An auto-submitting form is the usual way, because a token in a URL ends up in logs and history.
3. Dexaflow verifies the token, finds the active user linked to (issuer:<name>, sub) in the token’s tenant, sets the same session cookie a password or SSO login sets, and redirects to next with 303.

The token never creates a user and never grants roles: the user must already exist and be linked to the issuer, and its roles are the ones Dexaflow holds. Refusals set no cookie and answer 400 (no token), 401 (token rejected), 403 (origin not allowed, or no active linked user in that tenant) or 500, with the reason in the server log and the audit trail (issuer.login.success / issuer.login.failure), never in the response.

Only pages on allowed_origins can post a handoff: browsers send Origin on every cross-site form post, and Dexaflow refuses any other, so a page elsewhere cannot sign a visitor in as someone else. A token must also have been issued no later than a minute from now and live no longer than max_lifetime_seconds (120 seconds unless set, at most 600). Each token opens one session: a second post of the same jti is refused until the token expires. That memory is per server process, so with several replicas a token could be accepted once by each; the short lifetime is what bounds that window. Mint each token right before posting it, and never put one in a URL.

Operator service API

An operator that serves several organizations from one Dexaflow (a hosting provider, an internal platform team) creates tenants and their users from its own automation instead of writing to the database. With auth.service_token set, two idempotent endpoints accept Authorization: Bearer <service token>; a user session never reaches them.

PUT /api/v2/service/tenants/{tenant} with an optional {"display_name": "Acme Corp"} creates the tenant (1-63 lowercase letters, digits or -) with the same built-in roles, role permissions and default pool as the default tenant, copied from it so every tenant’s ladder stays equal. It answers 201 when the tenant is new and 200 when it already existed; a second call fills in anything missing and changes nothing else.

PUT /api/v2/service/tenants/{tenant}/users/{subject} with {"email": "ana@acme.com", "roles": ["operator"]} makes sure a user with no password exists in the tenant, linked to the trusted issuer under that subject, with exactly those roles. It answers 201 for a new user and 200 for an existing one, whose roles it sets to the list given. It needs auth.trusted_issuer (409 otherwise), answers 404 for an unknown tenant, 422 for a role the tenant does not have, and 409 for a subject already linked in another tenant or an email already used by another user of the tenant, such as a password account. A tenant the trusted issuer may not sign in to (auth.trusted_issuer.allowed_tenants) is 403. The user signs in only through the trusted issuer’s handoff.

Every call that reaches the database is recorded in the audit trail, as service.tenant.ensure (with whether the tenant was created) and service.user.ensure (with the subject, email, roles and whether the user was created), each with outcome success or failure.

The service token is a root-level credential: whoever holds it can create tenants and grant any role, admin included, in every tenant the trusted issuer covers. Keep it in a Secret, give it only to the automation that provisions tenants, and rotate it by changing the Secret and restarting.

Trusted proxies and the client IP

By default Dexaflow 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 DEXAFLOW_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. DEXAFLOW_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.

Names from before the rename

Dexaflow was called Leoflow. Every name from that time keeps working, and none is scheduled for removal. When both the current and the old name are present, the current one wins.

A few internal names keep the old spelling on purpose, because renaming them would break running installations: the Postgres database names (leoflow, leoflow_dev), the Lite cluster (leoflow-dev), the leoflow.io/* labels and annotations on task pods, the LEOFLOW_* variables the control plane passes to task pods (agents built before the rename only read those), and the OpenTelemetry service name leoflow-server (traces stay continuous across the upgrade), and the internal Python modules leoflow_runtime and leoflow_parser (task images built before the rename run the former, and existing config.yaml files name the latter in parser_cmd).