> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/operate/v1/dataos-operator/design-tenants.md).

# Design Tenants

A **Tenant** is the main isolation boundary in DataOS. It has its own namespace, credentials, access controls, and Compute.

Plan the Tenant structure before creating Tenants. The structure determines how you organize ownership, access, cost, and governance, and changing it later can affect teams, permissions, workloads, and operating processes.

{% hint style="info" %}
This page assumes you have already decided that a Tenant, rather than a separate Instance, is the right boundary. If not, first see [choosing between an Instance and a Tenant](/operate/v1/dataos-operator/choosing-between-instance-and-tenant.md).
{% endhint %}

## The decision in one sentence

Create a Tenant for the smallest team, business area, environment, or domain that needs its own isolation, owner, and lifecycle.

Do not make Tenants so broad that ownership becomes unclear. Do not make them so narrow that you have more boundaries to manage than needed.

## Common patterns

| Pattern              | Create a Tenant for...                                                | Best when                                                                  |
| -------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| **By environment**   | Each stage of the lifecycle, such as `dev`, `stg`, and `prod`         | A team needs clear separation between development, testing, and production |
| **By business unit** | Each business unit, such as `marketing`, `finance`, or `supply-chain` | Ownership, budget, and governance follow the organization structure        |
| **By domain**        | Each data domain, such as `orders`, `customers`, or `inventory`       | Domain teams own their data products from development through operation    |
| **Hybrid**           | A combination, such as `marketing-dev` and `marketing-prod`           | You need both business separation and environment separation               |

{% hint style="info" %}
Many organizations start with environment-based Tenants for their first team and evolve toward business-unit, domain, or hybrid patterns as adoption grows.
{% endhint %}

## What changes with the choice

| Area                        | More Tenants                                                     | Fewer Tenants                                                 |
| --------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------- |
| Isolation                   | Stronger separation between teams, environments, or domains      | More teams and workloads share the same boundary              |
| Cost and infrastructure use | More setup and operating overhead                                | Better reuse of shared infrastructure                         |
| Governance                  | Clearer ownership, but more boundaries to manage                 | Fewer boundaries, but ownership can become less clear         |
| Operations                  | More Tenants to create, configure, and monitor                   | Easier to manage, but each Tenant carries more responsibility |
| Promotion                   | Clearer development-to-production path when split by environment | Promotion happens within the same Tenant                      |
| Sharing                     | Sharing across Tenants needs explicit access                     | Sharing is easier within the same Tenant                      |

## How to choose

1. **Start with ownership.** Identify who is responsible for the data, workloads, and products day to day. That ownership boundary is often a good Tenant boundary.
2. **Separate environments when production stability matters.** If the same team needs to experiment without affecting production, use separate Tenants for `dev`, `stg`, and `prod`, or use a hybrid pattern.
3. **Separate areas that must not affect each other.** If a configuration change, failed workload, or access mistake in one area should not affect another, use separate Tenants.
4. **Consider the operating effort.** Every Tenant must be created, configured, governed, monitored, and reviewed. Create only the Tenants your team is ready to operate.
5. **Plan shared resources early.** Decide which data sources, Computes, and reference datasets will be shared, and which must remain isolated. Cross-Tenant access must be granted explicitly.

## Operating practices

A clear Tenant structure is only useful if it is operated consistently.

* **Use stable names.** Choose a naming pattern such as `<business-unit>-<environment>` or `<domain>`. Avoid renaming Tenants after teams start using them, because workflows and references may depend on the name.
* **Keep role design consistent.** Use the same role and grant conventions across Tenants so access remains predictable. For role definitions and the capability matrix, see [Roles & Permissions](/operate/v1/access-model.md).
* **Review Tenants regularly.** Confirm that each Tenant still has an owner, a clear purpose, and active workloads. Retire Tenants that are no longer needed.

After you have planned the Tenant structure, create the Tenant. See [Create Tenant](/operate/v1/dataos-operator/design-tenants/create-tenants.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://v2.dataos.info/operate/v1/dataos-operator/design-tenants.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.