​Tenants

How to enable multi-tenancy in your Kestra instance.

What is Multi-Tenancy

A tenant represents an isolated environment within a single Kestra instance.

Each tenant functions as a separate entity with its own resources, such as flows, triggers, or executions. Multi-tenancy enables different teams, projects, or customers to operate independently within the same Kestra instance, ensuring data privacy, security along with separation of resources between business units, teams, or customers. For example, you can have a dev tenant for development, a staging tenant for testing, and a prod tenant for production.

When multi-tenancy is enabled, all resources (such as flows, triggers, executions, RBAC, and more) are isolated by the tenant. This means that you can have a flow with the same identifier and the same namespace in multiple tenants at the same time.

Data stored inside the internal storage are also isolated by tenants.

Multi-tenancy functionality is not visible to end-users from the UI except for the tenant selection dropdown menu. That dropdown menu lists all tenants a user has access to, allowing them to switch between tenants easily. Each UI page also includes the tenant ID in the URL e.g. https://demo.kestra.io/ui/yourTenantId/executions/namespace/flow/executionId.

The API URLs also include the tenant identifier. For example, the URL of the API operation to list flows of the marketing namespace is /api/v1/flows/marketing when multi-tenancy is not enabled. Once you enable multi-tenancy and create a tenant prod, this URL becomes /api/v1/prod/flows/marketing. You can check the API Guide for more information.

Tenants must be created upfront, and a user needs to be granted access to use a specific tenant.

Key Benefits of Multi-Tenancy

1. Environment Management: you can manage multiple environments (development, staging, production) within a single Kestra instance.
2. Data Isolation: each tenant's data, configuration and code are isolated and inaccessible to other tenants.
3. Resource Isolation: each tenant's resources are isolated from other tenants — incl. flows, triggers, executions, logs, audit logs, secrets, etc.
4. Simple Configuration: you can easily create new tenants instantly giving you a fresh, fully-isolated workspace accessible from your existing Kestra instance.
5. Intuitive UI Navigation: the UI provides a dropdown as well as tenant identifiers included in the URL to make switching between tenants seamless.

How to Enable Multi-Tenancy

By default, multi-tenancy is disabled. To enable it, add the following configuration:

kestra:
  ee:
    tenants:
      enabled: true

Default Tenant

When enabling multi-tenancy, you can also decide whether to enable the default tenant or not. Default tenant is a tenant without an identifier (aka the null tenant). It exists for backward compatibility when multi-tenancy is enabled in an existing Kestra instance. If you disable the default tenant in a Kestra instance that already has flows and executions, you will no longer be able to access them.

When multi-tenancy is enabled in a new Kestra instance, it's recommended to disable the default tenant so that all tenants will have an identifier. This way, all tenants are explicitly defined and can be referenced by their ID.

By default, multi-tenancy is disabled, and the default tenant is set to true. Once you enable multi-tenancy, you can set the default tenant to false to disable it so that your Kestra instance includes only the tenants you explicitly create. Here is how to enable multi-tenancy and disable the default tenant (best practice):

kestra:
  ee:
    tenants:
      enabled: true
      default-tenant: false

Once multi-tenancy is enabled, you can create one or more tenants e.g. from the UI, CLI, Terraform or API. Then, you can assign user roles and permissions within each tenant.

Creating and Managing Tenants

Tenants in Kestra can be managed in various ways: from the UI, CLI, API, or Terraform.

Creating a Tenant from the UI

Tenants can be created and managed directly through Kestra's user interface. Go to Administration -> Tenants. Then, click on the Create button:

Fill in the form and click Save:

The user who created the tenant will get an Admin Role for that tenant. You may need to refresh the UI to see updated Roles.

Creating a Tenant from the CLI

Kestra provides CLI commands for tenant creation. The following command will create a tenant with the identifier stage and the name Staging:

kestra-ee tenants create --tenant stage --name "Staging"

Running kestra tenants create --help will show you all available properties:

$ kestra tenants create --help
Usage: kestra-ee tenants create [-hVv] [--internal-log]
                                [--admin-username=<adminUser>] [-c=<config>]
                                [-l=<logLevel>] [--name=<tenantName>]
                                [-p=<pluginsPath>] [--tenant=<tenantId>]
create a tenant and assign admin roles to an existing admin user
      --admin-username=<adminUser>
                            Username of an existing admin user that will be
                              admin of this tenant
  -c, --config=<config>     Path to a configuration file, default: /Users/anna/.
                              kestra/config.yml)
  -h, --help                Show this help message and exit.
      --internal-log        Change also log level for internal log, default:
                              false)
  -l, --log-level=<logLevel>
                            Change log level (values: TRACE, DEBUG, INFO, WARN,
                              ERROR; default: INFO)
      --name=<tenantName>   tenant description
  -p, --plugins=<pluginsPath>
                            Path to plugins directory , default:
                              /Users/anna/dev/plugins)
      --tenant=<tenantId>   tenant identifier
  -v, --verbose             Change log level. Multiple -v options increase the
                              verbosity.
  -V, --version             Print version information and exit.

Creating a Tenant from the API

Tenants can be managed programmatically via Kestra's API. Here is an example of an API call for creating a tenant:

curl -X POST "https://demo.kestra.io/api/v1/tenants" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -d "{ \"id\": \"stage\", \"name\": \"staging\", \"deleted\": false}"

Creating a Tenant from Terraform

Tenants can be managed via Infrastructure as Code using Kestra's Terraform provider. Here is an example of a Terraform configuration for creating a tenant:

resource "kestra_tenant" "stage" {
  tenant_id = "stage"
  name      = "staging"
}

Admin Role Assignment

Regardless of which of the above methods you use to create a tenant, the User who creates the tenant will automatically get the Admin Role assigned. That role grants admin rights to that user on that tenant.

Note that there is an exception to this rule if tenant is created by a Super Admin. In that case, the Super Admin will have to explicitly assign the Admin Role for that tenant to themselves or any other User, Service Account or Group.