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 the Config Sync Operator already installed. Hierarchy Controller does not require that you grant the Operator access to Git or otherwise configure the Operator, except as described in the following section.

Enabling Hierarchy Controller

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

  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
    
        # ...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.

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.2 0.7.0 This version of the plugin might be available from Krew.
1.6.1 0.7.0 This version of the plugin might be available from Krew.
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

The latest version of the plugin is typically supported by Krew. If you are using Krew, you may be able to install the plugin via the command:

kubectl krew install hns

Otherwise, you can manually install the plugin using the following steps:

  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.

    Linux

    Since Config Sync 1.5.0 / HNC v0.5.2:

    curl -L -o ${PLUGIN_DIR}/kubectl-hns \
       https://github.com/kubernetes-sigs/multi-tenancy/releases/download/hnc-${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 \
       https://github.com/kubernetes-sigs/multi-tenancy/releases/download/hnc-${HNC_VERSION}/kubectl-hns
    chmod +x ${PLUGIN_DIR}/kubectl-hns
    

    macOS

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

    curl -L -o ${PLUGIN_DIR}/kubectl-hns \
       https://github.com/kubernetes-sigs/multi-tenancy/releases/download/hnc-${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
    

    Output:

     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
    # subnamespaceanchor.hnc.x-k8s.io "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. There is no need to modify any other fields, such as enablePodTreeLabels.
  2. After the Operator removes the hierarchycontroller.configmanagement.gke.io finalizer, Hierarchy Controller is uninstalled.

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 Uninstalling the Operator from a cluster.

What's next