Merge remote-tracking branch 'upstream/main' into dev-1.30

Merge remote-tracking branch 'upstream/main' into dev-1.30

Author: chanieljdan

content/en/docs/concepts/overview/kubernetes-api.md

@@ -22,21 +22,139 @@ external components communicate with one another.
 The Kubernetes API lets you query and manipulate the state of API objects in Kubernetes
 (for example: Pods, Namespaces, ConfigMaps, and Events).
 
-Most operations can be performed through the
-[kubectl](/docs/reference/kubectl/) command-line interface or other
-command-line tools, such as
-[kubeadm](/docs/reference/setup-tools/kubeadm/), which in turn use the
-API. However, you can also access the API directly using REST calls.
+Most operations can be performed through the [kubectl](/docs/reference/kubectl/)
+command-line interface or other command-line tools, such as
+[kubeadm](/docs/reference/setup-tools/kubeadm/), which in turn use the API.
+However, you can also access the API directly using REST calls. Kubernetes
+provides a set of [client libraries](/docs/reference/using-api/client-libraries/)
+for those looking to
+write applications using the Kubernetes API.
+
+Each Kubernetes cluster publishes the specification of the APIs that the cluster serves.
+There are two mechanisms that Kubernetes uses to publish these API specifications; both are useful
+to enable automatic interoperability. For example, the `kubectl` tool fetches and caches the API
+specification for enabling command-line completion and other features.
+The two supported mechanisms are as follows:
+
+- [The Discovery API](#discovery-api) provides information about the Kubernetes APIs:
+  API names, resources, versions, and supported operations. This is a Kubernetes
+  specific term as it is a separate API from the Kubernetes OpenAPI.
+  It is intended to be a brief summary of the available resources and it does not
+  detail specific schema for the resources. For reference about resource schemas,
+  please refer to the OpenAPI document.
+
+- The [Kubernetes OpenAPI Document](#openapi-specification) provides (full)
+  [OpenAPI v2.0 and 3.0 schemas](https://www.openapis.org/) for all Kubernetes API
+endpoints.
+  The OpenAPI v3 is the preferred method for accessing OpenAPI as it
+provides
+  a more comprehensive and accurate view of the API. It includes all the available
+  API paths, as well as all resources consumed and produced for every operations
+  on every endpoints. It also includes any extensibility components that a cluster supports.
+  The data is a complete specification and is significantly larger than that from the
+  Discovery API.
+
+## Discovery API
+
+Kubernetes publishes a list of all group versions and resources supported via
+the Discovery API. This includes the following for each resource:
+
+- Name
+- Cluster or namespaced scope
+- Endpoint URL and supported verbs
+- Alternative names
+- Group, version, kind
+
+The API is available both aggregated and unaggregated form. The aggregated
+discovery serves two endpoints while the unaggregated discovery serves a
+separate endpoint for each group version.
+
+### Aggregated discovery
+
+{{< feature-state state="beta" for_k8s_version="v1.27" >}}
 
-Consider using one of the [client libraries](/docs/reference/using-api/client-libraries/)
-if you are writing an application using the Kubernetes API.
+Kubernetes offers beta support for aggregated discovery, publishing
+all resources supported by a cluster through two endpoints (`/api` and
+`/apis`). Requesting this
+endpoint drastically reduces the number of requests sent to fetch the
+discovery data from the cluster. You can access the data by
+requesting the respective endpoints with an `Accept` header indicating
+the aggregated discovery resource:
+`Accept: application/json;v=v2beta1;g=apidiscovery.k8s.io;as=APIGroupDiscoveryList`.
+
+Without indicating the resource type using the `Accept` header, the default
+response for the `/api` and `/apis` endpoint is an unaggregated discovery
+document.
+
+The [discovery document](https://github.com/kubernetes/kubernetes/blob/release-v{{< skew currentVersion >}}/api/discovery/aggregated_v2beta1.json)
+for the built-in resources can be found in the Kubernetes GitHub repository.
+This Github document can be used as a reference of the base set of the available resources
+if a Kubernetes cluster is not available to query.
+
+The endpoint also supports ETag and protobuf encoding.
+
+### Unaggregated discovery
+
+Without discovery aggregation, discovery is published in levels, with the root
+endpoints publishing discovery information for downstream documents.
+
+A list of all group versions supported by a cluster is published at
+the `/api` and `/apis` endpoints. Example:
+
+```
+{
+  "kind": "APIGroupList",
+  "apiVersion": "v1",
+  "groups": [
+    {
+      "name": "apiregistration.k8s.io",
+      "versions": [
+        {
+          "groupVersion": "apiregistration.k8s.io/v1",
+          "version": "v1"
+        }
+      ],
+      "preferredVersion": {
+        "groupVersion": "apiregistration.k8s.io/v1",
+        "version": "v1"
+      }
+    },
+    {
+      "name": "apps",
+      "versions": [
+        {
+          "groupVersion": "apps/v1",
+          "version": "v1"
+        }
+      ],
+      "preferredVersion": {
+        "groupVersion": "apps/v1",
+        "version": "v1"
+      }
+    },
+    ...
+}
+```
+
+Additional requests are needed to obtain the discovery document for each group version at
+`/apis/<group>/<version>` (for example:
+`/apis/rbac.authorization.k8s.io/v1alpha1`), which advertises the list of
+resources served under a particular group version. These endpoints are used by
+kubectl to fetch the list of resources supported by a cluster.
 
 <!-- body -->
 
-## OpenAPI specification {#api-specification}
+<a id="#api-specification" />
 
-Complete API details are documented using [OpenAPI](https://www.openapis.org/).
+## OpenAPI interface definition
 
+For details about the OpenAPI specifications, see the [OpenAPI documentation](https://www.openapis.org/).
+
+Kubernetes serves both OpenAPI v2.0 and OpenAPI v3.0. OpenAPI v3 is the
+preferred method of accessing the OpenAPI because it offers a more comprehensive
+(lossless) representation of Kubernetes resources. Due to limitations of OpenAPI
+version 2, certain fields are dropped from the published OpenAPI including but not
+limited to `default`, `nullable`, `oneOf`.
 ### OpenAPI V2
 
 The Kubernetes API server serves an aggregated OpenAPI v2 spec via the
@@ -74,11 +192,6 @@ request headers as follows:
   </tbody>
 </table>
 
-Kubernetes implements an alternative Protobuf based serialization format that
-is primarily intended for intra-cluster communication. For more information
-about this format, see the [Kubernetes Protobuf serialization](https://git.k8s.io/design-proposals-archive/api-machinery/protobuf.md) design proposal and the
-Interface Definition Language (IDL) files for each schema located in the Go
-packages that define the API objects.
 
 ### OpenAPI V3
 
@@ -149,7 +262,20 @@ Refer to the table below for accepted request headers.
   </tbody>
 </table>
 
-A Golang implementation to fetch the OpenAPI V3 is provided in the package `k8s.io/client-go/openapi3`.
+A Golang implementation to fetch the OpenAPI V3 is provided in the package
+[`k8s.io/client-go/openapi3`](https://pkg.go.dev/k8s.io/client-go/openapi3).
+
+Kubernetes {{< skew currentVersion >}} publishes
+OpenAPI v2.0 and v3.0; there are no plans to support 3.1 in the near future.
+
+### Protobuf serialization
+
+Kubernetes implements an alternative Protobuf based serialization format that
+is primarily intended for intra-cluster communication. For more information
+about this format, see the [Kubernetes Protobuf serialization](https://git.k8s.io/design-proposals-archive/api-machinery/protobuf.md)
+design proposal and the
+Interface Definition Language (IDL) files for each schema located in the Go
+packages that define the API objects.
 
 ## Persistence
 
@@ -238,8 +364,6 @@ ways that require deleting all existing alpha objects prior to upgrade.
 Refer to [API versions reference](/docs/reference/using-api/#api-versioning)
 for more details on the API version level definitions.
 
-
-
 ## API Extension
 
 The Kubernetes API can be extended in one of two ways:

content/en/docs/contribute/style/style-guide.md

@@ -116,17 +116,20 @@ The copy is called a "fork". | The copy is called a "fork."
 
 ## Inline code formatting
 
-### Use code style for inline code, commands, and API objects {#code-style-inline-code}
+### Use code style for inline code, commands {#code-style-inline-code}
 
 For inline code in an HTML document, use the `<code>` tag. In a Markdown
-document, use the backtick (`` ` ``).
+document, use the backtick (`` ` ``). However, API kinds such as StatefulSet
+or ConfigMap are written verbatim (no backticks); this allows using possessive
+apostrophes.
 
 {{< table caption = "Do and Don't - Use code style for inline code, commands, and API objects" >}}
 Do | Don't
 :--| :-----
-The `kubectl run` command creates a `Pod`. | The "kubectl run" command creates a pod.
-The kubelet on each node acquires a `Lease`… | The kubelet on each node acquires a lease…
-A `PersistentVolume` represents durable storage… | A Persistent Volume represents durable storage…
+The `kubectl run` command creates a Pod. | The "kubectl run" command creates a Pod.
+The kubelet on each node acquires a Lease… | The kubelet on each node acquires a `Lease`…
+A PersistentVolume represents durable storage… | A `PersistentVolume` represents durable storage…
+The CustomResourceDefinition's `.spec.group` field… | The `CustomResourceDefinition.spec.group` field…
 For declarative management, use `kubectl apply`. | For declarative management, use "kubectl apply".
 Enclose code samples with triple backticks. (\`\`\`)| Enclose code samples with any other syntax.
 Use single backticks to enclose inline code. For example, `var example = true`. | Use two asterisks (`**`) or an underscore (`_`) to enclose inline code. For example, **var example = true**.
@@ -191,37 +194,60 @@ Set the value of `image` to nginx:1.16. | Set the value of `image` to `nginx:1.1
 Set the value of the `replicas` field to 2. | Set the value of the `replicas` field to `2`.
 {{< /table >}}
 
+However, consider quoting values where there is a risk that readers might confuse the value
+with an API kind.
+
 ## Referring to Kubernetes API resources
 
 This section talks about how we reference API resources in the documentation.
 
 ### Clarification about "resource"
 
-Kubernetes uses the word "resource" to refer to API resources, such as `pod`,
-`deployment`, and so on. We also use "resource" to talk about CPU and memory
-requests and limits. Always refer to API resources as "API resources" to avoid
-confusion with CPU and memory resources.
+Kubernetes uses the word _resource_ to refer to API resources. For example,
+the URL path `/apis/apps/v1/namespaces/default/deployments/my-app` represents a
+Deployment named "my-app" in the "default"
+{{< glossary_tooltip text="namespace" term_id="namespace" >}}. In HTTP jargon,
+{{< glossary_tooltip text="namespace" term_id="namespace" >}} is a resource -
+the same way that all web URLs identify a resource.
+
+Kubernetes documentation also uses "resource" to talk about CPU and memory
+requests and limits. It's very often a good idea to refer to API resources
+as "API resources"; that helps to avoid confusion with CPU and memory resources,
+or with other kinds of resource.
+
+If you are using the lowercase plural form of a resource name, such as
+`deployments` or `configmaps`, provide extra written context to help readers
+understand what you mean. If you are using the term in a context where the
+UpperCamelCase name could work too, and there is a risk of ambiguity,
+consider using the API kind in UpperCamelCase.
 
 ### When to use Kubernetes API terminologies
 
 The different Kubernetes API terminologies are:
 
-- Resource type: the name used in the API URL (such as `pods`, `namespaces`)
-- Resource: a single instance of a resource type (such as `pod`, `secret`)
-- Object: a resource that serves as a "record of intent". An object is a desired
+- _API kinds_: the name used in the API URL (such as `pods`, `namespaces`).
+  API kinds are sometimes also called _resource types_.
+- _API resource_: a single instance of an API kind (such as `pod`, `secret`).
+- _Object_: a resource that serves as a "record of intent". An object is a desired
   state for a specific part of your cluster, which the Kubernetes control plane tries to maintain.
+  All objects in the Kubernetes API are also resources.
 
-Always use "resource" or "object" when referring to an API resource in docs.
-For example, use "a `Secret` object" over just "a `Secret`".
+For clarity, you can add "resource" or "object" when referring to an API resource in Kubernetes
+documentation.
+An example: write "a Secret object" instead of "a Secret".
+If it is clear just from the capitalization, you don't need to add the extra word.
+
+Consider rephrasing when that change helps avoid misunderstandings. A common situation is
+when you want to start a sentence with an API kind, such as “Secret”; because English
+and other languages capitalize at the start of sentences, readers cannot tell whether you
+mean the API kind or the general concept. Rewording can help.
 
 ### API resource names
 
 Always format API resource names using [UpperCamelCase](https://en.wikipedia.org/wiki/Camel_case),
-also known as PascalCase, and code formatting.
-
-For inline code in an HTML document, use the `<code>` tag. In a Markdown document, use the backtick (`` ` ``).
+also known as PascalCase. Do not write API kinds with code formatting.
 
-Don't split an API object name into separate words. For example, use `PodTemplateList`, not Pod Template List.
+Don't split an API object name into separate words. For example, use PodTemplateList, not Pod Template List.
 
 For more information about PascalCase and code formatting, please review the related guidance on
 [Use upper camel case for API objects](/docs/contribute/style/style-guide/#use-upper-camel-case-for-api-objects)
@@ -237,7 +263,7 @@ guidance on [Kubernetes API terminology](/docs/reference/using-api/api-concepts/
 {{< table caption = "Do and Don't - Don't include the command prompt" >}}
 Do | Don't
 :--| :-----
-kubectl get pods | $ kubectl get pods
+`kubectl get pods` | `$ kubectl get pods`
 {{< /table >}}
 
 ### Separate commands from output

content/en/docs/reference/using-api/cel.md

@@ -55,10 +55,12 @@ Example CEL expressions:
 | `has(self.expired) && self.created + self.ttl < self.expired`                      | Validate that 'expired' date is after a 'create' date plus a 'ttl' duration       |
 | `self.health.startsWith('ok')`                                                     | Validate a 'health' string field has the prefix 'ok'                              |
 | `self.widgets.exists(w, w.key == 'x' && w.foo < 10)`                               | Validate that the 'foo' property of a listMap item with a key 'x' is less than 10 |
-| `type(self) == string ? self == '99%' : self == 42`                                | Validate an int-or-string field for both the int and string cases             |
+| `type(self) == string ? self == '99%' : self == 42`                                | Validate an int-or-string field for both the int and string cases                 |
 | `self.metadata.name == 'singleton'`                                                | Validate that an object's name matches a specific value (making it a singleton)   |
 | `self.set1.all(e, !(e in self.set2))`                                              | Validate that two listSets are disjoint                                           |
 | `self.names.size() == self.details.size() && self.names.all(n, n in self.details)` | Validate the 'details' map is keyed by the items in the 'names' listSet           |
+| `self.details.all(key, key.matches('^[a-zA-Z]*$')`                                 | Validate the keys of the 'details' map                                            |
+| `self.details.all(key, self.details[key].matches('^[a-zA-Z]*$')`                   | Validate the values of the 'details' map                                          |
 {{< /table >}}
 
 ## CEL options, language features, and libraries

content/en/docs/tutorials/kubernetes-basics/update/update-intro.html

@@ -133,7 +133,7 @@ <h3>Update the version of the app</h3>
                and look for the <code>Image</code> field:</p>
                <p><code><b>kubectl describe pods</b></code></p>
                <p>To update the image of the application to version 2, use the <code>set image</code> subcommand, followed by the deployment name and the new image version:</p>
-               <p><code><b>kubectl set image deployments/kubernetes-bootcamp kubernetes-bootcamp=jocatalin/kubernetes-bootcamp:v2</b></code></p>
+               <p><code><b>kubectl set image deployments/kubernetes-bootcamp kubernetes-bootcamp=docker.io/jocatalin/kubernetes-bootcamp:v2</b></code></p>
                <p>The command notified the Deployment to use a different image for your app and initiated a rolling update. Check the status of the new Pods, and view the old one terminating with the <code>get pods</code> subcommand:</p>
                <p><code><b>kubectl get pods</b></code></p>
             </div>

content/en/examples/access/validating-admission-policy-audit-annotation.yaml

@@ -11,6 +11,8 @@ spec:
       operations:  ["CREATE", "UPDATE"]
       resources:   ["deployments"]
   validations:
-    - key: "high-replica-count"
-      expression: "object.spec.replicas > 50"
+    - expression: "object.spec.replicas > 50"
       messageExpression: "'Deployment spec.replicas set to ' + string(object.spec.replicas)"
+  auditAnnotations:
+    - key: "high-replica-count"
+      valueExpression: "'Deployment spec.replicas set to ' + string(object.spec.replicas)"