Merge pull request #165 from adrianludwin/docs

Update docs for v1.0

Author: k8s-ci-robot

README.md

@@ -30,14 +30,6 @@ pages](https://github.com/kubernetes-sigs/hierarchical-namespaces/releases/).
 Note that versions of HNC prior to HNC v0.9 are available from our [old
 repo](https://github.com/kubernetes-sigs/multi-tenancy/releases/).
 
-HNC is also supported by the following vendors:
-
-* GCP: as a part of Hierarchy Controller. [Install via Config
-  Sync](https://cloud.google.com/kubernetes-engine/docs/add-on/config-sync/how-to/installing-hierarchy-controller)
-  on GKE or [via
-  ACM](https://cloud.google.com/anthos-config-management/docs/how-to/installing-hierarchy-controller)
-  on Anthos.
-
 Once HNC is installed, you can try out the [HNC
 quickstart](docs/user-guide/quickstart.md)
 to get an idea of what HNC can do. Or, feel free to dive right into the [user
@@ -48,14 +40,15 @@ guide](docs/user-guide) instead.
 Please file issues - the more the merrier! Bugs will be investigated ASAP, while
 feature requests will be prioritized and assigned to a milestone or backlog.
 
-HNC is not yet GA, so please be cautious about using it on clusters with config
-objects you can't afford to lose (e.g. that aren't stored in a Git repository).
+Versions of HNC prior to v1.0 are not GA, so please be cautious about using it
+on clusters with config objects you can't afford to lose (e.g. that aren't
+stored in a Git repository).
 
 All HNC issues are assigned to an HNC milestone. So far, the following
 milestones are defined or planned:
 
 * [v1.0](https://github.com/kubernetes-sigs/hierarchical-namespaces/milestone/2):
-  HNC recommended for production use (ETA late 2021)
+  HNC recommended for production use (ETA April 2022)
 * [v0.9](https://github.com/kubernetes-sigs/hierarchical-namespaces/milestone/1):
   move HNC to its own repo; continued stability improvements.
 * [v0.1-v0.8](https://github.com/kubernetes-sigs/multi-tenancy/milestones):
@@ -67,6 +60,11 @@ HNC is overseen by the Working Group on Multi-Tenancy (wg-multitenancy). Please
 join us on Slack, mailing lists, and at our meeting at our [community
 page](https://github.com/kubernetes/community/blob/master/wg-multitenancy/README.md).
 
+If you use HNC, we recommend joining the
+[kubernetes-hnc-announce](https://groups.google.com/g/kubernetes-hnc-announce)
+mailing list, a low-volume list to receive updates such as new version of HNC
+and proposed changes or new features.
+
 This project is goverened by
 [wg-multitenancy](https://github.com/kubernetes-sigs/multi-tenancy), and was
 originally located in that repo. It moved to this location after approval by

docs/user-guide/README.md

@@ -1,4 +1,4 @@
-# HNC User Guide v0.9 (and v0.8)
+# HNC User Guide v1.0 (and v0.9)
 
 Authors: aludwin@google.com and other contributors from wg-multitenancy
 
@@ -12,8 +12,8 @@ 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.9.x and v0.8.x.** For older versions of HNC,
-see below.
+**Note: this doc covers HNC v1.0.x and v0.9.x.** For older versions of HNC, see
+below.
 
 ## Table of contents
 
@@ -25,8 +25,9 @@ see below.
 
 ## Older user guides
 
-* [HNC v0.7](https://github.com/kubernetes-sigs/multi-tenancy/tree/hnc-v0.7/docs/user-guide)
-* [HNC v0.6](https://github.com/kubernetes-sigs/multi-tenancy/tree/hnc-v0.6/docs/user-guide)
-* [HNC v0.5](https://github.com/kubernetes-sigs/multi-tenancy/tree/hnc-v0.5/docs/user-guide)
-* [HNC v0.4](https://github.com/kubernetes-sigs/multi-tenancy/tree/hnc-v0.4/docs/user-guide)
+* [HNC v0.8](https://github.com/kubernetes-sigs/multi-tenancy/tree/hnc-v0.8/incubator/hnc/docs/user-guide)
+* [HNC v0.7](https://github.com/kubernetes-sigs/multi-tenancy/tree/hnc-v0.7/incubator/hnc/docs/user-guide)
+* [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)

docs/user-guide/concepts.md

@@ -502,9 +502,9 @@ problem, and will generally require human intervention to resolve.
 
 <a name="admin-managed-labels"/>
 
-### Managed labels and annotations
+### (Beta) Managed labels and annotations
 
-***Managed labels and annotations are planned for HNC v1.0+***
+***Managed labels and annotations are new in HNC v1.0; please use with caution.***
 
 Just as certain objects can be propagated from parent namespaces to their
 descendants, so can certain labels and annotations on namespaces. For example,
@@ -577,17 +577,6 @@ namespace if this annotation already exists. The two are mutually exclusive.
 We are considering replacing this with the standard
 `app.kubernetes.io/managed-by` label in the future.
 
-<a name="excluded-namespace-label">
-
-#### hnc.x-k8s.io/excluded-namespace (label on namespaces)
-
-***This label is only used in HNC v0.8 (not applicable in HNC v0.9 and later)***
-
-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. See [Excluding namespaces from
-HNC](how-to.md#admin-excluded-namespaces) for more information.
-
 <a name="admin-labels-set">
 
 ### Labels and annotations set by HNC
@@ -664,8 +653,6 @@ anyone other than HNC.
 
 #### hnc.x-k8s.io/included-namespace (label on namespaces)
 
-***This label is only available in HNC v0.9 and later***
-
 HNC's mutating webhook sets this label on non-excluded namespaces by default.
 HNC also rejects any illegal changes on this label, e.g. adding the label to an
 excluded namespace or removing the label from a non-excluded namespace. This

docs/user-guide/faq.md

@@ -8,12 +8,17 @@ Please feel free to suggest additional questions.
 You can contact us on:
 
 * [Github issues](https://github.com/kubernetes-sigs/hierarchical-namespaces/issues)
-* [Google Groups mailing list](https://groups.google.com/forum/#!forum/kubernetes-wg-multitenancy)
+* [Google Groups mailing list](https://groups.google.com/g/kubernetes-wg-multitenancy)
 * [#wg-multitenancy on Slack](https://kubernetes.slack.com/messages/wg-multitenancy)
 
 Of these, Github and the mailing list will often get you the fastest response
 we're not constantly on Slack.
 
+If you use HNC, we recommend joining the
+[kubernetes-hnc-announce](https://groups.google.com/g/kubernetes-hnc-announce)
+mailing list, a low-volume list to receive updates such as new version of HNC
+and proposed changes or new features.
+
 ## What are HNC's minimum requirements?
 
 HNC technically requires Kubernetes 1.16 or higher, although we don't test on

docs/user-guide/how-to.md

@@ -405,34 +405,52 @@ EOF
 
 <a name="use-managed-labels"/>
 
-### Add a label or annotation to all namespaces in a subtree
+### (Beta) Add a label or annotation to all namespaces in a subtree
 
-***Managed labels and annotations are planned for HNC v1.0+***
+***Managed labels and annotations are new in HNC v1.0; please use with caution.***
 
 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:
+annotations](#admin-managed-labels), you may set them on any _full_ 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 > …
+  ... < 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
+You may similarly set managed annotations via the `.spec.annotations` list.
+
+For subnamespaces, you must set managed labels/annotations on the anchor in the
+parent namespace; any changes you make to the `HierarchyConfiguration` will be
+ignored and overwritten. The format on the anchors is the same as on the config:
+
+```
+apiVersion: hnc.x-k8s.io/v1alpha2
+kind: SubnamespaceAnchor
+metadata:
+  name: subns-name
+  namespace: subns-parent
+  ... < other stuff > ...
+spec:
+  labels:          # add
+  - key: env       # add
+    value: prod    # add
+```
+
+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)).
+[improved](https://github.com/kubernetes-sigs/hierarchical-namespaces/issues/144).
 
 <a name="admin"/>
 
@@ -448,24 +466,14 @@ 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.
 
+_Note: HNC has **experimental** support for HA deployments in v1.0. Please
+contact us on Slack to discuss if you want to try it out._
+
 #### Prerequisites
 
 Ensure `kube-system`, `kube-public` and `kube-node-lease` namespaces are listed
 in the [argument list](#admin-cli-args) with the option `--excluded-namespace`.
 
-**In HNC v0.8 (not applicable in HNC v0.9 and later)**, 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_.
@@ -505,7 +513,7 @@ make deploy
 To temporarily disable HNC, simply delete its deployment and webhooks:
 
 ```bash
-kubectl -n hnc-system delete deployment hnc-controller-manager
+kubectl -n hnc-system delete deployment --all
 kubectl delete validatingwebhookconfiguration.admissionregistration.k8s.io hnc-validating-webhook-configuration
 ```
 
@@ -534,16 +542,16 @@ relationships and configuration settings:
 # the finalizers first.
 kubectl get crds | grep .hnc.x-k8s.io | awk '{print $1}' | xargs kubectl delete crd
 
-# Delete the rest of HNC.
+# Delete the rest of HNC. For HNC v1.0 and later:
+kubectl delete -f https://github.com/kubernetes-sigs/hierarchical-namespaces/releases/download/hnc-${HNC_VERSION}/default.yaml
+# For versions earlier than HNC v1.0:
 kubectl delete -f https://github.com/kubernetes-sigs/hierarchical-namespaces/releases/download/hnc-${HNC_VERSION}/hnc-manager.yaml
 ```
 
 <a name="admin-excluded-namespaces"/>
 
 ### Including and excluding namespaces from HNC
 
-***Included namespaces are only available in HNC v0.9 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
@@ -560,7 +568,7 @@ protecting your cluster's stability.
 HNC supports two methods of specifying which namespaces should be managed, both
 of which are accessed from the HNC [argument list](#admin-cli-args):
 
-* **Included namespace regex (HNC v0.9+ only):** If set, this will limit HNC to
+* **Included namespace regex:** If set, this will limit HNC to
   only cover the namespaces included in this regex. For example, setting this
   parameter to `test-.*` will ensure that HNC only manages namespaces that begin
   with the prefix `test-` (HNC adds an implied `^...$` to the regex). If
@@ -575,14 +583,6 @@ of which are accessed from the HNC [argument list](#admin-cli-args):
    `--excluded-namespace` option, which can be specified multiple times, one
    namespace per option.
 
-**In HNC v0.8 only (not applicable in HNC v0.9 and later):** In addition to
-specifying excluded namespaces on the command line, you must _also_ add the
-`hnc.x-k8s.io/excluded-namespace=true` label to all excluded namespaces, _after_
-you have restarted HNC with the correct parameter. If you attempt to apply this
-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
-label has no effect in HNC v0.9 or later.
-
 
 <a name="admin-backup-restore"/>
 
@@ -759,9 +759,10 @@ edit the `config` object directly, which will bypass this protection.
 
 <a name="admin-managed-labels"/>
 
-### Ask HNC to manage certain labels and annotations
+### (Beta) Ask HNC to manage certain labels and annotations
 
-***Managed labels and annotations are planned for HNC v1.0+***
+***Managed labels and annotations are new in HNC v1.0; please use with
+caution.***
 
 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
@@ -881,9 +882,10 @@ gcloud auth list
 ## Modify command-line arguments
 
 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. These parameters are part of the `hnc-controller-manager` Deployment
-object in the `hnc-system` namespace.
+`hnc-manager.yaml` prior to HNC v1.0, and `default.yaml` after HNC v1.0)
+includes a set of reasonable default command-line arguments for HNC. These
+parameters are part of the `hnc-controller-manager` Deployment object in the
+`hnc-system` namespace.
 
 To modify these parameters, you may:
 
@@ -897,12 +899,14 @@ with significant caution.
 
 Interesting parameters include:
 
-* `--included-namespace-regex=<pattern>` (HNC v0.9+ only): limits which
+* `--included-namespace-regex=<pattern>`: limits which
   namespaces are [managed by HNC](#admin-excluded-namespaces). Defaults to `.*`,
   and may only be specified once.
 * `--excluded-namespace=<namespace>`: allows you to
   [exclude a namespace](#admin-excluded-namespaces) from HNC. May be specified
   multiple times, one namespace per option.
+* `--managed-namespace-label` and `--managed-namespace-annotation`: see [managed
+  labels and annotations](#admin-managed-labels).
 * `--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