​Business ​Units ​Separation

Kestra Enterprise provides two primary levels of isolation within an instance: tenants and namespaces.

Overview

Choosing between tenants and namespaces for separating business units depends on the required level of data isolation, access control, and visibility into cross-workflow dependencies.

When to use multiple tenants

A tenant is an isolated environment within a Kestra instance. Tenants have their own fully isolated resources, including flows, RBAC policies, secrets, variables, plugin defaults, and more. Users exist globally across the instance but can have different roles and permissions per tenant.

You can configure dedicated resources for each tenant:

• Dedicated internal storage (e.g., a separate S3 bucket per tenant)
• Dedicated secrets manager backend (e.g., a separate Vault or AWS Secrets Manager per tenant)
• Dedicated worker groups (e.g., a pool of workers used exclusively by a specific tenant)
• Flows, executions, and logs are isolated between tenants by default

Use cases for tenants

• Customer separation: For multi-tenant SaaS setups requiring strict isolation between customers, assign each customer its own tenant rather than a dedicated namespace.
• Fully isolated teams: When even administrators should not have visibility into other teams' workflows, tenants provide the highest level of isolation.

Note: Since tenants are fully isolated, there is no cross-tenant visibility. If you need to share flows (e.g., team A runs a subflow from team B) or manage interdependent workflows, namespaces are a better option.

When to use multiple namespaces

A namespace is a logical grouping within a tenant that organizes teams and projects while providing fine-grained access control. Unlike tenants, namespaces allow cross-visibility of flows and dependencies.

You can configure dedicated resources for each namespace:

• Dedicated internal storage (e.g., a separate S3 bucket per namespace)
• Dedicated secrets manager backend (e.g., a separate Vault or AWS Secrets Manager per namespace)
• Dedicated worker groups (e.g., a pool of workers used exclusively by a specific namespace)
• Flows, executions, and logs are shared across namespaces; isolation is managed through RBAC permissions

Use cases for namespaces

• Team-based organization: Separate flows and resources by team within the same tenant, maintaining visibility for users with appropriate permissions.
• Project-based organization: Create separate namespaces for projects that need limited isolation while retaining workflow visibility.
• Dependency management: Namespaces support cross-team dependencies (e.g., subflows or triggers), simplifying dependency tracking.
• RBAC control: Namespaces allow granular role-based access. A user might have READ access in one namespace and full CRUD permissions in another.

Summary of when to use tenants vs. namespaces

Recommendations

• Use tenants when strict isolation is required, and no cross-team dependencies exist.
• Use namespaces to organize business units or teams that require centralized governance and cross-team visibility.
• Configure dedicated secrets and internal storage backends at the lowest necessary level (tenant or namespace) to follow the principle of least privilege and simplify management (e.g., applying S3 lifecycle policies per team).
• Prefer namespace isolation over tenant isolation when workflows depend on each other to maintain visibility across dependencies.

For a hands-on guide on how to use RBAC to separate business units at the namespace level, see the video below: