A short definition first, so that every later chapter has something solid to stand on.

The Hierarchical Namespace Controller, usually shortened to HNC, is an add-on for Kubernetes that lets namespaces form a tree. One namespace can be the parent of others, and the others are its children. A child can have children of its own. Once the relationships exist, HNC does two main things for you. It copies chosen objects, such as permissions and policies, from a parent down into all its descendants. And it lets people who control a parent namespace create new child namespaces without asking a cluster administrator.

HNC does not change Kubernetes itself. A namespace is still just a namespace as far as the core system is concerned, and the cluster still keeps them in a flat list. HNC adds a layer on top. It stores the parent and child links in its own objects, watches for changes, and keeps the right copies in the right places.

To see what is missing, we first need to be clear about what namespaces give us today.

A namespace is a way to divide one cluster into several virtual sections. Most objects, such as Pods, Services, Deployments and ConfigMaps, belong to exactly one namespace. Names only need to be unique inside a namespace, so two teams can each have a Deployment called web without a clash. A few objects, such as Nodes and PersistentVolumes, are cluster-wide and do not live in any namespace.

Namespaces are also the main unit for control. Permissions are usually granted per namespace, using Roles and RoleBindings. Resource limits are applied per namespace, using ResourceQuotas. Network rules are written per namespace, using NetworkPolicies. A policy engine or an admission rule often looks at the namespace to decide what is allowed.

What namespaces do not give you

Namespaces have no relationship to each other. There is no such thing as a namespace inside a namespace. Each is an equal in a flat list. Rules written in one namespace do not affect any other. To apply the same rule to twenty namespaces, someone has to create twenty copies and keep them all up to date by hand or with automation.

Hierarchy is not a luxury. It solves several very concrete problems that grow with the size of a cluster.

Everything HNC does grows from a very small idea about how namespaces are connected.

HNC arranges namespaces in a forest, which is simply a collection of trees. Each tree has one namespace at the top, called the root. Every other namespace in that tree has exactly one parent. A namespace with no parent is a root. A namespace with no children is a leaf. Cycles are not allowed, so a namespace can never be its own ancestor.

flowchart TD
  ORG["org: root"] --> TA["team-a"]
  ORG --> TB["team-b"]
  TA --> TAD["team-a-dev"]
  TA --> TAS["team-a-staging"]
  TA --> TAP["team-a-prod"]
  TB --> TBD["team-b-dev"]
  TB --> TBP["team-b-prod"]
        

Two simple rules about direction

Things flow in one direction only. Objects and rules move down the tree, from a parent to its children, grandchildren and so on. Nothing flows upward. A rule in a child never affects its parent, and a rule in one child never affects its sibling. This one-way flow keeps behavior easy to predict: to know everything that applies to a namespace, you look at it and at its ancestors, and nowhere else.

Now we open the box and look at the parts that make the tree real.

HNC is installed as a program that runs inside the cluster, in its own namespace, usually called hnc-system. It is built like most Kubernetes add-ons. It has custom resource definitions that add new object types. It has a set of controllers that watch objects and make changes. And it has admission webhooks that check changes before they are saved.

flowchart LR
  U["User or automation"] --> API["API Server"]
  API -->|"Admission check"| W["HNC webhooks"]
  W --> API
  API -->|"Watch events"| C["HNC controllers"]
  C  F["In-memory forest"]
  C -->|"Create and update copies"| API
        

The forest in memory

When HNC starts, it reads all namespaces and hierarchy objects from the API server and builds the forest in memory. After that, it keeps the forest up to date by listening for changes. Whenever a controller needs to know “who are the descendants of this namespace”, it asks the forest and gets an instant answer. This makes propagation quick. It also means that after a restart, HNC rebuilds its picture from the objects stored in the cluster, so the real source of truth stays in the API server.

Getting started is straightforward, and a small command line plugin makes daily use friendly.

HNC is installed by applying the manifests published with each release, which create the controller, the definitions and the webhooks in the HNC namespace. Choose a release that supports your Kubernetes version, and read its notes. Because HNC adds webhooks that can affect namespaces and objects across the cluster, it is wise to try it first in a test cluster.

HNC also comes with a plugin for the kubectl command line tool, usually installed through the krew plugin manager. The plugin adds a command called kubectl hns with several subcommands. These do not do anything special that could not be done by editing objects directly, but they make common tasks much easier and their output much clearer.

What changes after installation

Right after installation, nothing dramatic happens. Existing namespaces simply become roots of their own trees, because none of them has a parent yet. By default, RBAC objects, meaning Roles and RoleBindings, are already set up to propagate. From that point, you can start attaching namespaces together or creating subnamespaces.

Subnamespaces are the part of HNC that makes self-service possible, and the trick behind them is clever.

Creating a namespace normally needs cluster-level permission, because a namespace is not inside any other namespace. HNC solves this with a small helper object called a subnamespace anchor. An anchor is an ordinary object that lives inside the parent namespace. Because it is namespaced, a person with rights in the parent can create it, with no cluster-level rights at all.

When the anchor appears, HNC reacts. Its controller, which does have cluster-level rights, creates a real namespace with the name given in the anchor, and records that the new namespace is a child of the parent. The person never needed the power to create namespaces. They only needed the ordinary power to create an anchor object in their own namespace, and HNC did the rest on their behalf.

sequenceDiagram
  participant T as Team lead
  participant A as API Server
  participant H as HNC controller
  T->>A: Create anchor named dev inside team-a
  A-->>H: Watch event: new anchor
  H->>A: Create namespace dev
  H->>A: Mark team-a as parent of dev
  H->>A: Update anchor status to Ok
  A-->>T: Anchor shows the new namespace is ready
        

Subnamespaces are not the only way to build a tree. You can also connect namespaces that already exist.

HNC distinguishes two kinds of child namespaces. A subnamespace is created through an anchor, and is tied to its parent by that anchor. A full namespace is a normal namespace that was created in the usual way by an administrator, and then attached to a parent afterwards by setting its parent. Both kinds behave the same way for propagation. The difference is mostly in how they are created and how they are deleted.

Who may set a parent

Setting the parent of a namespace is a powerful action, because it changes which rules flow into it. HNC therefore checks permissions on both sides. The person must be allowed to change the hierarchy setting of the child, and must also have the right to add children to the new parent. This prevents someone from attaching their own namespace to a powerful tree in order to inherit its permissions.

Each namespace in the tree has one small object that records its place in it.

The place of a namespace in the tree is stored in an object called the hierarchy configuration. There is at most one of these in each namespace, and it has a fixed name, so that it can always be found. Its spec, the part that people edit, holds the name of the parent and a setting about whether deleting this namespace’s anchor or parent should also remove everything below. Its status, the part that HNC fills in, lists the children of the namespace and a set of conditions that describe any problems.

Conditions are the health report

Conditions tell you what is wrong, and they are the first place to look when something seems off. A condition can warn that the named parent does not exist, that a cycle was detected, that an ancestor has a problem, or that an object could not be copied because of a conflict. Some conditions are only warnings about a single object. Others are serious, and cause HNC to stop activities in the affected part of the tree until the problem is fixed, to avoid making things worse.

Propagation is the second big feature of HNC, and it is where most of the daily value comes from.

When you create an object in a namespace that is marked as a source, HNC makes a copy of it in every descendant of that namespace. If you change the original, the copies change too. If you delete the original, the copies are deleted. The copies are real objects in each descendant, so Kubernetes treats them like any other, and a Role copied into a child namespace grants real permissions there.

flowchart TD
  S["Source object created in team-a"] --> C1["Copy in team-a-dev"]
  S --> C2["Copy in team-a-staging"]
  S --> C3["Copy in team-a-prod"]
  C3 --> C4["Copy in any further child below team-a-prod"]
        

What kinds of objects can propagate

By default, two kinds of objects propagate: Roles and RoleBindings. These are the objects that control who may do what, and they are by far the most common reason for using a hierarchy. Other kinds of objects can be added to the list by configuration, and we will cover how in the next chapters. Typical additions are NetworkPolicies, ResourceQuotas, ConfigMaps, Secrets and limit ranges. Almost any namespaced object type can be added, including custom resources.

The most loved feature of the controller is also the simplest: give someone access once, and every child namespace inherits it.

Kubernetes controls who may do what with a system called RBAC, short for role-based access control. A Role is a list of allowed actions, such as reading Pods or editing Deployments. A RoleBinding connects a Role to a person, a group or a service account inside one namespace. Without hierarchy, a RoleBinding in one namespace says nothing about any other namespace. If a team owns twelve namespaces, somebody must create twelve bindings and keep all twelve in sync.

The controller changes this by treating Roles and RoleBindings as things that flow downward by default. When you create a RoleBinding in a parent namespace, the controller creates an identical copy in every child, grandchild and deeper descendant. When you change the original, every copy changes. When you delete the original, every copy disappears. The people named in the binding therefore gain the same access across the whole subtree with one action.

Why this is a safe default

Access flows only downward. A person who is granted rights in a child gains nothing in the parent. This matches how most organizations think: a department head can see everything inside the department, while a single project member sees only that project. The direction of flow makes the permission model easy to explain and easy to audit.

Roles and bindings travel together

A binding points to a Role by name. If only the binding were copied and the Role were left behind, the copy would point at nothing. For this reason both objects propagate together. A team can define a Role called “namespace editor” in the parent and bind it to the team’s group. Every child then has the Role and the binding, and they work at once.

Roles and bindings are only the start. A single cluster-wide object tells the controller which other kinds of objects should travel.

The controller has one cluster-wide settings object called HNCConfiguration. There is exactly one of it, and it lists resource types together with a mode for each type. A resource type is a kind of object, such as ConfigMap, Secret, NetworkPolicy or ResourceQuota. The mode decides what the controller does with objects of that type.

The common modes

The names and details can change between versions, so check the documentation for your release. In general there are three ideas. The first is propagate: objects of this type that you place in a parent are copied down to descendants. The second is remove: the controller deletes inherited copies, which is useful when you want to stop a type from flowing without deleting the originals. The third is ignore: the controller does nothing at all for the type, which is the state of every type not on the list.

Which types make good candidates

Good candidates are objects that every namespace in a subtree should share and that rarely differ. Examples include policies that apply to every workload, a shared configuration file with a company-wide setting, or a pull credential for a private image registry. Poor candidates are objects that hold unique data for each application, or objects that vary by environment.

Sometimes one specific object should stay home, or should go only to some children. Annotations give you fine control.

Switching a whole type to propagate is a blunt tool. Real life has exceptions: a Role that is meant only for the parent, or a Secret that should reach just one branch of the tree. The controller offers small notes called annotations that you attach to the individual object. An annotation is a label-like key and value stored in the object’s metadata that tools can read. The controller reads a few of them to decide how that one object should travel.

The ideas behind the selectors

There are four main ideas. One note can say that the object should not propagate at all. Another can say it should propagate everywhere, even if the type is normally excluded in some situations. A third can pick children by their names or labels, in the style of a label selector. A fourth can pick whole subtrees through the tree labels you will meet soon. The exact annotation keys have changed over time, so read the documentation for the key names in your version rather than copying them from a blog post.

Why selectors are powerful but risky

Selectors let you share a credential with exactly the right children. They also create invisible rules that live inside individual objects. A reader looking at a child namespace sees a copy but cannot tell why the other children did not get one. Keep a short written record of every selected object, and prefer the tree structure to express most of your intent.

A copy in a child is not an ordinary object. It is marked, protected and tied to its source.

When the controller creates a copy of a parent object in a child, it labels that copy with a marker whose key is hnc.x-k8s.io/inherited-from and whose value is the name of the namespace where the original lives. This label is the passport of the copy. It tells people and tools that the object is inherited, and it tells the controller that this object is under its management.

Why copies are read-only

The controller’s webhooks refuse changes to inherited copies made by ordinary users. If anyone could edit a copy, the next sync would overwrite their change, or worse, the child would drift from the parent without anyone noticing. To change a copy, you change the original in the ancestor namespace. This is a strong guarantee. It means that what a child namespace receives from above is exactly what the owner above intended.

How a copy is kept up to date

The controller watches both the original and the copies. If the original changes, copies are updated. If a copy is somehow deleted or altered by an administrator who bypasses the webhook, the controller restores it. If the original is deleted, all the copies are removed. This reconciling loop is the same pattern that all Kubernetes controllers use, and it is why the system recovers from small accidents without human help.

Consequences you should know

Besides copying objects, the controller stamps every namespace with labels that describe where it sits in the tree.

Many Kubernetes features select namespaces by label. A NetworkPolicy, for example, can say “allow traffic from namespaces that carry this label”. Core Kubernetes knows nothing about trees, so a plain policy cannot say “allow everything from the finance department and all its sub-teams”. The controller fills this gap by adding labels to each namespace that name its ancestors.

What the tree labels look like

For every ancestor of a namespace, including the namespace itself, the controller adds a label whose key includes the ancestor’s name followed by the suffix .tree.hnc.x-k8s.io/depth. The value is a number. Zero means the namespace itself, one means a child of that ancestor, two means a grandchild, and so on. A policy can then select every namespace that carries the label for the finance department, regardless of how deep the namespace sits.

flowchart TD
  F["finance (depth 0 label on itself)"] --> P["payroll (finance depth 1)"]
  F --> A["audit (finance depth 1)"]
  P --> PD["payroll-dev (finance depth 2, payroll depth 1)"]
  P --> PP["payroll-prod (finance depth 2, payroll depth 1)"]
        

In the figure, a policy that selects the finance label matches finance itself, payroll, audit and both payroll environments. A policy that selects the payroll label matches payroll and its two environments only. The same idea works for any feature that selects namespaces by label.

Why this is valuable for network rules

A common requirement is that workloads inside one department may talk to each other, but not to other departments. Without tree labels, you list each namespace by name and update the list whenever a team adds a namespace. With tree labels, you write one rule per department. New namespaces join the department simply by being created under it.

Some settings live on the namespace object itself. The controller can be told to hand selected ones down to new subnamespaces.

Namespaces carry labels and annotations of their own. Many cluster tools depend on them. A security feature might read a label that sets how strict the Pod rules are. A cost tool might read a label that names the team that pays. A service mesh might read a label that turns on automatic sidecars. If subnamespaces do not carry the same labels as their parent, those tools treat them differently, often by accident.

What the controller can do

Depending on version and startup settings, the controller can copy chosen labels and annotations from a parent namespace to its children, so that a team’s namespaces share the same cost label or security level. Which keys are allowed to propagate is a setting for the administrator, because blindly copying everything would be unsafe. Features in this area have changed across releases, so confirm what your version supports before depending on it.

Why it matters in practice

If your version does not support label propagation, you can reach a similar result with a policy engine that adds labels at creation time, or with automation that runs when a subnamespace appears. The key point is to decide on purpose how children get their labels, rather than leaving it to chance.

Here we follow what the controller does, step by step, when a single object changes in a parent.

A reconciler is a piece of code that compares what should exist with what does exist and fixes the difference. The controller has several reconcilers. One looks after hierarchy objects and keeps the forest up to date. Another looks after anchors. Others look after each propagated type. They run whenever the API server tells them that something has changed.

sequenceDiagram
  participant U as User
  participant API as API server
  participant W as Webhook
  participant R as Reconciler
  participant F as Forest
  U->>API: Change a RoleBinding in the parent
  API->>W: Validate the change
  W->>F: Check hierarchy rules
  F-->>W: Allowed
  W-->>API: Accept
  API->>R: Notify of the change
  R->>F: Find all descendants
  F-->>R: List of children
  R->>API: Create or update copies in each child
        

The steps in words

Why the loop is forgiving

Because the reconciler compares the whole desired state to the whole actual state, it does not matter if it missed an event or crashed in the middle. After a restart it simply walks the corridors again. This idea, called level-based reconciliation, is what makes Kubernetes controllers resilient. It also means the controller can be slow for large trees, which we will discuss later.

When something cannot be done safely, the controller refuses and tells you why, using conditions on the namespace.

A hierarchy can go wrong in several ways. Two people can try to give a namespace different parents at the same time. Someone can set a parent that does not exist yet. Someone can create a loop where A is a child of B and B is a child of A. Someone can try to copy an object into a child that already has a different object of the same name. The controller meets each of these with a clear rule.

Halting is a safe choice

When a namespace is in trouble, the controller stops copying objects into and out of it. This is called halting. It may feel annoying, because teams stop receiving updates. It is much safer than guessing, because a wrong guess might give access to the wrong people. Once the problem is fixed, the condition clears and normal flow resumes.

Deleting a branch of the tree can remove a lot of work. The controller therefore adds guard rails.

In core Kubernetes, deleting a namespace deletes everything inside it. In a hierarchy, a parent may have many children, each full of applications. A careless deletion of the parent could, if cascading were automatic, remove the whole branch in seconds. The controller treats this very carefully.

Subnamespaces and their anchors

A subnamespace is owned by its anchor in the parent. If you delete the anchor, the controller deletes the subnamespace, but only when the subnamespace has no subnamespaces of its own, or when cascading deletion is allowed. This is a deliberate speed bump. It makes you stop and think when the deletion would affect several levels.

The cascading permission

The HierarchyConfiguration of a namespace has a setting, allowCascadingDeletion, which defaults to off. When it is off for a parent, the controller refuses to delete the parent’s subnamespace children by removing their anchors in a chain. When it is on, deletion may sweep downward through the whole subtree. The setting may be placed on a namespace or on its ancestors, and it lets the owner decide how much freedom to give.

Remember too that deleting copied objects does nothing useful. The controller recreates them. To remove an inherited object you must delete the original in its owning namespace or change the settings that make it travel.

The point of subnamespaces is to let teams act on their own. This chapter shows the exact line between the platform team and the tenants.

Delegation means handing part of a job to someone else together with the right to do it. In this system, the platform team prepares a team’s top namespace and gives the team permission to create anchors inside it. After that, the team can create, name and use subnamespaces without asking anyone, and the platform team does not need cluster-wide privileges for the work.

Three layers of permission

Where the guard rails are

The webhook checks that a person who sets a parent has the right to do so on both sides. Moving a namespace under a new parent needs authority over both the namespace and the new parent. This stops a person from attaching their namespace beneath someone else’s tree to inherit that tree’s permissions. Without this check, hierarchy would become a way to steal access.

People often expect a parent to share a budget of CPU and memory with its children. The truth is more careful.

A ResourceQuota in Kubernetes caps how much a single namespace may use: total CPU, memory, storage or number of objects. In a hierarchy the natural wish is to place one quota on a department and let the children share it. The project explored this idea in an early experimental version, but it is not part of the current stable features. Check the documentation of your release before planning around it.

What you can do today

You can propagate a ResourceQuota object downward, but each copy is its own separate limit. If a department has ten children and the quota says ten CPUs, the department can actually use a hundred CPUs. That is rarely what anyone wants. A better approach is to place a quota on each child by a different mechanism, such as an automation tool or policy engine that sets the right numbers at creation time, or a more advanced multi-tenant system that manages shared budgets.

Knowing the limits is as useful as knowing the features. These are the common misunderstandings.

The controller is a small, focused tool. It adds a tree to namespaces and copies chosen objects. It is not a complete multi-tenancy platform. Many wrong plans come from expecting it to do things that belong to other tools.

This is why serious multi-tenant clusters combine the controller with network policies, Pod security settings, admission policies, quotas and sometimes dedicated nodes. The controller removes the repetition from these tools. It does not replace them.

Let us follow a made-up company called Northwind, which has one shared cluster and four product teams.

Northwind’s platform team runs the cluster. Four product teams, called checkout, search, payments and profile, each need several namespaces: a development one, a testing one and a production one. Before the controller, the platform team created twelve namespaces by hand, then copied the same access rules into each, then answered a steady stream of requests such as “please add a namespace for my experiment”.

The new design

The platform team creates one full namespace for each team, such as team-checkout. They bind the team’s group to a Role in that namespace that allows creating anchors and managing ordinary workloads. Then they step back. The checkout team creates subnamespaces called checkout-dev, checkout-test and checkout-prod by themselves. The access rules flow down at once. Network rules flow down too, because the platform team listed NetworkPolicy in HNCConfiguration.

flowchart TD
  NW["northwind-root (platform team)"] --> TC["team-checkout"]
  NW --> TS["team-search"]
  NW --> TP["team-payments"]
  NW --> TR["team-profile"]
  TC --> CD["checkout-dev"]
  TC --> CT["checkout-test"]
  TC --> CP["checkout-prod"]
  TP --> PD["payments-dev"]
  TP --> PP["payments-prod"]
        

What changed for people

Two chores that every new namespace needs, solved once at the top of the tree.

Every new namespace at Northwind needs two things before an application can run properly. First, a credential for the private image registry, because Pods cannot pull company images without it. Second, a default-deny network rule, which blocks all traffic by default so teams must add explicit allowances. Without hierarchy, both items were forgotten about as often as they were remembered.

How the platform team handles the credential

The platform team places one credential object in a platform namespace. They mark the type as one that propagates in HNCConfiguration, and they add a note so that the credential reaches only the product team branches, not other special namespaces. Each subnamespace receives a copy automatically. When the registry password rotates, the platform team replaces the one original and every copy updates within moments.

How the default-deny rule is handled

The default-deny NetworkPolicy is placed in each team’s top namespace. It propagates to every child. Teams then add their own allow-rules in their own namespaces to open the connections they need. Because the inherited rule cannot be edited by tenants, no team can remove the safety net by mistake.

Many teams keep cluster settings in a version-controlled repository. Inherited copies need a little care in that world.

GitOps means that a repository is the source of truth, and a tool in the cluster keeps the cluster equal to the repository. Such tools often have a pruning feature that deletes anything in the cluster that is not described in the repository. Inherited copies are created by the controller, not by the repository, so a pruning tool may see them as strangers and try to delete them. The controller then recreates them, and the two tools fight in a loop.

How to avoid the fight

Most GitOps tools allow you to exclude objects by label. Because every inherited copy carries the inherited-from label, you can tell the tool to ignore objects that have it. Another safe habit is to keep the originals in the repository and let the controller own all copies. Teams should never place the same object by hand into a child namespace when the parent already sends it.

flowchart LR
  G["Git repository"] --> S["GitOps tool"]
  S --> P["Original objects in parent namespaces"]
  P --> H["Hierarchical namespace controller"]
  H --> C["Inherited copies in children"]
  S -. "ignore objects labeled inherited-from" .-> C
        

Policy engines

A policy engine, also called an admission controller, checks new objects against rules, for example “every Pod must have a team label”. The controller creates copies by writing to the API server like any other client, so the engine’s rules apply to those copies too. If your rules reject something the controller creates, you will see a condition about a failed copy. Make sure your policies allow what the controller needs, or exempt the controller’s service account where that is safe.

The controller does work in proportion to the size of your trees and the number of objects that propagate.

Every change to a propagated object means copies in every descendant. A Role copied into ten children is ten writes. A Secret that changes every hour and travels to five hundred namespaces is five hundred writes every hour. Those writes go through the API server, are stored in etcd, and are watched by many other components. At small scale this is invisible. At large scale it can matter.

The factors that grow cost

Keeping it healthy

Keep propagated objects small and slow-changing. Avoid very deep trees; two to four levels are common and easier to reason about. Watch the controller’s CPU, memory and queue length, and the API server’s request rates. If you grow to thousands of namespaces, test in a staging cluster with similar numbers before going live, and read the project’s notes on tested limits for your release.

A good operator can tell in a minute whether the hierarchy is healthy. Four sources of signals make that possible.

Observability means being able to understand what a system is doing from the outside. For this controller there are four natural places to look. Each answers a different question.

What to watch for first

What do you need to save, and what happens if the controller disappears for an afternoon?

The controller holds no data of its own. The forest in its memory is rebuilt from the API server each time it starts. The real information lives in Kubernetes objects: the hierarchy settings, the anchors, the configuration and the originals. If you back up those objects as part of your normal cluster backup, you can rebuild the whole hierarchy.

What happens during an outage

If the controller is down, existing copies stay in place and keep working, because they are ordinary objects. Applications are not affected. New changes in parents do not reach children, and new anchors are not turned into namespaces until it returns. If the webhook is configured to fail closed, hierarchy changes may be refused during the outage. Choose that setting knowing the trade-off between safety and availability.

Upgrade habits

Read the release notes before each upgrade, especially for changes to the custom resource definitions and to configuration names. Upgrade in a test cluster first. Take a backup. After the upgrade, check that conditions stay clear and that a test change in a parent reaches a test child.

A tool that copies permissions across namespaces deserves a careful security review.

The controller itself needs broad rights. To copy Roles and Secrets it must be able to read and write them across the cluster. Anyone who takes control of the controller could, in theory, create access in any namespace. Treat its service account, its Pod and its images as high-value assets.

Main risks and answers

Remember too that hierarchy is a convenience for permissions, not a wall. Strong isolation needs network policies, Pod security rules and, for the strictest needs, separate clusters.

When something looks wrong, a calm order of questions finds the cause faster than guessing.

Start with the tree, then conditions, then the controller, then the object. This order moves from the widest view to the narrowest and avoids chasing small details before checking the big picture.

These are patterns that work, and mistakes that appear again and again.

Patterns that work

Anti-patterns

No tool is right for every cluster. Here is an honest comparison.

Alternatives to consider

Introduce the controller slowly. Each step is small, safe and easy to undo.

The pattern fits several kinds of organizations, each for a slightly different reason.

A tree is easy to build and hard to rearrange. A little thought about names and levels at the start saves months of cleaning later.

Namespace names must be unique across the whole cluster. Position in the tree does not give a name its own private space. Two teams cannot both have a namespace called dev, even if they sit in different branches. The simplest way out is to put the team or product name inside the namespace name, so that checkout-dev and search-dev can live side by side.

Rules of thumb for names

Choosing the levels

Each level in the tree should answer one question. A common three-level design asks: which organization, which team, which environment. A level that does not answer a clear question is probably unnecessary. Before you add a level, ask what rule or permission will be attached to it. If you cannot name one, leave the level out.

Let us follow one subnamespace from its birth to its removal and watch what the controller does at each step.

stateDiagram-v2
  [*] --> Requested: anchor created
  Requested --> Created: namespace made by controller
  Created --> Configured: inherited objects and labels added
  Configured --> InUse: team deploys workloads
  InUse --> InUse: parent changes flow in
  InUse --> Removing: anchor deleted
  Removing --> [*]: namespace removed
        

What is worth noticing is how few people were involved. The developer acted on her own. The platform team acted once, at the top, for the credential change. Nobody with cluster-wide rights was needed for any step in her day.

A setup that works on the first day can silently break on the hundredth. Regular checks keep it honest.

Testing a tree means checking that the right things travel to the right places, and that the wrong things do not. It is useful to test the positive case, where an object should arrive, and the negative case, where it should not. Negative tests find most of the dangerous mistakes, since they show leaks of access.

A short list of checks

Make the checks routine

Run the same list after every upgrade of the controller, after every change to HNCConfiguration, and on a regular schedule such as once a week from an automated job. Keep the results somewhere the whole team can read. A test that fails loudly the day after a change is far cheaper than a leak found during an audit.

Keep this page nearby while you read other material about the controller. Every term is explained in everyday language.

If any of these words still feels unclear, return to the chapter that introduces it. Each chapter explains one idea with a story, so that the meaning stays in your memory.

Short answers to questions that newcomers ask most often.

A tree of namespaces turns repeated manual work into a rule you write once.

We began with a flat list of namespaces and the headaches it creates: copied permissions, forgotten rules, endless requests. We then saw how the controller adds parents and children, lets teams create subnamespaces with anchors, and copies chosen objects downward while keeping them read-only. We looked at the controller’s inner workings, its conditions and its safety limits, then at real examples, risks and a careful path to adoption.