Where Kestra Config Lives and How Overrides Work
For the complete documentation index, see llms.txt. For a full content snapshot, see llms-full.txt. Append .md to any kestra.io/docs/* URL for plain Markdown.

Use this page first if you are not sure where Kestra configuration is actually edited in your environment.

Configuration sources

Kestra reads configuration from YAML. In practice, teams usually provide it in one of these ways:

  • a YAML file mounted or bundled with the Kestra process
  • the KESTRA_CONFIGURATION environment variable
  • inline YAML inside Docker Compose
  • Helm values or Kubernetes manifests

Environment variables override file-based configuration, so many teams keep a shared YAML base config in version control and inject deployment-specific values at runtime.

Minimal boot configuration

Most deployments need to decide at least these three things:

  1. repository type
  2. queue type
  3. internal storage type

Example:

datasources:
  postgres:
    url: jdbc:postgresql://postgres:5432/kestra
    driver-class-name: org.postgresql.Driver
    username: kestra
    password: k3str4
kestra:
  repository:
    type: postgres
  queue:
    type: postgres
  storage:
    type: local
  url: "http://localhost:8080/"

These three choices drive the rest of the deployment:

  • kestra.repository.type controls the persistence backend for core metadata.
  • kestra.queue.type must be compatible with the repository type.
  • kestra.storage.type controls where Kestra stores internal files and task artifacts.

Environment variable conversion

Convert YAML keys to environment variables like this:

  • replace dots (.) with underscores
  • replace hyphens (-) with underscores
  • convert camelCase boundaries to underscores
  • uppercase everything
  • prefix Kestra-specific keys with KESTRA_

Examples:

Configuration valueResulting properties
MYAPP_MYSTUFFmyapp.mystuff, myapp-mystuff
MY_APP_MY_STUFFmy.app.my.stuff, my.app.my-stuff, my-app.my.stuff, my-app.my-stuff, and similar variants

File-based configuration:

datasources:
  postgres:
    username: kestra

becomes:

DATASOURCES_POSTGRES_USERNAME=kestra

And:

kestra:
  storage:
    s3:
      accessKey: myKey

or:

kestra:
  storage:
    s3:
      access-key: myKey

becomes:

KESTRA_STORAGE_S3_ACCESS_KEY=myKey

Common patterns:

MICRONAUT_SERVER_PORT=8080
DATASOURCES_POSTGRES_USERNAME=kestra
KESTRA_STORAGE_TYPE=s3
KESTRA_URL=https://kestra.example.com

SDK default authentication

SDK-based plugins resolve authentication in this order:

  1. Namespace-level default service account
  2. Tenant-level default service account
  3. Global SDK defaults (kestra.tasks.sdk.authentication)

In OSS, when kestra.server.basic-auth is configured, Kestra automatically derives the global SDK credentials from it — no additional configuration is needed. SDK-based tasks using DEFAULT or AUTO authentication work without further setup.

If you need to use different credentials from those in kestra.server.basic-auth, or to authenticate with an API token, override the global default explicitly:

kestra:
  tasks:
    sdk:
      authentication:
        username: my-user        # overrides basic-auth username
        password: my-password    # overrides basic-auth password
        # api-token: ${KESTRA_API_TOKEN}  # use an API token instead

If no credential is available at any level, SDK-based tasks using DEFAULT or AUTO authentication fail. This applies to OSS instances without basic auth configured, and to EE/Cloud instances without a namespace or tenant-level service account.

What belongs on the other configuration pages

  • Use Runtime and Storage for datasources, queue, repository, internal storage, JVM, environment metadata, and global variables.
  • Use Observability and Networking for logs, metrics, Micronaut, endpoints, access logs, SSL, and CORS.
  • Use Plugins and Execution for plugin installation, plugin defaults, retries, local flow sync, templates, and execution behavior.
  • Use Security and Secrets for encryption, secret backends, auth hardening, and liveness settings.
  • Use Enterprise and Advanced for EE license, Kafka, Elasticsearch, indexer, AI Copilot, and air-gapped deployments.

Next steps

Was this page helpful?