diff --git a/incubator/hnc/docs/user-guide/README.md b/incubator/hnc/docs/user-guide/README.md index e2fb00187..ef10e8618 100644 --- a/incubator/hnc/docs/user-guide/README.md +++ b/incubator/hnc/docs/user-guide/README.md @@ -1,4 +1,4 @@ -# HNC User Guide v0.7 (and v0.6) +# HNC User Guide v0.8 (and v0.7) Authors: aludwin@google.com and other contributors from wg-multitenancy @@ -12,7 +12,7 @@ This guide explains how to use hierarchical namespaces, explains some of the concepts behind them for a more in-depth understanding, and covers some best practices. -**Note: this doc covers HNC v0.7.x and v0.6.x.** For older versions of HNC, +**Note: this doc covers HNC v0.8.x and v0.7.x.** For older versions of HNC, see below. ## Table of contents @@ -25,6 +25,7 @@ see below. ## Older user guides +* [HNC v0.6](https://github.com/kubernetes-sigs/multi-tenancy/tree/hnc-v0.6/incubator/hnc/docs/user-guide) * [HNC v0.5](https://github.com/kubernetes-sigs/multi-tenancy/tree/hnc-v0.5/incubator/hnc/docs/user-guide) * [HNC v0.4](https://github.com/kubernetes-sigs/multi-tenancy/tree/hnc-v0.4/incubator/hnc/docs/user-guide) * [HNC v0.3](https://docs.google.com/document/d/1XVVv1ha4j1WUaszu3mmlACeWPUJXbJhA6zntxswrsco) diff --git a/incubator/hnc/docs/user-guide/concepts.md b/incubator/hnc/docs/user-guide/concepts.md index ce3ead728..56b01a0d8 100644 --- a/incubator/hnc/docs/user-guide/concepts.md +++ b/incubator/hnc/docs/user-guide/concepts.md @@ -318,8 +318,6 @@ application. ### Exceptions and propagation control -***Exceptions are only available in HNC v0.7*** - By default, HNC propagates _all_ objects of a [specified type](how-to.md#admin-resources) from ancestor namespaces to descendant namespaces. However, sometimes this is too restrictive, and you need to create ***exceptions*** to certain policies. For example: @@ -537,18 +535,8 @@ We are considering replacing this with the standard This label should be added to namespaces such as `kube-system` and `kube-public` so that HNC's validating webhook cannot accidentally prevent operations in these -namespaces and block critical cluster operations. - -Before installing HNC, users can customize the excluded namespace list in the HNC -deployment with a container arg called `excluded-namespace` in -`config/manager/manager.yaml` and then set this label on the excluded namespaces. -Setting this label on namespaces that are not -listed in the HNC deployment as an `excluded-namespace` is not allowed. - -As of March 2021, the default excluded namespaces listed in [config/manager/manager.yaml](https://github.com/kubernetes-sigs/multi-tenancy/blob/master/incubator/hnc/config/manager/manager.yaml) -are `kube-system`, `kube-public`, `hnc-system` and -`kube-node-lease`. HNC adds this label to `hnc-system` namespace by default, so -users will have to add this label to other excluded namespaces manually. +namespaces and block critical cluster operations. See [Excluding namespaces from +HNC](how-to.md#admin-excluded-namespaces) for more information. diff --git a/incubator/hnc/docs/user-guide/how-to.md b/incubator/hnc/docs/user-guide/how-to.md index 9c34f533b..7424b4da9 100644 --- a/incubator/hnc/docs/user-guide/how-to.md +++ b/incubator/hnc/docs/user-guide/how-to.md @@ -18,6 +18,7 @@ This document describes common tasks you might want to accomplish using HNC. * [Administer HNC](#admin) * [Install or upgrade HNC on a cluster](#admin-install) * [Uninstall HNC from a cluster](#admin-uninstall) + * [Excluding namespaces from HNC](#admin-excluded-namespaces) * [Backing up and restoring HNC data](#admin-backup-restore) * [Administer who has access to HNC properties](#admin-access) * [Modify the resources propagated by HNC](#admin-resources) @@ -343,8 +344,6 @@ $ kubectl hns set --root ### Limit the propagation of an object to descendant namespaces -***Exceptions are only available in HNC v0.7*** - To limit the propagation of an object, annotate it with an ***exception***. You can use any of the following annotations: @@ -414,6 +413,26 @@ and webhooks) that were only introduced in v1.16. There is no need to uninstall HNC before upgrading it unless specified in the release notes for that version. +#### Prerequisite + +***These prerequisites apply to HNC v0.8 and higher*** + +Prior to installing HNC, add the `hnc.x-k8s.io/excluded-namespaces` label to +your critical system namespaces: + +``` +kubectl label ns kube-system hnc.x-k8s.io/excluded-namespace=true +kubectl label ns kube-public hnc.x-k8s.io/excluded-namespace=true +kubectl label ns kube-node-lease hnc.x-k8s.io/excluded-namespace=true +``` + +Failure to do so may result in HNC being unable to start, and your cluster's +operations being degraded until you delete HNC or apply the labels. + +If you wish, you may also [exclude additional namespaces from +HNC](#admin-excluded-namespaces), but be aware that only the three namespaces +listed above can be excluded _by default_. + #### Install an official release and the kubectl plugin [The most recent official release is @@ -478,6 +497,51 @@ kubectl get crds | grep .hnc.x-k8s.io | awk '{print $1}' | xargs kubectl delete kubectl delete -f https://github.com/kubernetes-sigs/multi-tenancy/releases/download/hnc-${HNC_VERSION}/hnc-manager.yaml ``` + + +### Excluding namespaces from HNC + +***The following instructions are only required for HNC v0.8.x and higher*** + +HNC installs a validating webhook on _all_ objects in your cluster. If HNC +itself is damaged or inaccessible, this could result in all changes to all +objects in your cluster being rejected, making it difficult to repair your +cluster or even re-install HNC. + + +In order to prevent HNC from damaging your cluster, you can exclude certain +namespaces from some of HNC's webhooks. Excluded namespace cannot be the +parent or child of any other namespace; any attempts to change the hierarchy of +an excluded namespace, or create a subnamespace within it, will be rejected by +HNC. However, the critical webhooks will not operate in the excluded namespace, +protecting your cluster's stability. + +In order to exclude namespaces from HNC _before_ installing it: + +1. Add the `hnc.x-k8s.io/excluded-namespace` label with the value of `true` to + all critical namespaces. We recommend, at a minimum, applying this label to + `kube-system`, `kube-public`, and `kube-node-lease`. Note that the HNC + manifests already include this label on `hnc-system` itself. +2. Ensure that all the namespaces you have excluded are also listed in the + [argument list](#admin-cli-args) with the option `--excluded-namespace`. By + default, the HNC manifests include all the critical system namespaces listed + above, but you can exclude any namespace you like. +3. Apply the HNC manifest. + +To exclude an additional namespace from HNC _after_ it has been installed, +follow these steps: + +1. Add the namespace to the list of `--excluded-namespace` [command line + args](#admin-cli-args). +2. Apply the `hnc.x-k8s.io/excluded-namespace=true` label to the namespace. + +If you attempt to apply the `hnc.x-k8s.io/excluded-namespace` label to any +namespace that is not _also_ listed in the command line args, HNC will not allow +the change, or will remove the label when it is started. This prevents users +with edit access to a single namespace from removing themselves from HNC without +permission of the HNC administrator. + + ### Backing up and restoring HNC data @@ -750,13 +814,32 @@ gcloud auth list HNC's default manifest file (available as part of each release with the name `hnc-manager.yaml`) includes a set of reasonable default command-line arguments -for HNC, but you can tweak certain parameters to modify how HNC behaves. These -parameters are different from those controlled by `HNCConfiguration` - they -should only be modified extremely rarely, and only with significant caution. +for HNC. These parameters are part of the `hnc-controller-manager` Deployment +object in the `hnc-system` namespace. + +To modify these parameters, you may: + +* Modify the manifest file and re-apply it with `kubectl apply -f` +* Directly edit the Deployment via `kubectl edit -n hnc-system deploy + hnc-controller-manager`. + +Note that these parameters are different from those controlled by +`HNCConfiguration` - they should only be modified extremely rarely, and only +with significant caution. Interesting parameters include: -* `--apiserver-qps-throttle=<integer>`: set to 50 by default, this limits how many +* `--excluded-namespace=`: allows you to + [exclude a namespace](#admin-excluded-namespaces) from HNC. +* `--unpropagated-annotation=`: empty by default, this argument + can be specified multiple times, with each parameter representing an + annotation name, such as `example.com/foo`. When HNC propagates objects from + ancestor to descendant namespaces, it will strip these annotations out of the + metadata of the _copy_ of the object, if it exists. For example, this can be + used to remove an annotation on the source object that's has a special meaning + to another system, such as GKE Config Sync. If you restart HNC after changing + this arg, all _existing_ propagated objects will also be updated. +* `--apiserver-qps-throttle=`: set to 50 by default, this limits how many requests HNC will send to the Kubernetes apiserver per second in the steady state (it may briefly allow up to 50% more than this number). Setting this value too high can overwhelm the apiserver and prevent it from serving @@ -777,11 +860,3 @@ Interesting parameters include: load on your metrics database (through increased metric cardinality) and also by increasing how carefully you need to guard your metrics against unauthorized viewers. -* `--unpropagated-annotation=<string>`: empty by default, this argument - can be specified multiple times, with each parameter representing an - annotation name, such as `example.com/foo`. When HNC propagates objects from - ancestor to descendant namespaces, it will strip these annotations out of the - metadata of the _copy_ of the object, if it exists. For example, this can be - used to remove an annotation on the source object that's has a special meaning - to another system, such as GKE Config Sync. If you restart HNC after changing - this arg, all _existing_ propagated objects will also be updated. diff --git a/incubator/hnc/docs/user-guide/quickstart.md b/incubator/hnc/docs/user-guide/quickstart.md index 24adbb241..446fe0318 100644 --- a/incubator/hnc/docs/user-guide/quickstart.md +++ b/incubator/hnc/docs/user-guide/quickstart.md @@ -630,7 +630,7 @@ also show up in the HNC logs, and in its [metrics](how-to.md#admin-metrics). -## Keeping objects out of certain namespaces (v0.7 only) +## Keeping objects out of certain namespaces _Demonstrates: exceptions_