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 Anthos Config Management repository.

Before you begin

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

Enabling Hierarchy Controller

Follow these steps to configure Anthos Config Management 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
    
      apiVersion: configmanagement.gke.io/v1
      kind: ConfigManagement
      metadata:
        name: config-management
      spec:
        # Set to true to enable hierarchical namespaces
        hierarchyController:
          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 Anthos Config Management 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 Anthos Config Management.

Anthos Config Management version kubectl-hns version
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 Anthos Config Management 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 Anthos Config Management 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 Anthos Config Management 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 Anthos Config Management 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.
  2. After the Operator removes the hierarchycontroller.configmanagement.gke.io finalizer, the Hierarchy Controller is uninstalled.

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

What's next