From 8daf91237cfdb8e989275ddcd4f0b49887c8cf15 Mon Sep 17 00:00:00 2001 From: Anton Gilgur Date: Tue, 4 Jul 2023 14:28:11 -0400 Subject: [PATCH] docs: improve grammar and simplify HRQ examples Was reading through the docs and these seemed the most verbose - it seems to be a very recent feature as well, from 3aef487a1aabe96195e25577985ad50e31ce4716 - use same heading in both Quickstart and Concepts, including HRQ abbreviation - use abbreviation to shorten the HRQ docs themselves as well - fix run-on sentences by adding punctuation - "by default, to use it" -> "by default. To use it" - add missing commas - "Then,", "finally,", etc - add Oxford commas - ", but", ", and", ", or", etc - simplify several sentences, per [k8s style guide](https://kubernetes.io/docs/contribute/style/style-guide/#use-simple-and-direct-language) - "won't be over the amount of resources that is configured in `HierarchicalResourceQuota`" -> "cannot surpass the HRQ" - "can't go over what is configured in the HRQ" -> "can't surpass the HRQ" - "And put the resources HRQ in" -> "An HRQ in" - "This will restrict whole" -> "restricts" (also uses present tense now, per style guide) - "the amount of resources that" -> "the resources" "resource usage" -> "resources" - "automatically creates" -> "creates" - in a similar vein, remove or replace ambiguous language - "equally shared" -> "shared" -- they can be shared however, not necessarily "equally" - "which is very efficient" -> "" -- "efficient" could be interpreted in a performance sense and is unnecesary - "lower level", "level" -> "child" / "sub" -- use HNC's existing terminology instead of "lower level", which has multiple disambiguations - Similarly use HNC's existing terminology for: - "individual", "members" -> "namespace", "subnamespaces" - "above", "overall" -> "parent" - "wins" -> "applies" -- replace idiom, per [style guide](https://kubernetes.io/docs/contribute/style/style-guide/#avoid-jargon-and-idioms) - clarify a few sentences with a single word - "within", "Instead", "still", "directly" - consolidate the two paragraphs on command-line usage into one - looks like they were added at different times, in 564b4a968ca2091f27cf0eb51d0cd99190e57db5 - they largely duplicated each other with slighlty different wording - creating an HRQ via a CR YAML is the definition of how CRs work, which are already used across HNC, so not necessary to re-explain - also remove the word "simply", per [style guide](https://kubernetes.io/docs/contribute/style/style-guide/#avoid-words-that-assume-a-specific-level-of-understanding) There are potentially more changes that could be made according to the style guide, but I primarily limited changes to simplifications, clarifications, and grammar --- docs/user-guide/concepts.md | 59 ++++++++++++++++++----------------- docs/user-guide/quickstart.md | 14 ++++----- 2 files changed, 37 insertions(+), 36 deletions(-) diff --git a/docs/user-guide/concepts.md b/docs/user-guide/concepts.md index e58e2664d..328d72550 100644 --- a/docs/user-guide/concepts.md +++ b/docs/user-guide/concepts.md @@ -227,18 +227,18 @@ You can create a subnamespace from the command line via `kubectl hns create chil ***Hierarchical resource quotas are beta in HNC v1.1*** -***HRQs are not included by default, to use it install the hrq.yaml file in the [releases -> Assets](https://github.com/kubernetes-sigs/hierarchical-namespaces/releases)*** +***HRQs are not included by default. To use it, install the `hrq.yaml` file in [Releases -> Assets](https://github.com/kubernetes-sigs/hierarchical-namespaces/releases)*** When you want to give some amount of resources to `team-a`, and want them to be able to flexibly use resources in any of their subnamespaces, you create a `HierarchicalResourceQuota` -in namespace `team-a`. The sum of all resources from all the subnamespaces of the -members won't be over the amount of resources that is configured in -`HierarchicalResourceQuota` of namespace `team-a`. All of the resources of `team-a` are -equally shared between the applications in their subnamespaces, which is very efficient. +in namespace `team-a`. The sum of all resources from all subnamespaces of `team-a` +cannot surpass the HRQ in namespace `team-a`. All of the resources of `team-a` are +shared between applications in their subnamespaces. -In addition, you can let an org or team's admin create their own hierarchical -quotas without violating the overall HRQ for their org or team. For example, +In addition, you can let an org or team's admin create sub-HRQs +without violating the parent HRQ for their org or team. For example, if you start with the following structure: + ``` company-a ├── organization-a @@ -251,42 +251,43 @@ company-a │ ... ... ``` -Instead of each team asking from the `cluster-admin` to modify their `ResourceQuota`, -you can insert an additional "policy" namespace above each level to hold -the policy objects (like hierarchical quota) that the sub-admin _cannot_ -change, while giving them permission to create their own quotas in the -lower level namespaces, like this: + +Instead of each team asking a cluster admin to modify their `ResourceQuota`, +you can insert an additional "policy" parent namespace to hold +policy objects like HRQ. The sub-admin _cannot_ change the parent policies, +but still has permission to create sub-HRQs in their subnamespaces, like this: + ``` company-a-policy └── company-a ``` -And put the resources HRQ in the `company-a-policy` namespace. This will restrict -whole `company-a` to the amount of resources that they are paying for. Then `company-a` -can do similar HRQ with their organizations: + +An HRQ in the `company-a-policy` namespace restricts +`company-a` to the resources they are paying for. Then, `company-a` +can create sub-HRQs for their internal organizations: + ``` company-a-policy (has HRQ) └── company-a - ├── org-a-policy (has HRQ) + ├── org-a-policy (has sub-HRQ) │ └── organization-a - ├── org-b-policy (has HRQ) + ├── org-b-policy (has sub-HRQ) │ └── organization-b ... ``` -Lower-level quotas cannot override more restrictive quotas from ancestor namespaces; -the most restrictive quota always wins. -This way each individual can fairly and securely distribute their resources across -their members. - -You can create the HRQ `CustomResource` by simply applying a yaml file, and see usage via `kubectl hns hrq` or `kubectl get hrq`. See -[quickstart example](quickstart.md#hrq) for reference. +Child quotas cannot override more restrictive quotas from ancestor namespaces; +the most restrictive quota always applies. +This way, each namespace can fairly and securely distribute their resources across +their subnamespaces. -To implement hierarchical quotas, HNC automatically creates `ResourceQuota` objects in each -affected namespace. This is a part of the internal implementation and shouldn't be modified or -inspected. Use the `kubectl hns hrq` command to inspect hierarchical quotas, -or look at the `HierarchicalResourceQuota` object in the ancestor namespaces. +To implement hierarchical quotas, HNC creates `ResourceQuota` objects in each +affected namespace. This is part of the internal implementation and shouldn't be modified or +inspected directly. Instead, use `kubectl hns hrq` to inspect hierarchical quotas +or, in ancestor namespaces, `kubectl get hrq`. +See the [quickstart example](quickstart.md#hrq) for reference. -Note: Decimal point values cannot be specified in HRQ (you can't do `cpu: 1.5` but you can do `cpu: "1.5"` or `cpu: 1500m`). See [#292](https://github.com/kubernetes-sigs/hierarchical-namespaces/issues/292) +Note: Decimal point values cannot be specified in HRQ (you can't do `cpu: 1.5`, but you can do `cpu: "1.5"` or `cpu: 1500m`). See [#292](https://github.com/kubernetes-sigs/hierarchical-namespaces/issues/292) diff --git a/docs/user-guide/quickstart.md b/docs/user-guide/quickstart.md index e00d92f82..f5a9cddb1 100644 --- a/docs/user-guide/quickstart.md +++ b/docs/user-guide/quickstart.md @@ -461,11 +461,11 @@ kubectl delete pods s2 -n service-2 -### Hierarchical resource quotas +### Hierarchical resource quotas (HRQs) ***Hierarchical resource quotas are beta in HNC v1.1*** -***HRQs are not included by default, to use it install the hrq.yaml file in the [releases -> Assets](https://github.com/kubernetes-sigs/hierarchical-namespaces/releases)*** +***HRQs are not included by default. To use it, install the `hrq.yaml` file in [Releases -> Assets](https://github.com/kubernetes-sigs/hierarchical-namespaces/releases)*** _Will demonstrate: Create and delete [HierarchicalResourceQuota](concepts.md#hierarchical-resource-quota)._ @@ -476,11 +476,11 @@ acme-org └── [s] team-b ``` -You can create a `HierarchicalResourceQuota` in namespace `acme-org`, and the sum of -all subnamespaces resource usage can't go over what is configured in the HRQ. +If you create a `HierarchicalResourceQuota` in namespace `acme-org`, the sum of +all subnamespaces' resources can't surpass the HRQ. We will demonstrate how it works using services, but you could also limit `cpu`, -`memory` or any other `ResourceQuota` field. +`memory`, or any other `ResourceQuota` field. Creating the HRQ: ```bash @@ -525,12 +525,12 @@ acme-org services: 1/1 ``` You can also view HRQs in all namespaces by running `kubectl get hrq -A`. -And finally you can delete the HRQ via simply deleting the CR: +And finally, you can delete the HRQ by deleting the CR: ```bash kubectl delete hrq acme-org-hrq -n acme-org ``` -Note: Decimal point values cannot be specified (you can't do `cpu: 1.5` but +Note: Decimal point values cannot be specified (you can't do `cpu: 1.5`, but you can do `cpu: "1.5"` or `cpu: 1500m`). See [#292](https://github.com/kubernetes-sigs/hierarchical-namespaces/issues/292)