Explanation

Capsule Multi-Tenancy Model

Understanding how Capsule implements Kubernetes multi-tenancy.

Overview

Capsule provides a lightweight multi-tenancy solution that aggregates multiple Kubernetes namespaces into logical “Tenants”. This allows teams to self-manage their namespaces while maintaining strict isolation from other tenants.

The Tenant Abstraction

A Tenant is a cluster-scoped custom resource that:

  • Groups multiple namespaces under a single policy boundary

  • Defines who can create and manage namespaces (owners)

  • Enforces resource quotas across all tenant namespaces

  • Applies network policies and other restrictions

Tenant vs Namespace

Aspect

Namespace

Tenant

Scope

Single unit

Collection of namespaces

RBAC

Per-namespace

Inherited across all tenant namespaces

Quotas

Per-namespace

Aggregated at tenant level

Creation

Requires cluster-admin

Self-service for tenant owners

Namespace Assignment

Capsule uses the forceTenantPrefix setting to automatically assign namespaces to tenants:

  1. Tenant owner creates namespace: kubectl create namespace bd-prod

  2. Capsule intercepts the request

  3. Matches prefix bd- to tenant bd

  4. Assigns namespace to tenant

  5. Applies tenant policies (RBAC, quotas, network policies)

Without prefix matching, namespace creation would require explicit tenant annotation.

Owner Types

Tenants can have different owner types:

ServiceAccount (Used in kup6s)

owners:
  - name: system:serviceaccount:capsule-system:bd-sa
    kind: ServiceAccount

Best for programmatic access and token-based authentication.

User

owners:
  - name: alice@example.com
    kind: User

Requires external identity provider (OIDC, LDAP).

Group

owners:
  - name: developers
    kind: Group

Useful for team-based access via group membership.

Comparison with Alternatives

vs Hierarchical Namespace Controller (HNC)

  • HNC: Hierarchical structure (parent/child namespaces)

  • Capsule: Flat tenant structure with namespace aggregation

  • HNC: Archived project (no updates since April 2025)

  • Capsule: Actively maintained

vs vCluster

  • vCluster: Full virtual cluster isolation

  • Capsule: Lightweight namespace-based isolation

  • vCluster: Higher resource overhead

  • Capsule: Minimal overhead, single operator