Capsule — Multi-Tenant Kubernetes Made Easy

Introduction

Capsule provides native multi-tenancy for Kubernetes without requiring separate clusters for each team. It introduces a Tenant custom resource that groups multiple namespaces under unified governance, enforcing resource quotas, network isolation, and access control while letting tenant owners self-manage their namespaces within defined boundaries.

What Capsule Does

• Groups namespaces into Tenants with shared governance policies
• Enforces resource quotas, limit ranges, and storage limits at the Tenant level
• Applies network policies automatically to isolate Tenant traffic
• Delegates namespace creation to Tenant owners via RBAC
• Restricts access to cluster-scoped resources like Ingress classes and storage classes

Architecture Overview

Capsule runs as a controller and a set of admission webhooks. The controller watches Tenant CRDs and reconciles namespace-level resources (ResourceQuotas, LimitRanges, NetworkPolicies) across all namespaces belonging to each Tenant. The admission webhooks intercept API requests to ensure Tenant owners can only operate within their assigned boundaries, enforcing namespace quotas, allowed registries, and ingress hostname restrictions without modifying the Kubernetes API server.

Self-Hosting & Configuration

• Deploy via Helm with default RBAC and webhook configuration
• Define Tenant resources with owner bindings and resource quotas
• Configure allowed ingress classes, storage classes, and container registries per Tenant
• Set namespace quotas to limit how many namespaces a Tenant can create
• Enable Tenant-level network policies for automatic namespace isolation

Key Features

• Tenant-level quotas aggregate resource usage across multiple namespaces
• Self-service namespace creation within policy boundaries for team autonomy
• Ingress hostname and TLS restrictions prevent cross-Tenant conflicts
• Container registry whitelisting enforces image provenance per Tenant
• No changes required to the Kubernetes API server or control plane components

Comparison with Similar Tools

• Hierarchical Namespace Controller (HNC) — namespace hierarchy without quota aggregation or admission control
• vCluster — virtual clusters provide stronger isolation but higher resource overhead
• Loft — commercial multi-tenancy platform, Capsule is open source
• Kiosk — archived multi-tenancy project, Capsule is actively maintained

FAQ

Q: Does Capsule require a custom Kubernetes API server? A: No. Capsule uses standard CRDs and admission webhooks. It works on any conformant Kubernetes cluster without modifications.

Q: Can a Tenant span multiple clusters? A: Capsule operates within a single cluster. For multi-cluster tenancy, combine Capsule with a multi-cluster management tool.

Q: How does Capsule differ from just using namespaces with RBAC? A: Capsule adds Tenant-level governance that plain namespaces lack: aggregated quotas across namespaces, automatic network policy injection, and self-service namespace creation within enforced limits.

Q: Can I migrate existing namespaces into a Capsule Tenant? A: Yes. Assign existing namespaces to a Tenant by adding the capsule.clastix.io/tenant label. Capsule will apply Tenant policies to those namespaces.

Sources

• https://github.com/projectcapsule/capsule
• https://capsule.clastix.io/docs/