Join the community on the #capsule channel in the Kubernetes Slack.

Kubernetes multi-tenancy made easy

Capsule is a multi-tenancy framework for Kubernetes. It gives teams the freedom to create and manage their own namespaces, while access, resource budgets, and policies stay under platform control. It runs as a Kubernetes operator and relies only on upstream Kubernetes: no custom distribution and no extra tooling for your users to learn.

What's the problem with the current status?

Kubernetes namespaces have no hierarchy. As soon as multiple teams or customers share a cluster, the choices are all costly:

• Namespaces only: cluster admins become a bottleneck, and developers cannot list their own namespaces.
• A custom CRD: your teams learn an API that exists on your cluster and nowhere else.
• Multiple clusters: another control plane per team to upgrade, secure, and pay for, known as _clusters sprawl_.

Entering Capsule

Capsule groups a team's namespaces into a _Tenant_, a lightweight cluster-scoped resource. Cluster administrators define the tenant's owners, rules, and budgets once, and every namespace in the tenant inherits them. Tenant owners then create ordinary namespaces on their own, without cluster-admin rights or a ticket.

| Role | Responsibility | | --- | --- | | Cluster Admin | Installs Capsule, creates Tenants, and sets resource budgets and policies. | | Tenant Owner | Creates and manages namespaces within their Tenant and grants access to team members. | | Tenant User | Deploys workloads inside tenant namespaces, within the limits the owner has set. |

As a cluster admin, you describe a team once as a Tenant:

apiVersion: capsule.clastix.io/v1beta2
kind: Tenant
metadata:
  name: solar
spec:
  owners:
    - kind: User
      name: alice
  forceTenantPrefix: true
  rules:
    - quota:
        - name: shared-compute
          hard:
            requests.cpu: "8"
            requests.memory: 16Gi

Alice, the tenant owner, now creates namespaces herself, without cluster-admin rights or a ticket. Capsule enforces the boundaries through admission control: it grants owners access, applies the configured quotas and policies, and rejects requests that fall outside the tenant's rules.

$ kubectl create namespace solar-dev
namespace/solar-dev created
$ kubectl create namespace experiments
The Namespace name must start with 'solar-' when ForceTenantPrefix is enabled in the Tenant.
$ kubectl apply -n solar-dev -f pod.yaml
resource exceeds GlobalResourceQuota "solar-shared-compute": requests.cpu (requested=2, current=7, projected=9, hard=8, exceededBy=1)

Project Status

Quick start

Capsule is installed with its Helm chart, which also manages the CustomResourceDefinitions. The webhooks need TLS certificates. By default the chart gets them from cert-manager, so install cert-manager first, then:

helm install capsule oci://ghcr.io/projectcapsule/charts/capsule -n capsule-system --create-namespace

Without cert-manager, let Capsule generate and inject its own certificates instead:

helm install capsule oci://ghcr.io/projectcapsule/charts/capsule -n capsule-system --create-namespace \
  --set 'certManager.generateCertificates=false' \
  --set 'tls.enableController=true' \
  --set 'tls.create=true'

See the installation guide for all options.

Then follow the quickstart to create your first Tenant, or try the live demo.

Features

Tenants

Group namespaces by team, product, or customer. Owners manage their namespaces and grant developers access to deploy applications. RBAC bindings are propagated to every namespace automatically.

Namespace rules

Configure policy on a per-namespace basis. Namespace selectors give namespaces within the same Tenant different profiles. Rules mutate new resources (such as workload placement, seccomp, AppArmor, or Gateway references) and enforce policies on the result, for example allowed registries, workload types, ingress hostnames, NetworkPolicy CIDRs, and namespace metadata. Rules can be applied conditionally with CEL expressions.

Resource management

Control the resources consumed by tenants and prevent them from overtaking:

• GlobalResourceQuota enforces one shared ceiling across selected namespaces.
• ResourcePool allocates capacity to namespaces through claims.
• CustomQuota and GlobalCustomQuota limit custom quantities calculated from any Kubernetes object.

Replications

Propagate Secrets, NetworkPolicies, LimitRanges, and other resources into tenant namespaces with TenantResource and GlobalTenantResource, using Go templates for values such as the namespace or tenant name.

Capsule Proxy

Let tenant users list only their own namespaces, pods, and volumes through the standard Kubernetes API with their existing tools. Capsule Proxy is optional and released separately.

Self-service, GitOps ready, and a native experience

Developers self-provision within their assigned boundaries. Everything is declarative and GitOps ready, built on plain Kubernetes without additional management layers or customized binaries.

Ecosystem

Tenant namespaces are ordinary namespaces, so your tools keep working. Integrations for Argo CD, Rancher, OpenShift, Headlamp, Kyverno, Velero, Crossplane, Tekton, and more make them tenant-aware. See the ecosystem.

How it fits together

Documentation

Please check the project documentation for the cool things you can do with Capsule. What's new lists the features of the current release.

Contributions

Capsule is Open Source with Apache 2 license and any contribution is welcome.

Community meeting

Join the community, share and learn from it. You can find all the resources to how to contribute code and docs, connect with people in the community repository.

Please read the code of conduct.

Adopters

See the ADOPTERS.md file for a list of companies that are using Capsule.

Project Governance

You can find how the Capsule project is governed here.

Maintainers

Please refer to the maintainers file available here.

CLOMonitor

CLOMonitor is a tool that periodically checks open source project repositories to verify they meet certain project health best practices.

Read how we log changes here

Software Bill of Materials

All OCI release artifacts include a Software Bill of Materials (SBOM) in CycloneDX JSON format. More information about this is available here

FAQ

• Q. How do you pronounce Capsule?

• Q. Is it production grade?

• Q. Does it work with my Kubernetes XYZ distribution?

• Q. Do you provide commercial support?

Project repositories

All repositories live in the projectcapsule GitHub organization.

Core

| Repository | Scope | | --- | --- | | Capsule | Controller, namespace profiling rules, admission webhooks, and Helm chart. | | Capsule Proxy | Optional Kubernetes API proxy for tenant users, developed and released separately. | | Website | Source for the user documentation and project website. |

Addons

| Repository | Scope | | --- | --- | | Change Windows | Controller for maintenance windows and scheduled actions. See the documentation. | | Resource Permits | Approval flows native to Kubernetes for requesting predefined services. See the documentation. | | SOPS Operator | Create SOPS Secrets on Kubernetes in a multi-tenant way. See the documentation. | | Observability Tenancy | Controllers to align your monitoring stack with multi-tenancy. | | Headlamp Plugin | Headlamp plugins for Capsule. See the documentation. |

Capsule and Capsule Proxy are the runtime codebases. The release process. in this repository builds and publishes the Capsule controller and Helm chart. More addons and integrations are listed in the ecosystem.