Join the community on the #capsule channel in the Kubernetes Slack.
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.
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.
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: 16GiAlice, 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)
This project is stable. We follow the Kubernetes definition of stable.
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-namespaceWithout 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.
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.
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.
Control the resources consumed by tenants and prevent them from overtaking:
GlobalResourceQuotaenforces one shared ceiling across selected namespaces.ResourcePoolallocates capacity to namespaces through claims.CustomQuotaandGlobalCustomQuotalimit custom quantities calculated from any Kubernetes object.
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.
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.
Developers self-provision within their assigned boundaries. Everything is declarative and GitOps ready, built on plain Kubernetes without additional management layers or customized binaries.
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.
Please check the project documentation for the cool things you can do with Capsule. What's new lists the features of the current release.
Capsule is Open Source with Apache 2 license and any contribution is welcome.
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.
See the ADOPTERS.md file for a list of companies that are using Capsule.
You can find how the Capsule project is governed here.
Please refer to the maintainers file available here.
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
All OCI release artifacts include a Software Bill of Materials (SBOM) in CycloneDX JSON format. More information about this is available here
-
Q. How do you pronounce Capsule?
A. It should be pronounced as
/ˈkæpsjuːl/. -
Q. Is it production grade?
A. Although under frequent development and improvement, Capsule is ready to be used in production environments as currently, people are using it in public and private deployments. Check out the release page for a detailed list of available versions.
-
Q. Does it work with my Kubernetes XYZ distribution?
A. The community edition supports the latest Kubernetes release on vanilla Kubernetes, which is what our community end-to-end tests run against. Other Kubernetes distributions, for example OpenShift, and older Kubernetes versions are supported through the Enterprise offering. See the support page.
-
Q. Do you provide commercial support?
A. Yes, there is commercial support for Capsule, including consulting and priority feature support. See the support page for more information.
All repositories live in the projectcapsule GitHub organization.
| 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. |
| 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.