Merge pull request #263 from adrianludwin/docs

Update docs for v1.1

README.md

@@ -44,7 +44,7 @@ All HNC issues are assigned to an HNC milestone. So far, the following
 milestones are defined or planned:
 
 * [v1.1](https://github.com/kubernetes-sigs/hierarchical-namespaces/milestone/3):
-  Improved UX for managed labels; performance improvements.
+  Hierarchical quotas; inclusive propagation.
 * [v1.0](https://github.com/kubernetes-sigs/hierarchical-namespaces/milestone/2):
   HNC recommended for production use (released March 31 2022)
 * [v0.9](https://github.com/kubernetes-sigs/hierarchical-namespaces/milestone/1):

docs/releasing.md

@@ -36,14 +36,8 @@ that anyone can use, but without leaking personal access tokens._
 
 Ensure that the [user guide](user-guide/) is up-to-date with all the latest or
 changed features. _This must be done on the master branch **before** creating
-the release branch._ The user guide should usually contain instructions for at
-least the last two minor releases of HNC - e.g., if the current version is v0.5,
-it should contain instructions for both v0.4 and v0.5. But if you're _about_ to
-release v0.6, then you should:
-
-* In the master docs README, add a link to the v0.4 version of the user guide.
-* Delete everything about v0.4
-* Add all new information for v0.6.
+the release branch._ We used to remove instructions for old versions of HNC, but
+since v1.0 this should no longer be necessary as it's not changing as quickly.
 
 ## Create a release branch
 

docs/user-guide/README.md

@@ -1,4 +1,4 @@
-# HNC User Guide v1.0 (and v0.9)
+# HNC User Guide v1.1
 
 Authors: [email protected] 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 v1.0.x and v0.9.x.** For older versions of HNC, see
+**Note: this doc covers HNC v1.0 and later.** For older versions of HNC, see
 below.
 
 ## Table of contents
@@ -25,6 +25,7 @@ below.
 
 ## Older user guides
 
+* [HNC v0.9](https://github.com/kubernetes-sigs/hierarchical-namespaces/tree/hnc-v0.9/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)

docs/user-guide/concepts.md

@@ -315,27 +315,28 @@ 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.*
+If tree labels are too restrictive for your purposes, you can also use [managed
+labels](#admin-managed-labels), which require more work to set up but are also
+managed by HNC and are therefore suitable for policy use.
 
 <a name="basic-exceptions"/>
- 
+
 ### Exceptions and propagation control
 
 HNC typically 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:
 
 * A ResourceQuota was propagated to many children, but one child namespace now
-has higher requirements than the rest. Rather than getting rid of the quota in
-the parent namespace, or raising the limit for everyone, you can stop the
-quota in the parent from being propagated to that _one_ child namespace,
-allowing you to replace it with another, more suitable quota.
+  has higher requirements than the rest. Rather than getting rid of the quota in
+  the parent namespace, or raising the limit for everyone, you can stop the
+  quota in the parent from being propagated to that _one_ child namespace,
+  allowing you to replace it with another, more suitable quota.
 
 * A RoleBinding allows any user to create subnamespaces under one namespace, but
-we don’t want to allow those users to create additional levels of hierarchy
-underneath those subnamespaces. So you can stop the role binding from being
-propagated to _any_ child namespace.
+  we don’t want to allow those users to create additional levels of hierarchy
+  underneath those subnamespaces. So you can stop the role binding from being
+  propagated to _any_ child namespace.
 
 Exceptions are defined using [annotations on the objects
 themselves](how-to.md#use-limit-propagation).  As a result, anyone who can edit
@@ -353,18 +354,19 @@ exclude those objects, or else delete the conflicting objects to allow them to
 be replaced.
 
 #### (Beta in v1.1) Opt-in propagation
-The `Propagate` mode propagates all objects unless directed to otherwise via a selector,
-using exceptions. By contrast, opt-in propagation, as set by the `AllowPropagate` 
-mode, doesn't propagate objects unless directed to by a selector. That is, for an object 
-with a selector, its behaviour will be identical in both the `Propagate` and `AllowPropagate` modes; 
-the only difference in behaviours is for objects without a selector.
+The `Propagate` mode propagates all objects unless directed to otherwise via a
+selector, using exceptions. By contrast, opt-in propagation, as set by the
+`AllowPropagate` mode, doesn't propagate objects unless directed to by a
+selector. That is, for an object with a selector, its behaviour will be
+identical in both the `Propagate` and `AllowPropagate` modes; the only
+difference in behaviours is for objects without a selector.
 
 For example:
- 
+
 * A Secret exists on a namespace but we don't want this secret to be propagated
-to all subnamespaces by default but instead only to one namespace of our choosing. 
-So you can choose to propagate to that _one_ child namespace using `AllowPropagate`
-and exceptions.
+  to all subnamespaces by default but instead only to one namespace of our
+  choosing.  So you can choose to propagate to that _one_ child namespace using
+  `AllowPropagate` and exceptions.
 
 #### Built-in exceptions
 
@@ -374,10 +376,11 @@ objects from being propagated by HNC.
 * 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
+* 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))
-* *Planned for future version:* Secrets with type `helm.sh/release.v1`, which is auto-created in the namespaces where their respective Helm releases are deployed to.
+* *HNC v1.1+:* Secrets with type `helm.sh/release.v1`, which is auto-created in
+  the namespaces where their respective Helm releases are deployed to.
 
 <a name="admin"/>
 
@@ -517,9 +520,9 @@ problem, and will generally require human intervention to resolve.
 
 <a name="admin-managed-labels"/>
 
-### (Beta) Managed labels and annotations
+### Managed labels and annotations
 
-***Managed labels and annotations are new in HNC v1.0; please use with caution.***
+***Managed labels and annotations are beta in HNC v1.0 and GA in HNC v1.1+.***
 
 Just as certain objects can be propagated from parent namespaces to their
 descendants, so can certain labels and annotations on namespaces. For example,

docs/user-guide/how-to.md

@@ -421,9 +421,9 @@ EOF
 
 <a name="use-managed-labels"/>
 
-### (Beta) Add a label or annotation to all namespaces in a subtree
+### Add a label or annotation to all namespaces in a subtree
 
-***Managed labels and annotations are new in HNC v1.0; please use with caution.***
+***Managed labels and annotations are beta in HNC v1.0 and GA in HNC v1.1+.***
 
 If your administrator has [created managed labels or
 annotations](#admin-managed-labels), you may set them on any _full_ namespace
@@ -482,7 +482,7 @@ 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
+_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
@@ -768,9 +768,10 @@ in the `Propagate` mode or `AllowPropagate`.  Instead, to do so safely:
   synchronizing all known source objects.
 * Wait until `kubectl hns config describe` looks like it's identified the
   correct number of objects of the newly added resource in its status.
-* Change the propagation mode from `Remove` to `Propagate` or `AllowPropagate`. 
-  HNC will then check to see if any objects will be overwritten, and will not 
-  allow you to change the propagation mode until all such conflicts are resolved.
+* Change the propagation mode from `Remove` to `Propagate` or `AllowPropagate`.
+  HNC will then check to see if any objects will be overwritten, and will not
+  allow you to change the propagation mode until all such conflicts are
+  resolved.
 
 Alternatively, if you're certain you want to start propagating objects
 immediately, you can use the `--force` flag with `kubectl hns config
@@ -779,10 +780,9 @@ edit the `config` object directly, which will bypass this protection.
 
 <a name="admin-managed-labels"/>
 
-### (Beta) Ask HNC to manage certain labels and annotations
+### Ask HNC to manage certain labels and annotations
 
-***Managed labels and annotations are new in HNC v1.0; please use with
-caution.***
+***Managed labels and annotations are beta in HNC v1.0 and GA in HNC v1.1+.***
 
 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

docs/user-guide/quickstart.md

@@ -209,9 +209,9 @@ simply use the config subcommand:
 kubectl hns config set-resource secrets --mode Propagate
 ```
 
-  Note: As of HNC v1.0+, the supported modes are `Propagate`, `Remove`,
-  `Ignore` and `AllowPropagate`. More may be added in the future; you can run `kubectl hns config
-  set-resource` for the latest documentation.
+  Note: The supported modes are `Propagate`, `Remove`, `Ignore` and (in HNC
+  v1.1+ only) `AllowPropagate`. More may be added in the future; you can run
+  `kubectl hns config set-resource` for the latest documentation.
 
 Now, we should be able to verify that `my-creds` was propagated to `service-1`: