Kubernetes Multi-Tenancy: Implementing Hierarchical Namespaces with HNC

Managing a large Kubernetes cluster for multiple teams is a headache. You’ve likely faced the "namespace sprawl" problem—where you end up with hundreds of namespaces, each requiring its own set of NetworkPolicies, RBAC rules, and ResourceQuotas. It’s brittle, it’s manual, and it’s a recipe for configuration drift.

That’s where Kubernetes multi-tenancy comes in, specifically through the Hierarchical Namespace Controller (HNC). Instead of treating namespaces as flat, isolated buckets, HNC lets you create parent-child relationships. This hierarchy allows you to propagate policies and resources downward, making your cluster management actually scalable.

Why HNC Matters for Multi-Tenancy

In a standard Kubernetes setup, namespaces are independent. If you want to enforce a security policy across thirty namespaces, you have to apply it thirty times. If you forget one, you’ve got a security hole.

HNC changes this by introducing the concept of subnamespaces. When you define a policy at a parent level, HNC ensures it flows down to all children. It’s not just about organization; it’s about inheritance.

Getting Started with HNC

First, ensure you're running a supported Kubernetes version (1.24+ is recommended). You’ll need cert-manager installed, as HNC relies on it for webhooks.

Install the HNC manager using kubectl:

Bash
kubectl apply -f https://github.com/kubernetes-sigs/hierarchical-namespaces/releases/download/v1.1.0/hnc-manager.yaml

Once installed, verify the controller is running:

Bash
kubectl get pods -n hnc-system

Creating Your First Hierarchy

Let’s say you have a "Product" team that needs multiple environments. Instead of creating prod-frontend and prod-backend as separate, unrelated entities, you create a parent namespace called product-team.

1. Create the parent namespace:

   Bash
   kubectl create ns product-team
   

2. Create subnamespaces: Using the kubectl-hns plugin (which you should definitely install via Krew), create the children:

   Bash
   kubectl hns create frontend -n product-team
   kubectl hns create backend -n product-team
   

Now, frontend and backend are children of product-team. If you inspect the frontend namespace, you’ll see an annotation indicating its parent.

Enforcing Resource Isolation

The real power of Hierarchical Namespace Controller (HNC) is policy propagation. Let’s say you want to restrict egress traffic for the entire product team.

Create a NetworkPolicy in the parent namespace:

YAML
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: deny-all-egress
  namespace: product-team
spec:
  podSelector: {}
  policyTypes:
  - Egress

HNC detects this and automatically copies the policy into the frontend and backend namespaces. If you add a new subnamespace tomorrow, it inherits the policy instantly. You don’t have to touch it.

Best Practices for HNC

1. Use the kubectl-hns plugin: Don't try to manage annotations manually. The plugin abstracts the complexity and prevents configuration errors.
2. Limit direct changes to children: If you need to change a policy, always change it at the parent level. If you force a change in a child namespace, HNC will flag it as a conflict.
3. Monitor the HNC status: Use kubectl hns tree product-team to visualize your structure. It provides an immediate view of your hierarchy and any health issues within the tree.
4. Combine with ResourceQuotas: HNC doesn't replace ResourceQuotas. Use HNC to manage the structure of your multi-tenancy, and use standard Kubernetes ResourceQuotas to manage the consumption within those namespaces.

The Reality of Kubernetes Resource Isolation

Using HNC isn't a silver bullet for total security. It’s an organizational tool. You still need to implement proper RBAC and NetworkPolicies to ensure that a pod in frontend can't talk to a database in another team's namespace.

However, HNC solves the "management at scale" problem. It turns your cluster from a flat, manual mess into a structured, hierarchical system. When you're managing 500+ namespaces, you’ll thank yourself for adopting a hierarchical approach early.

It’s about reducing the cognitive load on your SRE team. By automating the propagation of policies, you spend less time running kubectl apply and more time building features that actually move the needle.