Installing Hierarchy Controller

Beta

This product is covered by the Pre-GA Offerings Terms of the Google Cloud Platform Terms of Service. Pre-GA products may have limited support, and changes to pre-GA products may not be compatible with other pre-GA versions. For more information, see the launch stage descriptions.

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.

Important: We recommend installing Hierarchy Controller on clusters with GKE version 1.15.x or later installed. Hierarchy Controller is not supported on GKE version 1.14.x and earlier. Hierarchy Controller is unable to stop authorized users from directly deleting a subnamespace, even when the allowCascadingDelete option (described later) is unset.

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

   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
   

   Important: For this to work, you must have permission to create SubnamespaceAnchor objects in the default namespace.

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.

   Warning: Uninstalling Hierarchy Controller also removes all hierarchical relationships between the namespaces on your cluster, but does not delete the namespaces themselves or any of the objects that were propagated from ancestor namespaces to their descendants. Reinstalling Hierarchy Controller results in all propagated objects being deleted, but does not re-establish the hierarchical relationships between namespaces.

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

What's next

• Observe hierarchical workloads.

• Learn more about common tasks that you might want to use HNC to accomplish in the HNC User Guide: How-to.