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:
In the configuration file for the Operator, in the
spec.hierarchyController
object, set the value ofenabled
totrue
:# 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...
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
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
Select the location to install the plugin. It can be anywhere in your PATH.
PLUGIN_DIR=~/kubectl-plugins # Example path
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
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
If Hierarchy Controller is working correctly, you should be able to inspect the resulting hierarchy:
kubectl hns tree default
Output:
default └── sub
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:
- In the configuration file for the Operator, in the
spec.hierarchyController
object, set the value ofenabled
tofalse
. After the Operator removes the
hierarchycontroller.configmanagement.gke.io
finalizer, the Hierarchy Controller is uninstalled.
If you want to fully uninstall Config Sync, see Uninstalling the Operator from a cluster.
What's next
Learn more about common tasks that you might want to use HNC to accomplish in the HNC User Guide: How-to.