# Capsule — Multi-Tenant Kubernetes Made Easy

> Capsule is a Kubernetes operator that implements multi-tenancy by grouping namespaces into isolated Tenants with shared resource quotas, network policies, and RBAC rules, enabling secure self-service for multiple teams on a single cluster.

## Install

Save in your project root:

# Capsule — Multi-Tenant Kubernetes Made Easy

## Quick Use
```bash
# Install Capsule via Helm
helm repo add projectcapsule https://projectcapsule.github.io/charts
helm install capsule projectcapsule/capsule --namespace capsule-system --create-namespace
# Create a Tenant
cat <<EOF | kubectl apply -f -
apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: team-alpha
spec:
  owners:
    - name: alice
      kind: User
  namespaceOptions:
    quota: 5
  resourceQuotas:
    scope: Tenant
    items:
      - hard:
          cpu: "8"
          memory: 16Gi
EOF
```

## 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/

---
Source: https://tokrepo.com/en/workflows/asset-cb67681b
Author: AI Open Source