Install Hierarchy 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 Policy Controller, Config Sync and Config Controller to install Hierarchy Controller.

gcloud

Follow these steps to configure Policy Controller, Config Sync and Config Controller 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 Policy Controller, Config Sync and Config Controller to install Hierarchy Controller, including all optional components. If you do not want to enable hierarchical observability or hierarchical resource quotas, comment on 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 hierarhical 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 Policy Controller, Config Sync and Config Controller. To learn more, see Upgrade Policy Controller, Config Sync and Config Controller.

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.

kubectl

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

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

What's next