diff --git a/README.md b/README.md index a714508cf..77e94bbd9 100644 --- a/README.md +++ b/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): diff --git a/docs/releasing.md b/docs/releasing.md index aad7138a8..e61120c57 100644 --- a/docs/releasing.md +++ b/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 diff --git a/docs/user-guide/README.md b/docs/user-guide/README.md index 2195f863d..7e1d1124c 100644 --- a/docs/user-guide/README.md +++ b/docs/user-guide/README.md @@ -1,4 +1,4 @@ -# HNC User Guide v1.0 (and v0.9) +# HNC User Guide v1.1 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 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) diff --git a/docs/user-guide/concepts.md b/docs/user-guide/concepts.md index ae067de6d..fee0751c6 100644 --- a/docs/user-guide/concepts.md +++ b/docs/user-guide/concepts.md @@ -315,11 +315,12 @@ 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. - + ### Exceptions and propagation control HNC typically propagates _all_ objects of a [specified type](how-to.md#admin-resources) @@ -327,15 +328,15 @@ 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. @@ -517,9 +520,9 @@ problem, and will generally require human intervention to resolve. -### (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, diff --git a/docs/user-guide/how-to.md b/docs/user-guide/how-to.md index 4b7164774..8bf6dfcba 100644 --- a/docs/user-guide/how-to.md +++ b/docs/user-guide/how-to.md @@ -421,9 +421,9 @@ EOF -### (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. -### (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 diff --git a/docs/user-guide/quickstart.md b/docs/user-guide/quickstart.md index c637aba8f..a7b25b3b6 100644 --- a/docs/user-guide/quickstart.md +++ b/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`: