​Business ​Units ​Separation

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

Overview

The choice between tenants and namespaces for separation of Business Units depends on the 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 incl. flows, RBAC policies, secrets, variables, plugin defaults, and more. Users are global to the instance but can have different roles and permissions per tenant.

You can configure dedicated resources per 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. special pool of workers intended to be used by a given tenant)
• flows, executions, and logs are by default isolated between tenants.

Use cases for tenants

• Customer separation: If you operate a multi-tenant SaaS on top of Kestra and you need strict isolation between customers, each customer should have its own tenant, not just a dedicated namespace.
• Fully isolated teams: If even Admin users 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 flow from team B as a subflow) or dependencies between teams (e.g. flow B should run only after flow A managed by a different team), namespaces are a better option.

When to use multiple namespaces

A namespace is a logical grouping within a tenant that allows for structured organization of teams and projects, and fine-grained access control, while still allowing for cross-visibility of flows and dependencies across namespaces.

You can configure dedicated resources per 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. special pool of workers intended to be used by a given namespace)
• flows, executions, and logs are by default shared across namespaces and the only isolation is at the RBAC level i.e. you can restrict specific users or groups of users to allow access to only specific namespaces.

Use cases for namespaces

• Team-based organization: Use namespaces to separate flows and resources for different teams while keeping them within the same tenant and allowing cross-team visibility for users with the right permissions.
• Project-based organization: If multiple projects within a team need some level of separation but still require visibility across workflows.
• Dependency management: Namespaces allow visibility into dependencies (e.g., subflows and triggers), which makes it easier to track cross-team interactions.
• RBAC control: Namespaces allow role-based permissions at a granular level. A user may have only READ access within one namespace and full CRUD (CREATE, READ, UPDATE, DELETE) access within another. Or some users may have access to only one namespace intended for their team and not others.

Summary of when to use tenants vs. namespaces

Recommendations

• Use tenants when strict isolation is required and you don't have cross-team workflow dependencies.
• Use namespaces for organizing business units and teams with centralized governance and visibility into cross-team dependencies.
• Configure dedicated secrets and internal storage backend at the lowest necessary level (tenant or namespace level) to follow the principle of least privilege and allow for painless management (e.g. lifecycle policy on an S3 bucket for a given team).
• If workflows depend on each other, prefer namespace isolation over tenant isolation to maintain visibility into workflow dependencies.

For a hands-on guide on how you can leverage RBAC to separate business units on a namespace-level, check the video below: