Skip to main content

Tenant, Department, Project, And Resource Hierarchy designed

This is the clean product-facing hierarchy for AI Cloud today. It answers three questions directly:

  1. Where does authority live?
  2. Where does billing attribution live?
  3. Where do workloads, apps, storage, and credentials belong?

The Canonical Hierarchy​

Terminology Rule​

Product-facing termCurrent implementation termMeaning
OrganizationTenantThe customer root for billing, ownership, and governance
DepartmentDepartment / cost centerAn attribution and reporting layer inside an organization
ProjectProjectThe operational workspace where resources live
PrincipalUser, service account, groupThe actor that receives scoped access
ResourceAllocation, app instance, bucket, key, route, usageThe actual thing the project owns or operates

Use organization in portal and product documents. Expect some implementation docs and schema names to still say tenant while the migration finishes.

What Each Layer Owns​

LayerWhat it ownsWhat it does not mean
PlatformPlatform-admin authority, fleet, global policy, release posture, shared servicesCustomer content ownership
OrganizationBilling root, customer ownership root, tenant-scoped governance, top-level IAM boundaryA direct workspace for launches or app instances
DepartmentChargeback and reporting anchor, future budget/policy/delegation pointA required visible UX layer for small tenants
ProjectThe operational workspace for launches, apps, storage, service accounts, and membershipsA free-form nested folder tree
ResourceRuntime or data object owned by a projectAn independent top-level billing or IAM root

The Practical Rule​

Projects are where work happens.

Organizations and departments explain who owns the work and how it is governed or billed. Projects are where users actually launch workloads, attach storage, issue service accounts, and consume APIs.

Department Is Mandatory In The Model, Optional In The UX​

Department attribution is part of the durable data and billing model, but department administration is not a first-class user experience everywhere yet.

Current rule:

  • every organization has at least one default department;
  • every project belongs to exactly one department;
  • project creation may omit department_id, and the API assigns the organization's default department;
  • simple tenants do not need to see a department selector unless multiple departments or a department capability is enabled.

That gives the platform a stable reporting and billing shape without forcing small customers into enterprise-only controls.

Billing Attribution Shape​

The stable ownership and billing chain is:

organization -> department -> project

Products can meter below that:

organization -> department -> project -> service_account/api_key -> product/resource -> usage

Important distinction​

  • billing unit is not a hierarchy layer.
  • billing unit describes how usage is measured, such as gpu_hour, node_hour, or vcpu_hour.
  • organization, department, and project describe who owns or pays for the usage.

Roles And Scope​

Role bindings attach at scope, not at arbitrary nested content paths.

Platform scope​

  • platform_admin
  • platform_ops
  • platform_viewer
  • platform_iam_admin
  • platform_billing_admin

Organization scope​

  • tenant_owner
  • tenant_admin
  • tenant_ops
  • tenant_viewer
  • tenant_iam_admin
  • tenant_billing_admin

Project scope​

  • project_owner
  • project_admin
  • project_operator
  • project_member
  • project_viewer

Scope rule​

Management authority and content visibility are intentionally separable.

Example: an organization admin may manage projects and memberships without automatically seeing every project's runtime content.

Why This Hierarchy Is Stronger Than It Looks​

This is not only an org chart. It is the backbone for:

  • product navigation and context switching;
  • billing attribution across products;
  • service-account ownership;
  • future second-product reuse such as Token Factory;
  • operator and security readbacks that need to explain who owns a resource.

That is why the hierarchy belongs in both product and architecture thinking, not only in IAM implementation notes.

What A User Should Experience​

From a normal user or project admin point of view:

  • they sign in and land in an organization/project context;
  • they launch and manage resources inside a project;
  • they may never see a department selector if the organization has only the default department;
  • they should not need to understand implementation terms like tenant or internal Keycloak concepts.

What Is Explicitly Deferred​

These are not part of the basic hierarchy contract yet:

  • recursive org folders;
  • department admins as a separate shipped role family;
  • department hard budgets by default;
  • always-visible department pickers;
  • a resource-group layer below project;
  • using Keycloak as the product IAM authority.

Product Guidance​

When a new feature needs ownership, ask these questions in order:

  1. Is this a platform concern, organization concern, project concern, or resource concern?
  2. Does the actor need organization-scoped authority or only project-scoped authority?
  3. Is department only attribution, or is the feature trying to introduce new department capabilities?
  4. Is the feature incorrectly using billing-unit language when it really means ownership hierarchy?

If a feature cannot answer those questions, the hierarchy is not yet modeled clearly enough.

Canonical sources