FAQs

Capsule is a Kubernetes operator that turns a single cluster into a shared, multi-tenant platform. It implements a multi-tenant, policy-based environment as a micro-services-based ecosystem with a minimalist approach, leveraging only upstream Kubernetes. Its own description is a multi-tenancy and policy-based framework for Kubernetes.

Kubernetes namespaces are flat, with no hierarchy and no native way to share resources between the namespaces belonging to one team. The consequences are that isolation becomes all or nothing, that administrators turn into a bottleneck manually creating every namespace, and that teams end up with a cluster each, which is cluster sprawl. Capsule introduces a grouping abstraction so that self-service can be delegated safely.

A cluster-scoped custom resource that groups one or more namespaces under a shared set of boundaries. Everything defined on the Tenant is inherited automatically by all of its namespaces: role bindings, resource quotas and limits, admission rules such as allowed registries and pull policies, and templated resource distribution. Namespaces carry an owner reference back to the Tenant and a tenant label.

Clastix created Capsule, with the first commit in June 2020, and it was the first multi-tenancy operator of its kind for Kubernetes. It is now hosted in the vendor-neutral projectcapsule GitHub organization with published governance and a maintainer list.

Capsule was accepted into the CNCF on 13 December 2022 at Sandbox maturity, and it remains at Sandbox today. Some third-party articles describe it as a CNCF Incubator project; that is incorrect and should not be repeated.

Apache 2.0.

The project describes itself as stable, following the Kubernetes definition of stable, and states that although it is under frequent development it is ready for use in production and is currently used in both public and private deployments.

Exactly like the English word capsule.

There are three practical personas. The cluster administrator installs Capsule, creates Tenants, and sets budgets and policies, and is then out of the day-to-day path. The tenant owner creates and manages namespaces within their Tenant and assigns access to team members, without needing any cluster-level permissions. The tenant user deploys workloads inside those namespaces within the owner’s limits.

Three ways, which can be combined. Inline on the Tenant, naming a user, group, or service account and optionally the cluster roles they receive. Through a dedicated cluster-scoped TenantOwner resource matched to tenants by label selector, which is more loosely coupled and merges with inline owners. Or implicitly, by labeling a TenantOwner with the tenant name.

By default, two cluster roles bound per namespace: the Kubernetes built-in admin role, and a Capsule-provided namespace deleter role. Narrower roles can be assigned per owner instead. Owners can create and delete their own namespaces, but they cannot list namespaces, nodes, persistent volumes, or tenants at cluster scope without the proxy.

No. Tenant resources remain under cluster administrator control.

By the groups carried on every request, with a configurable default Capsule group. In production this is done with X.509 client certificates or OIDC tokens, and service accounts are matched by their system group or user scope.

Capsule can apply a resource quota at tenant scope, aggregating usage across every namespace in the tenant rather than applying a fixed quota per namespace, which is the behavior most platform teams actually want. The current recommended model is ResourcePools, which are cluster-scoped resources defining a pool of resources plus the namespaces permitted to claim from it, with claiming done through a namespaced ResourcePoolClaim. Bound claims stack additional resources on top of the quota provisioned into the claiming namespace, and claim lifecycle is deliberately decoupled from pool lifecycle. Global and custom quota resources are also available in the current release line.

Yes, with a namespace quota on the Tenant. Attempts to exceed it are rejected by the admission webhook with a clear message directing the user to the platform team.

Either by enforcing a tenant name prefix, which is recommended for production and makes assignment automatic, or by requiring an explicit tenant label on namespace creation. By default namespaces cannot be moved between tenants and are deleted when the Tenant is deleted.

Yes. Cordoning a namespace prevents any changes within it, which is useful during change freezes. Cordoning the whole Tenant cordons all of its namespaces, which then cannot be individually uncordoned or deleted.

A wide surface, through validating and mutating admission webhooks. For scheduling: limit ranges, allowed priority classes and runtime classes with tenant defaults, node selectors, and device classes for dynamic resource allocation. For connectivity: allowed external IPs, forbidden service labels and annotations, blocked service types, allowed gateway classes and ingress classes with defaults, allowed ingress hostnames with collision scoping and wildcard denial, and network policies. For storage: allowed storage classes with a tenant default, and prevention of cross-tenant persistent volume mounts. For images: allowed container registries and allowed image pull policies. Metadata rules cover required, default, and allowed namespace labels and annotations, quality-of-service class, and scheduler name.

Yes. The current model is Rules, which supports namespace selectors, audiences, and explicit allow or deny actions. The legacy enforcement fields are marked deprecated, and the individual limit range and network policy fields are flagged for future deprecation in favor of replications.

Not by itself, and the documentation says so plainly. Because of the way the NetworkPolicy API works, a user can add a policy that contradicts what the Tenant set, working around the original limitation. The documented mitigations are to give owners a restricted role rather than the full admin role, or to use cluster-level policy resources from Calico or Cilium, which establish packet-filter ordering. Tenant-defined policies cannot be deleted by owners and are recreated by the controller if removed.

Through replications. A TenantResource is created inside a tenant namespace, and a GlobalTenantResource is cluster-scoped with tenant and namespace selectors. Both support resync periods, pruning on delete, raw items, and templating for dynamic values such as the tenant or namespace name. Impersonation is supported and is the recommended hardening. This is the current way to distribute limit ranges, network policies, and selective role bindings.

Capsule Proxy is an add-on that closes a gap in Kubernetes RBAC. Kubernetes cannot list only the cluster-scoped resources you own, because there is no ACL-filtered API, so granting list on namespaces would expose every namespace in the cluster. Without the proxy, a tenant user running a namespace listing gets a forbidden error. With it, standard commands return only that user’s own resources, including listing pods across all their namespaces and the persistent volumes backing their claims. The design goal is to keep the same user experience across every Kubernetes distribution rather than introducing mirrored custom resources and lock-in.

Filter other cluster-scoped kinds per owner, including nodes, storage classes, ingress classes, and priority classes, now moving to dedicated proxy settings resources. Reflect role bindings to grant list capabilities to non-owners across namespaces. Integrate with Gangplank for issuing real kubeconfigs. Support forwarded client certificate authentication and trusted source configuration. Expose specific public paths without authentication. It can be deployed as a Deployment or DaemonSet and exposed by NodePort, Ingress, or Route. It can also confine an operator inside a tenant: add the operator’s service account as a tenant owner and point it at the proxy, and it behaves as if it had cluster-admin while remaining fully scoped to that tenant.

Helm 3, since the Helm chart is the only officially supported installation method and handles CRD lifecycle. A Kubernetes cluster with the pod node selector, limit ranger, resource quota, and mutating and validating admission webhook admission controllers enabled. A cluster-admin kubeconfig. cert-manager is required by default, and self-signed cert-manager certificates for the admission webhooks became the default in the current release line.

The project supports the latest minor version of Kubernetes. The installation requirements state a floor of v1.16 for running Capsule at all, but backwards compatibility with older Kubernetes and OpenShift versions is offered by commercial vendors rather than by the project itself. Confirm the specific version in the release notes for the Capsule release you plan to run.

By default yes, because Kubernetes RBAC escalation prevention means a subject creating a role binding must already hold those permissions or hold bind on the cluster role. For production the documentation recommends strict RBAC mode, which replaces the cluster-admin binding with a narrow cluster role plus bind permission on a configurable list of bindable cluster roles and Capsule’s own managed roles.

Some webhooks cause problems when Capsule is not running, which is especially acute on single-node clusters. The recommendation is to use match conditions on all webhooks to exclude system-critical components and namespaces. The node webhook is disabled by default and, if enabled, should be considered with a permissive failure policy. The namespace webhook is enabled by default and should not be disabled.

Client connection queries per second and burst, concurrent reconcile workers, cache sync timeout, leader election timing, and built-in API priority and fairness configuration.

Yes, and it is a stated design goal: Capsule is completely declarative and GitOps ready, with no special requirements for Argo CD or Flux. With Argo CD, specific sync options are needed on the Capsule configuration resource because Argo validates before the CRDs are installed, and a separate Capsule Argo add-on translates Tenants into Argo AppProjects automatically. With Flux, the documented pattern is a Helm release from the OCI repository with drift detection enabled, and a Capsule Flux add-on lets tenants manage their own resources, including creating namespaces, from their own Git repositories without escaping tenant policy.

Yes, with documented setup. The key steps are removing subjects from the self-provisioners cluster role binding and preventing OpenShift from reverting it, extending the admin role appropriately, and blocking users from mutating OpenShift-managed labels and annotations, since some of those can otherwise allow a security context constraint bypass. Two limitations are documented: a tenant owner cannot create a project through the OpenShift web console and must use the command line, and the login token copied from the console points at the Kubernetes API rather than the proxy, so the server address must be adjusted manually.

Documented integrations include Argo CD, Flux, Kyverno, Velero, the Kubernetes Dashboard, Headlamp, Envoy Gateway, External Secrets Operator, OpenCost, Teleport, OpenShift, and Rancher. Add-ons include Capsule Proxy, the Argo add-on, the Flux add-on, the Rancher add-on, a Cortex proxy that routes metrics to per-tenant Cortex organizations, and a community CoreDNS plugin.

Several things, stated plainly in its own documentation. Tenant owners cannot create custom resource definitions, because that requires cluster-admin, and this is described as a known limitation of any multi-tenancy model built on a single shared control plane. There is no hierarchy of Tenants, since all Tenants sit at the same level, although multiple Tenants can share an owner. Capsule is not a general-purpose admission policy engine and does not attempt to enforce every possible security standard, which is why Kyverno is a documented companion. All tenants share one API server and one etcd, so custom resource definitions and API extensions are shared and can conflict. Namespaces cannot be moved between tenants by default and are deleted with their Tenant.

When tenants need what a shared control plane cannot give them: full cluster-admin rights, their own custom resource definitions, their own Kubernetes version, or isolation that extends below the API layer. Capsule is the efficient choice when tenants can share a control plane and namespace-level isolation is sufficient, because it maximizes resource utilization and minimizes operational overhead. The two are frequently used together, and kMetal uses both.

Yes, two on the current release line. A high-severity advisory covering users being able to create cluster-scoped resources anywhere in the cluster if permitted to create tenant resources, mitigated immediately by using impersonation for tenant resources. A moderate-severity advisory covering namespace hijacking through namespace status privileges where platform administrators had explicitly granted those privileges, fixed by routing status subresource requests through the admission webhook. Both are published on the project’s What’s New page.

Porting more properties to the namespace rule model, transformers and health checks for tenant resources, a break-the-glass mechanism for temporary elevation of tenant owner permissions with platform administrator approval, custom Argo CD health checks upstream, and proxy work including restoring RBAC reflection and moving proxy settings to a global resource.

The project’s self-reported adopters page lists Bedag Informatik, Begasoft, the US Department of Defense, Die Mobiliar, Enreach, Fastweb, Klarrio, KubeRocketCI, ODC-Noord, PITS Global Data Recovery Services, Politecnico di Torino, Reevo, University of Torino, Velocity, Wargaming.net, and Zynga.

Yes. TomTom’s engineering team published a detailed account of running Capsule in production for its developer experience platform. They chose Capsule over per-tenant control plane approaches specifically because of synchronization and observability complexity, and because per-tenant control planes would let tenants deploy anything. They highlight a very simple kubeconfig for developers via Capsule Proxy, tenant metadata stamped onto workloads for cost attribution and paging, ingress hostname protection because external DNS is a shared service, and a tiered GitOps repository layout driven by Flux with an Argo AppProject per tenant.

They sit at different points on the isolation spectrum. Capsule uses native Kubernetes primitives, with no custom API server, no virtualization layer, and no syncing complexity, which makes it lightweight and cheap but means custom resource definitions are shared and can conflict. vCluster gives each tenant an isolated API so tenants can install their own CRDs and run their own Kubernetes version. Independent commentary recommends Capsule where tenants can share, a dedicated-control-plane approach where tenants need admin rights, and a hybrid where both apply.

HNC was retired. The repository was archived in April 2025 following a SIG Auth decision, due to a lack of maintainers and adopters. Capsule’s model differs in that a Tenant is a collector of namespaces that enforces policy and calculates quota usage across all of them, rather than a hierarchical tree.

Yes, from two vendors listed on the project’s support page: Clastix, the creators of the project, and Peak Scale. Vendors also provide backwards compatibility with older Kubernetes and OpenShift versions that the project itself does not support.

The Capsule channel on Kubernetes Slack, the community repository in the projectcapsule organization, and CNCF DevStats for project metrics. Capsule has been featured in CNCF project demos at KubeCon Europe and in CNCF online programs.