# Capsule (Kubernetes)

Capsule is a multi-tenant Kubernetes operator that enables efficient and secure workload isolation by grouping namespaces into lightweight virtual clusters called Tenants.

## History

Capsule was created by Clastix to address the need for true multi-tenancy in Kubernetes without relying on heavyweight virtual clusters or multiple control planes. First introduced as an open-source project around 2020, Capsule has gained adoption among organizations needing fine-grained control, policy enforcement, and delegation in multi-team Kubernetes environments.

## Value Proposition

Capsule provides a scalable and cost-effective way to enable multi-tenancy in Kubernetes by:

- Allowing each team or project to operate in isolated namespace groups (Tenants).
- Delegating administrative control to tenant owners without granting full cluster-admin rights.
- Enforcing policies (like resource quotas, network policies, and RBAC) per tenant.

This makes it ideal for organizations that want to avoid the complexity of managing separate clusters while maintaining strong security and operational boundaries.

## Challenges

While Capsule simplifies multi-tenancy, it introduces some challenges:

## Key Features

- **Tenant abstraction**: Group multiple namespaces under a single “Tenant” object.
- **Policy enforcement**: Apply custom policies for resource quotas, network policies, image registries, and node selectors per tenant.
- **Delegation**: Assign tenant owners who can manage their namespaces, pods, and deployments independently.
- **Multi-tenancy isolation**: Ensures workloads, configurations, and access controls are scoped to their respective tenants.
- **Namespace auto-provisioning**: Automatically creates namespaces assigned to a tenant.
- **Integration support**: Works with tools like Gatekeeper, Kyverno, and Open Policy Agent for governance.

## Types of Tenancy Models Capsule Supports

- **Soft multi-tenancy**: Teams share the same control plane with namespace-level isolation.
- **Hard multi-tenancy**: Teams are fully isolated using Capsule’s Tenant boundary mechanisms while keeping operational simplicity.

### How to Use Capsule

#### Step 1: Install Capsule

```yaml
kubectl apply -f https://github.com/clastix/capsule/releases/latest/download/install.yaml
```

Verify the Capsule components:

```yaml
kubectl get pods -n capsule-system
```

#### Step 2: Create a Tenant

Create a YAML file like `tenant-dev.yaml`:

```yaml
apiVersion: capsule.clastix.io/v1alpha1
kind: Tenant
metadata:
  name: dev-team
spec:
  owners:
    - kind: User
      name: dev-user
```

Apply it:

```yaml
kubectl apply -f tenant-dev.yaml
```

#### Step 3: Create Namespaces under the Tenant

Use Capsule’s admission controller to assign namespaces:

```none
kubectl create namespace dev-ns
kubectl label namespace dev-ns capsule.clastix.io/tenant=dev-team
```

Only users assigned to the `dev-team` tenant will be able to access this namespace (depending on RBAC).

#### Step 4: Enforce Quotas and Policies

Add resource quotas per tenant:

```none
apiVersion: v1
kind: ResourceQuota
metadata:
  name: tenant-quota
  namespace: dev-ns
spec:
  hard:
    pods: "20"
    requests.cpu: "4"
    requests.memory: 16Gi
```

Capsule also supports enforcing:

- Ingress domains
- Container registries
- Network policy isolation

## Cloud Providers Supporting Capsule

Capsule is Kubernetes-native and cloud-agnostic. It runs on any CNCF-compliant Kubernetes distribution, including:

- Amazon EKS
- Google GKE
- Azure AKS
- DigitalOcean Kubernetes
- On-prem distributions like OpenShift, Rancher, and VMware Tanzu

## Similar Concepts

- **vCluster** – creates lightweight virtual clusters within a single physical cluster.
- **Kiosk** – another Kubernetes multi-tenancy framework focused on namespace templating and user onboarding.
- **OpenShift Projects** – Red Hat’s flavor of multi-tenancy with built-in policy enforcement.