Skip to content
Fundament Docs

ADR-0011: Organizational hierarchy

Proposed
Status

proposed

Date

2026-03-10

Group

platform

Depends-on

ADR-0008

Context

With dedicated physical clusters per tenant (ADR-0008), we need a resource hierarchy that maps government organizational structures to platform resources. The hierarchy determines how access control, billing, and resource quotas are scoped.

Options

Option 1: Flat (organization → clusters)

  • Pros: simplest model; easy to reason about

  • Cons: no sub-grouping within a cluster; large ministries cannot delegate environments or teams; all workloads share one authorization scope

Option 2: Organization → cluster → project → namespace

  • Pros: organization is the tenant boundary; clusters are infrastructure owned by the organization; projects group workloads within a cluster (e.g. by environment or team); namespaces are the deployment unit within a project; access control scopes at both organization level (platform access) and project level (workload access); clean separation between infrastructure concerns (clusters, node pools) and workload concerns (projects, namespaces)

  • Cons: slightly more complex than flat

Option 3: Organization → project → cluster (Gardener/GCP model)

  • Pros: matches Gardener’s native project concept; proven pattern in GCP

  • Cons: project-as-grouping-of-clusters does not match how teams actually work — teams work within a cluster, not across clusters; conflates infrastructure grouping with workload grouping

Option 4: Deeply nested (organization → folder → folder → …​ → project → clusters)

  • Pros: maximum flexibility for complex org structures

  • Cons: deep nesting creates confusion about where policies apply; inheritance rules become complex; over-engineering for current needs

Decision

Organization → cluster → project → namespace. An organization represents a government entity (ministry, agency) and is the tenant boundary. Clusters are managed Kubernetes clusters provisioned via Gardener, owned by the organization. Projects are logical groupings within a cluster (e.g. staging, production, or per-team). Namespaces are the unit of deployment within a project. Access control is scoped at two levels: organization membership controls platform access, project membership controls workload access.

Consequences

  • Every namespace belongs to exactly one project, every project to one cluster, every cluster to one organization

  • Authorization model must support scoping at both organization and project level

  • Tenant onboarding creates an organization; infrastructure admins provision clusters; teams create projects within clusters

  • Billing and quota aggregation happens at organization level

  • Node pools are an infrastructure concern managed at cluster level, not visible to project-level users