Installing Hierarchy Controller

This document shows how to install and uninstall Hierarchy Controller, which extends regular Kubernetes namespaces to allow for hierarchical policies and creation without modifying the Config Sync repository.

Before you begin

You need a cluster running Google Kubernetes Engine (GKE) version 1.15.x or later with Config Sync already installed.

Enabling Hierarchy Controller

Follow these steps to configure Config Sync to enable Hierarchy Controller on the cluster:

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

      # config-management.yaml
      kind: ConfigManagement
        name: config-management
        # Set to true to enable hierarchical namespaces
          enabled: true
        # ...other fields...
  2. 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.

Installing 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 the following sections.

Determining the required version of the plugin

Each release of Config Sync corresponds to a release of the OSS project, as shown in the following table. For best results, ensure that the version of the plugin that you download matches the version of Config Sync.

Config Sync version kubectl-hns version Notes
1.6.0 0.6.0
1.5.2 0.6.0 kubectl-hns v0.6.0 is not compatible with Config Sync 1.5.1 or earlier
1.5.1 0.5.3 kubectl-hns v0.5.3 and earlier are not compatible with Config Sync 1.5.2 or later
1.5.0 0.5.2
1.4.2 0.5.1
1.4.1 0.5.0
Pre-1.4.0 n/a

Installing the plugin on your workstation

  1. Set an environment variable to the kubectl-hns version shown in the previous table. For example:

     HNC_VERSION=v0.5.0   # Example for Config Sync 1.4.1
  2. Select the location to install the plugin. It can be anywhere in your PATH.

     PLUGIN_DIR=~/kubectl-plugins   # Example path
  3. Download the plugin and make it executable.


    Since Config Sync 1.5.0 / HNC v0.5.2:

    curl -L -o ${PLUGIN_DIR}/kubectl-hns \${HNC_VERSION}/kubectl-hns_linux_amd64
    chmod +x ${PLUGIN_DIR}/kubectl-hns

    In Config Sync 1.4.2 / HNC v0.5.1 and earlier:

    curl -L -o ${PLUGIN_DIR}/kubectl-hns \${HNC_VERSION}/kubectl-hns
    chmod +x ${PLUGIN_DIR}/kubectl-hns


    macOS is only available for Config Sync 1.5.0 / HNC v0.5.2 and later.

    curl -L -o ${PLUGIN_DIR}/kubectl-hns \${HNC_VERSION}/kubectl-hns_darwin_amd64
    chmod +x ${PLUGIN_DIR}/kubectl-hns

Verifying the installation

  1. If Hierarchy Controller is installed correctly, you should be able to create subnamespaces underneath an existing namespace, as follows:

     kubectl hns create sub -n default
  2. If Hierarchy Controller is working correctly, you should be able to inspect the resulting hierarchy:

     kubectl hns tree default


      └── sub
  3. Clean up the subnamespace. Subnamespaces cannot be deleted directly; instead, you must delete the subnamespace anchor from the parent namespace:

    kubectl delete subns sub -n default
    # "sub" deleted

Uninstalling Hierarchy Controller

To uninstall Hierarchy Controller:

  1. In the configuration file for the Operator, in the spec.hierarchyController object, set the value of enabled to false.
  2. After the Operator removes the finalizer, the Hierarchy Controller is uninstalled.

If you want to fully uninstall Config Sync, see Uninstalling the Operator from a cluster.

What's next