kubernetes-retired/multi-tenancy hnc-v0.6.0

HNC v0.6.0

on GitHub

HNC v0.6.0 introduces the new v1alpha2 API that is more standards-compliant than the prior API. It also includes an alpha-level preview of exceptions and a variety of smaller fixes. See the changelog for more details.

Installing on a cluster without HNC

If you do not have HNC v0.5 installed on your cluster, you can install HNC v0.6 by running the following commands:

HNC_VERSION=v0.6.0
kubectl apply -f https://github.com/kubernetes-sigs/multi-tenancy/releases/download/hnc-${HNC_VERSION}/hnc-manager.yaml
# Wait 30s if HNC has never been installed before for it to generate certs and reboot itself.

Otherwise, see below for upgrade instructions.

To install the kubectl plugin on your workstation, switch to any directory in your PATH (e.g. ~/bin) and run the following commands:

HNC_VERSION=v0.6.0
HNC_PLATFORM=linux_amd64 # also supported: darwin_amd64
curl -L https://github.com/kubernetes-sigs/multi-tenancy/releases/download/hnc-${HNC_VERSION}/kubectl-hns_${HNC_PLATFORM} -o ./kubectl-hns
chmod +x ./kubectl-hns

# Ensure the plugin is working
kubectl hns
# The help text should be displayed

NB: As of December 14th 2020, you can no longer install the v0.6.0 version of the plugin via Krew; Krew now serves a newer version, which may not be compatible with HNC v0.6.0.

For more instructions, see the user guide.

Upgrading from HNC v0.5.x

If you do have HNC v0.5 installed on your cluster, be aware that installing HNC v0.6 will automatically and immediately update all your HNC objects (HierarchyConfiguration, HNCConfiguration and SubnamespaceAnchor) from v1alpha1 to v1alpha2. We have tested this process extensively but there is always the possibility that some bugs have slipped through and that you could lose data while upgrading from v0.5 to v0.6.

Once you have upgraded to HNC v0.6, you cannot automatically revert to HNC v0.5. To minimize or eliminate the chance of data loss, follow these steps:

1. Ensure you have the latest version of HNC v0.5 installed before attempting to upgrade (v0.5.3)
2. Ensure you don't have any objects with the hnc.x-k8s.io/inheritedFrom label, unless those objects have the propagate sync mode. That is, ensure you didn't change any type configs from propagate to ignore without cleaning up, because after HNC is upgraded, it will no longer respected the inheritedFrom label and will not be able to clean up these objects.
3. Use kubectl hns config describe and ensure that there are no conditions in your cluster, and that all configs are healthy.
4. Back up all existing HNC objects and manually confirm that all namespaces are accounted for.
5. For the rest of this process, do not delete any object types that are propagated by HNC, and do not change the contents of any HNC objects. For example, do not delete any RBAC Roles or RoleBindings until you've confirmed that HNC v0.6 is in a good state.
6. Install HNC v0.6 as described in the prior section, "Installing on a cluster without HNC." That is, first apply the manifest to your cluster, and then upgrade the kubectl-hns plugin on your workstation. Wait at least 30s for HNC to finish upgrading all v1alpha1 objects; once you can call kubectl hns tree -A and see your full hierarchy, you should be in good shape (during the upgrade process, the tree command may simply list namespaces without showing the hierarchical relationships).
7. Run kubectl hns config describe to ensure that your cluster-wide configuration looks correct and there are no other problems across your cluster. The new API uses plural resource names instead of singular kind names (e.g. secrets and networkpolicies instead of Secret and NetworkPolicy), and HNC v0.6 uses a simple pluralization algorithm on your existing cluster-wide config (e.g. replace trailing "y" with "ies," otherwise append an "s"). If this is incorrect, you can simply fix the HNC config after the upgrade is finished.

If you do encounter problems, please contact us on Slack and we'll help you out. For more information about how v1alpha2 has changed, see the design doc.

To downgrade to HNC v0.5, you must completely uninstall HNC, including the CRDs. You may then reinstall HNC v0.5.x and reapply the configs you saved earlier.

Known issues

These issues are being (or have been) fixed in a future release of HNC, but are considered to be sufficiently rare or low-impact that we are not currently planning on backporting them to HNC v0.5. Please contact aludwin@google.com if you are affected by these changes and require a backport.

• When uninstalling HNC CRDs, subnamespaces could sometimes be erased by mistake. This is fixed in v0.7.0 (#1285)

Changelog

Since HNC v0.5

• The new v1alpha2 API is introduced with the following major changes from v1alpha1 (see full list):
  • Namespace conditions are now reported using the standard Kubernetes conditions schema.
  • Object "conditions" have been converted to Kubernetes Events and are no longer reported in the HierarchyConfiguration objects (though they are reported by kubectl hns describe NAMESPACE.
  • When configuring object propagation, instead of providing the group, version and kind (e.g. "networking.k8s.io/v1/NetworkPolicy"), you now provide the group and resource (e.g. "networking.k8s.io/networkpolicies"), similar to RBAC.
  • Enum values are now properly capitalized (e.g. Propagate, not propagate)
  • Annotations and labels are now properly hyphenated (e.g. inherited-from, not inheritedFrom)
• If you start propagating a new type (such as Secret), we now warn you that existing objects could be overridden and provide ways to ensure this doesn't happen (#1076)
• If a RoleBinding is quickly deleted and recreated with a new Role, HNC will no longer fail to update it (#798)

Full list of changes

Testing signoff