Fix managed label conditions and docs

Add a very minor fix to ensure that out-of-date managed label conditions
are cleared. Also update a variety of docs.

Tested: existing tests only

Author: adrianludwin

api/v1alpha2/hierarchy_types.go

@@ -54,15 +54,16 @@ const (
 	ConditionActivitiesHalted string = "ActivitiesHalted"
 	ConditionBadConfiguration string = "BadConfiguration"
 
-	// Condition reasons.
+	// Condition reasons. Please keep this list in alphabetical order. IF ADDING ANYTHING HERE, PLEASE
+	// ALSO ADD THEM TO AllConditions, BELOW.
 	ReasonAncestor                 string = "AncestorHaltActivities"
+	ReasonAnchorMissing            string = "SubnamespaceAnchorMissing"
 	ReasonDeletingCRD              string = "DeletingCRD"
+	ReasonIllegalManagedAnnotation string = "IllegalManagedAnnotation"
+	ReasonIllegalManagedLabel      string = "IllegalManagedLabel"
+	ReasonIllegalParent            string = "IllegalParent"
 	ReasonInCycle                  string = "InCycle"
 	ReasonParentMissing            string = "ParentMissing"
-	ReasonIllegalParent            string = "IllegalParent"
-	ReasonAnchorMissing            string = "SubnamespaceAnchorMissing"
-	ReasonIllegalManagedLabel      string = "IllegalManagedLabel"
-	ReasonIllegalManagedAnnotation string = "IllegalManagedAnnotation"
 )
 
 // AllConditions have all the conditions by type and reason. Please keep this
@@ -72,9 +73,11 @@ var AllConditions = map[string][]string{
 	ConditionActivitiesHalted: {
 		ReasonAncestor,
 		ReasonDeletingCRD,
+		ReasonIllegalManagedAnnotation,
+		ReasonIllegalManagedLabel,
+		ReasonIllegalParent,
 		ReasonInCycle,
 		ReasonParentMissing,
-		ReasonIllegalParent,
 	},
 	ConditionBadConfiguration: {
 		ReasonAnchorMissing,

docs/user-guide/concepts.md

@@ -14,12 +14,13 @@ namespaces are, and _why_ they behave the way they do.
   * [Parents, children, trees and forests](#basic-trees)
   * [Full namespaces and subnamespaces](#basic-subns)
   * [Policy inheritance and object propagation](#basic-propagation)
-  * [Namespace labels and non-propagated policies](#basic-labels)
+  * [Tree labels and non-propagated policies](#basic-labels)
   * [Exceptions and propagation control](#basic-exceptions)
 * [Administration](#admin)
   * [Hierarchical Configuration](#admin-hc)
   * [Namespaces administrators](#admin-admin)
   * [Conditions](#admin-conditions)
+  * [Namespace label and annotation propagation](#admin-managed-labels)
   * [Labels and annotations read by HNC](#admin-labels-read)
   * [Labels and annotations set by HNC](#admin-labels-set)
 
@@ -291,7 +292,7 @@ following three labels applied to it:
 * `team-a.tree.hnc.x-k8s.io/depth: 1`
 * `division-x.tree.hnc.x-k8s.io/depth: 2`
 
-Due to their suffixes, these are known as **_tree labels_**.
+Due to their suffixes, these are known as ***tree labels***.
 
 Tree labels can be used in two ways. Firstly, any policy that uses namespace
 label selectors may use them directly - even if those policies are not
@@ -314,6 +315,9 @@ whichever labels they like. However, HNC will overwrite any changes made to
 these labels, so other applications can trust these labels for policy
 application.
 
+*Note: in HNC v1.0, [managed labels](#admin-managed-labels) may also be trusted
+for policy purposes.*
+
 <a name="basic-exceptions"/>
 
 ### Exceptions and propagation control
@@ -353,21 +357,12 @@ be replaced.
 There are some built-in exceptions to prevent certain known (auto-generated)
 objects from being propagated by HNC.
 
-If ConfigMaps propagation is enabled, any ConfigMaps named `istio-ca-root-cert`
-or `kube-root-ca.crt` will not be propagated. These are auto-created in new
-namespaces by Istio and Kubernetes respectively. As they are auto-generated,
-adding annotations is not possible and HNC will by default exclude them.
-
-Similarly, Kubernetes ServiceAccount Secrets will also by default be excluded
-from propagation.
-
-In addition, propagation exclusions are also used for Rancher-managed Kubernetes
-clusters. Rancher uses a "project" concept that bundles namespaces and thus sets
-roles, rolebindings, etc. for all namespaces of a project. This leads to
-conflicts with HNC, so all resources created by Rancher (which are automatically
-labeled with `"cattle.io/creator": "norman"` by Rancher, cf. [their
-docs](https://rancher.com/docs/rancher/v2.6/en/system-tools/#remove)) are
-excluded from propagation.
+* Kubernetes Service Account Secrets
+* ConfigMaps named `istio-ca-root-cert` or `kube-root-ca.crt`, which are
+  auto-created in new namespaces by Istio and Kubernetes respectively
+* *Planned for HNC v1.0+:* Any objects with the label
+  `cattle.io/creator:norman`, which are [inserted by Rancher to support
+  Projects](https://rancher.com/docs/rancher/v2.6/en/system-tools/#remove))
 
 <a name="admin"/>
 
@@ -505,6 +500,40 @@ can either query such objects directly, or via `kubectl hns describe NAMESPACE`.
 The event will include machine-readable and human-readable information about the
 problem, and will generally require human intervention to resolve.
 
+<a name="admin-managed-labels"/>
+
+### Managed labels and annotations
+
+***Managed labels and annotations are planned for HNC v1.0+***
+
+Just as certain objects can be propagated from parent namespaces to their
+descendants, so can certain labels and annotations on namespaces. For example,
+an admin may define a `mycorp.com/environment:prod` label on a parent namespace,
+and ensure that it will be automatically propagated to all descendants of that
+namespace.
+
+However, managed labels (and annotations - the remainder of this section applies
+to both) cannot be used simply by putting a label on a parent namespace, for
+several reasons:
+
+* Users may not intend HNC to overwrite their existing labels simply because one
+  of their ancestors has a conflicting label.
+* When a namespace's ancestors change, it's unclear which labels should be
+  removed because they were propagated from an ancestor, and which were
+  intended to be applied to the namespace itself.
+
+Therefore, by default, HNC will _not_ propagate any labels on namespaces; the
+HNC admin must define which labels are _managed_ by modifying the command-line
+options of HNC and restarting HNC.
+
+In addition, managed labels may _never_ be set simply by adding them to a
+namespace, as it would be impossible to distinguish between a "source" label and
+a "propagated" label (unlike propagated objects, which are annotated by
+`hnc.x-k8s.io/inherited-from`). Instead, they must be added in the
+`HierarchyConfiguration` object.
+
+See [here](how-to.md#admin-managed-labels) for more details.
+
 <a name="admin-labels-read">
 
 ### Labels and annotations read by HNC
@@ -514,8 +543,8 @@ objects, in addition to using the custom resources it defines.
 
 #### propagate.hnc.x-k8s.io/TYPE (annotation on objects)
 
-These annotations may be added to any namespaced object to define exceptions to
-propagation rules. More information to come.
+These annotations may be added to any namespaced object to define
+[exceptions](#basic-exceptions) to propagation rules.
 
 #### hnc.x-k8s.io/managed-by (annotation on namespaces)
 
@@ -567,6 +596,9 @@ HNC annotates and labels objects in several circumstances. Typically, most users
 (or admins) will never need to care about these, but occasionally they may cause
 some odd changes in behaviour that you need to be aware of.
 
+See also [managed labels and annotations](#admin-managed-labels), which are
+defined by admins, not by HNC itself.
+
 #### app.kubernetes.io/managed-by (label on objects)
 
 HNC sets this label on any object that it propagates, taking the place of any

docs/user-guide/how-to.md

@@ -15,13 +15,15 @@ This document describes common tasks you might want to accomplish using HNC.
   * [Organize full namespaces into a hierarchy](#use-full)
   * [Resolve conditions on a namespace](#use-resolve-cond)
   * [Limit the propagation of an object to descendant namespaces](#use-limit-propagation)
+  * [Add a label or annotation to all namespaces in a subtree](#use-managed-labels)
 * [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)
+  * [Ask HNC to manage certain labels and annotations](#admin-managed-labels)
   * [Gather metrics](#admin-metrics)
   * [Modify command-line arguments](#admin-cli-args)
 
@@ -189,9 +191,9 @@ destination (descendant) namespace.
 ### Select namespaces based on their hierarchies
 
 HNC inserts labels onto your namespaces to allow trees (and subtrees) of
-namespaces to be selected by policies such as `NetworkPolicy`.
-
-This section is under construction (as of Oct 2020). For now, please see the
+namespaces to be selected by policies such as Network Policies. For more
+information, read about the [concept](concepts.md#basic-labels) or see an
+example for how they can apply to Network Policies in the
 [quickstart](quickstart.md#netpol).
 
 <a name="use-subns-delete"/>
@@ -401,6 +403,37 @@ metadata:
 EOF
 ```
 
+<a name="use-managed-labels"/>
+
+### Add a label or annotation to all namespaces in a subtree
+
+***Managed labels and annotations are planned for HNC v1.0+***
+
+If your administrator has [created managed labels or
+annotations](#admin-managed-labels), you may set them on any namespace where you
+have permission to edit the `hierarchyconfigurations/hierarchy` object. For
+example, if your admin has set `env` as a managed label, you may set it on your
+namespace as follows:
+
+```
+apiVersion: hnc.x-k8s.io/v1alpha2
+kind: HierarchyConfiguration
+metadata:
+  name: hierarchy
+  namespace: child
+  … < other stuff > …
+spec:
+  labels:          # add
+  - key: env       # add
+    value: prod    # add
+```
+
+You may similarly set managed annotations via the `.spec.annotations` list. Note
+that any label or annotation that conflicts with one set in an ancestor
+namespace will be silently ignored (this will eventually
+[be](https://github.com/kubernetes-sigs/hierarchical-namespaces/issues/143)
+[improved](https://github.com/kubernetes-sigs/hierarchical-namespaces/issues/144)).
+
 <a name="admin"/>
 
 ## Administer HNC
@@ -724,6 +757,32 @@ immediately, you can use the `--force` flag with `kubectl hns config
 set-resource` to add a resource directly in the `Propagate` mode. You can also
 edit the `config` object directly, which will bypass this protection.
 
+<a name="admin-managed-labels"/>
+
+### Ask HNC to manage certain labels and annotations
+
+***Managed labels and annotations are planned for HNC v1.0+***
+
+See [here](concepts.md#admin-managed-labels) for the background on managed
+labels and annotations. In order to get HNC to manage a label or annotation, use
+the following [command-line arguments](#admin-cli-args):
+
+* `--managed-namespace-label` for labels
+* `--managed-namespace-annotation` for annotations
+
+Both of these options may be specified multiple times, and both of them are
+regular expressions, but automaticaly have `^...$` surrounding them. For
+example, to ask HNC to manage any label with the prefix `hier.mycorp.com`, set
+the parameter `--managed-namespace-label hier.mycorp.com/.*`.
+
+When you ask HNC to start managing a label or annotation, all _existing_
+namespace labels/annotations that match the pattern will immediately be deleted
+(unless they are specified in the `HierarchyConfiguration`), so use this feature
+with care.
+
+See [here](#use-managed-labels) for more information on how to use managed
+labels and annotations once they've been enabled.
+
 <a name="admin-metrics"/>
 
 ### Gather metrics