Introducing Hierarchical Namespaces in Kubernetes for Secure Multi‑Tenant Clusters

Managing a large number of users securely on a single Kubernetes cluster is challenging because different organizations use the platform in varied ways, making a one‑size‑fits‑all tenancy model difficult. While Kubernetes provides building blocks such as RBAC and NetworkPolicies, the more effectively these are used, the easier it is to construct a secure multi‑tenant environment.

The most fundamental building block is the namespace , which underpins almost all control‑plane security and sharing policies. By default, RBAC, NetworkPolicies, and ResourceQuotas operate within namespaces, and objects like Secrets, ServiceAccounts, and Ingress can be used freely inside a namespace while remaining isolated from others.

Namespaces have two key properties that make them ideal for policy enforcement:

They can represent ownership, as most Kubernetes objects must reside in a namespace, allowing all objects in that namespace to be associated with a single owner.

Creation and usage of namespaces require authorization; only privileged administrators can create them, while other users need explicit permissions to view or modify resources within them.

However, plain namespaces have limitations. They lack flexibility for scenarios such as a team that needs multiple micro‑services with different confidentiality levels and quotas. Separate namespaces for each service create two problems: (1) no shared ownership across those namespaces, preventing policies from applying across them, and (2) the need for high‑privilege administrators to create new namespaces, which becomes cumbersome as the organization grows.

Hierarchical namespaces address these issues by allowing a parent namespace to own child namespaces, enabling two additional capabilities:

Policy inheritance : policies (e.g., RBAC RoleBindings) from a parent are automatically copied to its children.

Delegated creation rights : child namespaces can be created using a limited set of permissions inherited from the parent, reducing the need for cluster‑level privileges.

The implementation is provided by the Hierarchical Namespace Controller (HNC) , which consists of a controller running in the cluster and a kubectl-hns plugin for user interaction.

Example usage with the plugin:

$ kubectl hns create svc1-team-a -n team-a

This creates a child namespace svc1-team-a under the parent team-a . The child behaves like a regular namespace but inherits policies from its parent.

Viewing the hierarchy:

$ kubectl hns tree team-a
# Output:
team-a
└── svc1-team-a

If the parent namespace contains policies, they appear in the child as well. For instance, an RBAC RoleBinding sres defined in team-a is automatically present in svc1-team-a with a label indicating inheritance.

$ kubectl describe rolebinding sres -n svc1-team-a
# Output includes:
Labels: hnc.x-k8s.io/inheritedFrom=team-a

HNC also adds hierarchical labels that can be used in other policies, such as a NetworkPolicy that selects all descendant namespaces of team-a :

kind: NetworkPolicy
apiVersion: networking.k8s.io/v1
metadata:
  name: allow-team-a
  namespace: team-a
spec:
  ingress:
  - from:
    - namespaceSelector:
        matchExpressions:
        - key: 'team-a.tree.hnc.x-k8s.io/depth'
          operator: Exists

This policy propagates to all descendants and permits intra‑namespace traffic, with the "tree" label managed exclusively by HNC to reflect the current hierarchy.

For more details, refer to the official HNC user guide. If hierarchical namespaces suit your organization, you can try HNC v0.5.1 on GitHub, keeping in mind that early‑stage software should be used cautiously in production, and feedback helps accelerate the path to HNC 1.0.