Hierarchy Controller overview

This document describes Hierarchy Controller, a Kubernetes controller and dynamic admission controller that adds hierarchies to Kubernetes namespaces.

Hierarchical namespaces

Hierarchy Controller introduces the concept of hierarchical namespaces, which are extensions to Kubernetes namespaces that make it easy to manage groups of namespaces that share a common concept of ownership. They are especially useful in clusters that are shared by multiple teams, but the owners do not need to be people. For example, you might want to make an Operator an owner of a set of namespaces.

To support multi-tenant use cases, hierarchical namespaces have two key behaviors in addition to regular Kubernetes namespaces:

  • Delegated namespace creation. Hierarchy Controller introduces the concept of a subnamespace, which can be created by users under an existing namespace even if that user does not have cluster-level namespace privileges.

    For example, you can define a namespace for a team in Config Sync in a Git repository, but then delegate subnamespace creation to the team. This lets them create their own subnamespaces underneath the team-level namespace that you defined for them, without making any modifications in Git.

  • Policy enforcement. Just as Config Sync can propagate policy objects from abstract namespace directories to Kubernetes namespaces, Hierarchy Controller can further propagate these objects to subnamespaces. For example, doing this ensures that the policies that are applied to a team's root namespace are also applied to their subnamespaces.

    However, there are some differences between how Hierarchy Controller and Config Sync propagate policies. Config Sync copies all objects in abstract namespace directories to their descendant Kubernetes namespaces. By contrast, Hierarchy Controller copies only RBAC roles and role bindings by default, although it can be configured to propagate any other type of Kubernetes object.

Hierarchy Controller is integrated into Config Sync version 1.4.1 and later. Hierarchy Controller is based on the Hierarchical Namespace Controller (HNC), an open source project.

Hierarchical namespaces versus abstract namespaces

The hierarchical namespaces provided by Hierarchy Controller are similar to Config Sync abstract namespaces. However, while abstract namespaces only exist in the Config Sync repository, hierarchical namespaces are all Kubernetes namespaces and exist on the cluster.

To avoid contention between Config Sync abstract namespaces and Hierarchy Controller namespaces, ensure that no non-root hierarchical namespace is created as an abstract or leaf namespace in the Config Sync repository.

Alternatively, you can use an unstructured repository to disable Config Sync abstract namespaces, and rely solely on Hierarchy Controller to define hierarchies and propagate policies. This can be useful if you are unable to use the default repository directory structure but still want to take advantage of hierarchical features.

To use unstructured repositories, check in either subnamespaces or full namespaces. We recommend using full namespaces because you can update their hierarchical relationships by modifying the HierarchicalConfiguration object (which you must also check in). By contrast, if you do check in subnamespaces, ensure that you check in both the namespaces and the SubnamespaceAnchor objects in their parents, but be aware that they are not designed to be easily modified after creation.

In both cases, ensure that you configure Hierarchy Controller to apply all desired Kubernetes object types across hierarchies. By default, only RBAC roles and role bindings are applied.

What's next