Install Hierarchy Controller

Beta

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

Caution: As of December, 2024 you can no longer install Hierarchy Controller. Config Sync will be blocked from upgrades if Hierarchy Controller is configured as a configmanagement fleet feature or through the ConfigManagement API. To migrate to Hierarchical Namespace Controller (HNC), which Hierarchy Controller is based on and offers similar functionality, see Migrate from Hierarchy Controller to Hierarchical Namespace Controller.

Hierarchy Controller lets you organize Kubernetes namespaces into hierarchies, apply policies to them (such as RBAC and hierarchical resource quotas), and observe workloads from related namespaces.

This page shows you how to install, configure, and uninstall Hierarchy Controller.

Before you begin

Before you start, make sure you have performed the following tasks:

• Install and initialize the Google Cloud CLI, which provides the gcloud and kubectl commands used in these instructions. If you use Cloud Shell, Google Cloud CLI comes pre-installed.

• Have a cluster running a Kubernetes version of 1.16.x or later.

Hierarchy Controller is designed to work closely with Config Sync to let you manage your hierarchical namespaces and policies through a Git repository. If you choose to do this, we recommend that you select an unstructured repository when you install Config Sync, which lets you organize your repository in the way that you want while retaining the benefits of hierarchical policies. By contrast, a hierarchical repository can conflict with Hierarchy Controller; using the two together is not recommended.

Alternatively, you can choose to install Hierarchy Controller without configuring a Config Sync repository; hierarchical namespaces can be defined entirely on the cluster through the Kubernetes API. If you are not planning on using Git, you do not need to grant the Operator access to Git or configure it in any way except as described in the following section.

Enable Hierarchy Controller

Follow these steps to configure Config Sync to install Hierarchy Controller.

Note: Hierarchy Controller is not supported on Autopilot clusters.

gcloud

Note: The file format for the gcloud CLI apply command changed for version 1.8.0. Please make sure you update your gcloud CLI to the latest version.

Follow these steps to configure Config Sync to install Hierarchy Controller, including all optional components. If you do not want to enable hierarchical observability or hierarchical resource quotas, comment out the indicated lines.

1. (Optional) If you are using private clusters, add firewall rules to the projects of each cluster to allow the GKE cluster control planes to connect to the Hierarchy Controller webhooks on port 9443:

    gcloud compute firewall-rules create allow-cluster-control-plane-tcp-9443 \
      --allow tcp:9443 \
      --network default \
      --source-ranges CONTROL_PLANE_CIDR \
      --target-tags NODE_TAG
   

   Replace the following:

   • CONTROL_PLANE_CIDR: The IP range for your GKE cluster control plane. For example, 172.16.0.16/28.
   • NODE_TAG: A tag applied to all the nodes in your GKE cluster.

2. Set the following values in the spec.hierarchyController object to true in the gcloud configuration file:

   # apply-spec.yaml
   
   applySpecVersion: 1
   spec:
     hierarchyController:
       # Set to true to enable hierarchical namespaces
       enabled: true
       # Comment to disable hierarchical quota:
       enableHierarchicalResourceQuota: true
       # Comment to disable hierarchical observability:
       enablePodTreeLabels: true
     # ...other fields...
   

3. Apply the apply-spec.yaml file:

    gcloud beta container fleet config-management apply \
        --membership=CLUSTER_NAME \
        --config=CONFIG_YAML \
        --project=PROJECT_ID
   

   Replace the following:

   • CLUSTER_NAME: add the registered cluster that you want to apply this configuration to.
   • CONFIG_YAML: add the path to your apply-spec.yaml file.
   • PROJECT_ID: add your project ID.

   Several workloads are deployed, and then Hierarchy Controller becomes usable on your cluster. This can take up to a minute to complete.

kubectl

Follow these steps to configure Config Sync to install Hierarchy Controller, including all optional components. If you do not want to enable hierarchical observability or hierarchical resource quotas, comment out the indicated lines.

1. (Optional) If you are using private clusters, add firewall rules to the projects of each cluster to allow the GKE cluster control planes to connect to the Hierarchy Controller webhooks on port 9443:

    gcloud compute firewall-rules create allow-cluster-control-plane-tcp-9443 \
      --allow tcp:9443 \
      --network default \
      --source-ranges CONTROL_PLANE_CIDR \
      --target-tags NODE_TAG
   

   Replace the following:

   • CONTROL_PLANE_CIDR: The IP range for your GKE cluster control plane. For example, 172.16.0.16/28.
   • NODE_TAG: A tag applied to all the nodes in your GKE cluster.

2. In the configuration file for the Operator, in the spec.hierarchyController object, set the value of enabled to true:

   # config-management.yaml
   
   apiVersion: configmanagement.gke.io/v1
   kind: ConfigManagement
   metadata:
     name: config-management
   spec:
     # Set to true to enable hierarchical namespaces
     hierarchyController:
       enabled: true
       # Comment to disable hierarchical quota:
       enableHierarchicalResourceQuota: true
       # Comment to disable hierarchical observability:
       enablePodTreeLabels: true
      # ...other fields...
   

3. Apply the configuration:

     kubectl apply -f config-management.yaml
   

   Several workloads are deployed, and then Hierarchy Controller becomes usable on your cluster. This can take up to a minute to complete.

Install the kubectl plugin

It is possible to interact with Hierarchy Controller purely through Kubernetes client tools such as kubectl. However, the open source kubectl-hns kubectl plugin greatly simplifies several tasks. This plugin is part of the Hierarchical Namespace Controller (HNC), which is a component of Hierarchy Controller.

This plugin is distributed by the OSS community, and is currently available for Linux and macOS. To install it on your workstation, see Install the kubectl plugin in the Config Sync documentation.

Verify the installation

After you have installed Hierarchy Controller, you can verify that the installation completed successfully.

gcloud

Run the following command:

gcloud beta container fleet config-management status \
    --project=PROJECT_ID

Replace PROJECT_ID with your project's ID.

You should see output similar to the following example:

Name          ...other columns... Hierarchy_Controller
CLUSTER_NAME  ...other fields ... INSTALLED

A successful installation has a status of INSTALLED in the Hierarchy_Controller column. It might take several minutes for the status to appear after you enable Hierarchy Controller.

kubectl

If Hierarchy Controller is installed correctly, its Pods will be running. The Pods might restart several times before they're available.

Since the Hierarchy Controller Pods run in the hnc-system namespace, you can view their status by running following command:

kubectl get pods -n hnc-system

You should see output similar to the following example:

NAME                                         READY   STATUS    RESTARTS   AGE
gke-hc-controller-manager-6f4dbb484d-t8tdm   2/2     Running   1          1m
hnc-controller-manager-7b75655894-tzqvx      2/2     Running   1          1m

Upgrade Hierarchy Controller

Hierarchy Controller is upgraded whenever you upgrade Config Sync. To learn more, see Upgrade Config Sync.

Uninstall Hierarchy Controller

Follow these steps to uninstall Hierarchy Controller from your clusters.

gcloud

To uninstall the Hierarchy Controller:

1. Edit the Hierarchy Controller configuration in your apply-spec.yaml file and set hierarchyController.enabled to false.

2. Apply the changes in the apply-spec.yaml file:

    gcloud beta container fleet config-management apply \
        --membership=CLUSTER_NAME \
        --config=CONFIG_YAML \
        --project=PROJECT_ID
   

   Replace the following:

   • CLUSTER_NAME: add the registered cluster that you want to apply this configuration to.
   • CONFIG_YAML: add the path to your apply-spec.yaml file.
   • PROJECT_ID: add your project ID.

After Hierarchy Controller removes the hierarchycontroller.configmanagement.gke.io finalizer, uninstallation is complete.

Note: Uninstalling Hierarchy Controller does not remove any namespaces, nor does it remove any of the objects that were propagated from ancestor namespaces to their descendants. However, any further changes to the objects are not propagated.

kubectl

To uninstall Hierarchy Controller, edit the Config Sync configuration in your config-management.yaml file and set hierarchyController.enabled to false. After Config Sync removes the hierarchycontroller.configmanagement.gke.io finalizer, uninstallation is complete.

Note: Uninstalling Hierarchy Controller does not remove any namespaces, nor does it remove any of the objects that were propagated from ancestor namespaces to their descendants. However, any further changes to the objects are not propagated.

If you want to fully uninstall Config Sync, see Uninstall Config Sync from a cluster.

What's next

• Learn more about Hierarchy Controller
• Apply hierarchical resource quotas
• Observe hierarchical workloads
• Explore foundational hierarchical namespaces features
• Explore advanced hierarchical namespaces features