1. Kestra 1.3 is here: production-grade controls release
Item 1 of 1

Kestra Enterprise and Advanced Configuration

OVERVIEW

Created by

Kestra Core Team

Managed by

Kestra Core Team

Use this page for configuration areas that are either Enterprise-specific or advanced platform concerns.

Enterprise platform settings

This page groups together settings that are important but not part of a normal OSS-style runtime setup. If the instance is not using EE features, you can ignore most of this page.

This area includes:

  • Enterprise license configuration
  • Enterprise Java security
  • UI sidebar customization
  • historical multi-tenancy and default tenant settings
  • custom links in the UI

EE license configuration:

kestra:
  ee:
    license:
      id: <LICENSE ID>
      fingerprint: <LICENSE FINGERPRINT>
      key: |
        <LICENSE KEY>

Kestra validates the license on startup. The fingerprint is also required for versioned plugins.

EE Java security lets you restrict filesystem access and thread creation:

kestra:
  ee:
    java-security:
      enabled: true
      forbidden-paths:
        - /etc/
      authorized-class-prefix:
        - io.kestra.plugin.core
        - io.kestra.plugin.gcp

Use EE Java security carefully. It is a platform hardening feature, so the goal is to narrow what plugin code is allowed to touch, not to tune routine runtime behavior.

UI customization examples:

kestra:
  ee:
    right-sidebar:
      custom-links:
        internal-docs:
          title: "Internal Docs"
          url: "https://kestra.io/docs/"
kestra:
  ee:
    left-sidebar:
      disabled-menus:
        - "Blueprints/Flow Blueprints"

The old multi-tenancy and default-tenant configuration was removed in 0.23.0; keep it only in mind for migration work.

Elasticsearch, Kafka, and indexing

This section is really about one architectural choice: running Kestra on the Kafka plus Elasticsearch stack instead of the simpler JDBC-backed setup. If you are on PostgreSQL or MySQL only, much of this page will not apply.

These settings cover the advanced repository and queue stack used in Enterprise deployments:

  • Elasticsearch repository settings
  • Kafka client and topic settings
  • Kafka message protection
  • indexer behavior

Use this section when you are running the Kafka plus Elasticsearch architecture instead of a JDBC-only deployment.

Minimal Elasticsearch repository configuration:

kestra:
  elasticsearch:
    client:
      http-hosts: "http://localhost:9200"
  repository:
    type: elasticsearch

Start by proving the minimal connection first. After that, add auth, SSL handling, index prefixes, or rotation only when the deployment model requires them.

With authentication:

kestra:
  elasticsearch:
    client:
      http-hosts:
        - "http://node-1:9200"
        - "http://node-2:9200"
      basic-auth:
        username: "<your-user>"
        password: "<your-password>"
  repository:
    type: elasticsearch

Related advanced Elasticsearch settings include:

  • trust-all-ssl for self-signed development clusters
  • custom index prefixes
  • daily, weekly, monthly, or yearly index rotation

Minimal Kafka queue configuration:

kestra:
  kafka:
    client:
      properties:
        bootstrap.servers: "localhost:9092"
  queue:
    type: kafka

Kafka tuning is usually about cluster shape rather than syntax. Partition count limits how much component-level concurrency you can achieve, while replication settings should match your broker topology and HA expectations.

This page also covers:

  • SSL-secured Kafka clients
  • default topic partition and replication settings
  • consumer, producer, and stream defaults
  • custom topic names and topic properties
  • consumer and topic prefixes for shared clusters
  • Kafka Streams local state directory
  • message protection for oversized Kafka messages

Representative advanced Kafka settings:

kestra:
  kafka:
    client:
      properties:
        bootstrap.servers: "localhost:9092"
        security.protocol: SSL
    defaults:
      topic:
        partitions: 3
        replication-factor: 3
    topics:
      executions:
        properties:
          retention.ms: 604800000

Use client properties for transport and auth, defaults for cluster-wide topic behavior, and topics.*.properties only when one topic needs behavior that differs from the rest.

Shared-cluster deployments often also need prefixes or dedicated topic names to avoid collisions with other tenants or environments.

To reject oversized Kafka messages early:

kestra:
  kafka:
    message-protection:
      enabled: true
      limit: 1048576

Indexer settings control batch indexing from Kafka into Elasticsearch:

kestra:
  indexer:
    batch-size: 500
    batch-duration: PT1S

If indexing falls behind, tune indexer batch settings before changing flow definitions. Those settings control how aggressively Kafka-backed events are flushed into Elasticsearch.

AI and isolated environments

These are the most optional settings on the page. They matter only if you are enabling Copilot integrations or operating Kestra in restricted network environments.

This page also includes:

  • AI Copilot provider configuration
  • air-gapped instance settings

AI Copilot

Enterprise Edition supports multiple providers in one configuration, which is useful when teams need both a default internal model and a fallback external model:

kestra:
  ai:
    providers:
      - id: gemini
        display-name: Gemini - Private
        type: gemini
        configuration:
          model-name: gemini-2.5-flash
          api-key: YOUR_GEMINI_API_KEY
      - id: gpt
        display-name: OpenAI
        type: openai
        isDefault: true
        configuration:
          model-name: gpt-4
          api-key: YOUR_OPENAI_API_KEY

Optional provider settings include temperature, top-p, top-k, max-output-tokens, log-requests, log-responses, and base-url.

Air-gapped mode

Use air-gapped mode when the UI and blueprint experience must avoid external dependencies:

kestra:
  ee:
    airgapped: true

When enabled, the UI hides or adapts features that normally depend on external services, such as hosted fonts, external blueprint sources, or embedded internet content.

Execution data in internal storage

If EE outputs and inputs must be isolated per tenant or namespace, store execution data in internal storage:

kestra:
  ee:
    execution-data:
      internal-storage:
        enabled: true

To enforce that behavior everywhere:

kestra:
  ee:
    execution-data:
      internal-storage:
        force-globally: true

Mail service

Invitation and password-reset emails rely on the EE mail service:

kestra:
  ee:
    mail-service:
      host: host.smtp.io
      port: 587
      username: user
      password: password
      from: configurable@mail.com
      from-name: Kestra
      auth: true
      starttls-enable: true

Use this page when an instance needs non-default enterprise infrastructure, custom UI platform behavior, or advanced deployment constraints rather than routine runtime configuration.

When to use this page

Was this page helpful?