diff --git a/content/en/docs/concepts/overview/kubernetes-api.md b/content/en/docs/concepts/overview/kubernetes-api.md
index f7e6da3d86..c0306c3084 100644
--- a/content/en/docs/concepts/overview/kubernetes-api.md
+++ b/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.
-Consider using one of the [client libraries](/docs/reference/using-api/client-libraries/)
-if you are writing an application 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" >}}
+
+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/` 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.
+also known as PascalCase. Do not write API kinds with code formatting.
-For inline code in an HTML document, use the `
` tag. In a Markdown document, use the backtick (`` ` ``).
-
-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
diff --git a/content/en/docs/reference/using-api/cel.md b/content/en/docs/reference/using-api/cel.md
index 4be0fab37b..fd6460ea78 100644
--- a/content/en/docs/reference/using-api/cel.md
+++ b/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
diff --git a/content/en/docs/tutorials/kubernetes-basics/update/update-intro.html b/content/en/docs/tutorials/kubernetes-basics/update/update-intro.html
index f151f5a8e2..28e7681af4 100644
--- a/content/en/docs/tutorials/kubernetes-basics/update/update-intro.html
+++ b/content/en/docs/tutorials/kubernetes-basics/update/update-intro.html
@@ -133,7 +133,7 @@ description: |-
and look for the
Image
field:
kubectl describe pods
To update the image of the application to version 2, use the set image
subcommand, followed by the deployment name and the new image version:
kubectl set image deployments/kubernetes-bootcamp kubernetes-bootcamp=jocatalin/kubernetes-bootcamp:v2
kubectl set image deployments/kubernetes-bootcamp kubernetes-bootcamp=docker.io/jocatalin/kubernetes-bootcamp:v2
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 get pods
subcommand:
kubectl get pods
生成事件所对应的审计级别。
@@ -58,7 +60,9 @@ Event 结构包含可出现在 API 审计日志中的所有信息。k8s.io/apimachinery/pkg/types.UID
为每个请求所生成的唯一审计 ID。
@@ -70,7 +74,9 @@ Event 结构包含可出现在 API 审计日志中的所有信息。- + 生成此事件时请求的处理阶段。
- + requestURI 是客户端发送到服务器端的请求 URI。
user
[必需]authentication/v1.UserInfo
+authentication/v1.UserInfo
- + 关于认证用户的信息。
impersonatedUser
authentication/v1.UserInfo
+authentication/v1.UserInfo
- + 关于所伪装(impersonated)的用户的信息。
userAgent
string
- + userAgent 中记录客户端所报告的用户代理(User Agent)字符串。 注意 userAgent 信息是由客户端提供的,一定不要信任。
@@ -181,21 +194,25 @@ Note: All but the last IP can be arbitrarily set by the client.- + 此请求所指向的对象引用。对于 List 类型的请求或者非资源请求,此字段可忽略。
responseStatus
meta/v1.Status
+meta/v1.Status
- + For non-status type error responses, this will be auto-populated with the error Message. + --> 响应的状态,当 responseObject 不是 Status 类型时被赋值。 对于成功的请求,此字段仅包含 code 和 statusSuccess。 对于非 Status 类型的错误响应,此字段会被自动赋值为出错信息。 @@ -215,15 +232,13 @@ Note: All but the last IP can be arbitrarily set by the client. Omitted for non-resource requests. Only logged at Request Level and higher. --> 来自请求的 API 对象,以 JSON 格式呈现。requestObject 在请求中按原样记录 - (可能会采用 JSON 重新编码),之后会进入版本转换、默认值填充、准入控制以及 - 配置信息合并等阶段。此对象为外部版本化的对象类型,甚至其自身可能并不是一个 - 合法的对象。对于非资源请求,此字段被忽略。 + (可能会采用 JSON 重新编码),之后会进入版本转换、默认值填充、准入控制以及配置信息合并等阶段。 + 此对象为外部版本化的对象类型,甚至其自身可能并不是一个合法的对象。对于非资源请求,此字段被忽略。 只有当审计级别为 Request 或更高的时候才会记录。
responseObject
k8s.io/apimachinery/pkg/runtime.Unknown
requestReceivedTimestamp
meta/v1.MicroTime
+meta/v1.MicroTime
请求到达 API 服务器时的时间。
@@ -254,11 +270,13 @@ Note: All but the last IP can be arbitrarily set by the client.stageTimestamp
meta/v1.MicroTime
+meta/v1.MicroTime
- + 请求到达当前审计阶段时的时间。
kind
EventList
metadata
meta/v1.ListMeta
+meta/v1.ListMeta
kind
Policy
metadata
meta/v1.ObjectMeta
+meta/v1.ObjectMeta
-
+
包含 metadata
字段是为了便于与 API 基础设施之间实现互操作。
- 字段 rules 设置请求要被记录的审计级别(level)。 每个请求可能会与多条规则相匹配;发生这种状况时遵从第一条匹配规则。 - 默认的审计级别是 None,不过可以在列表的末尾使用一条全抓(catch-all)规则 - 重载其设置。 + 默认的审计级别是 None,不过可以在列表的末尾使用一条全抓(catch-all)规则重载其设置。 列表中的规则(PolicyRule)是严格有序的。
omitManagedFields
kind
PolicyList
metadata
meta/v1.ListMeta
+meta/v1.ListMeta
string
core
API 组。
例如:
-pods
匹配 Pod;pods/log
匹配 Pod 的 log 子资源;* 匹配所有资源及其子资源;
pods/*
匹配 Pod 的所有子资源;resources
是此规则所适用的资源的列表。
例如:
+pods
匹配 Pod。pods/log
匹配 Pod 的 log 子资源。* 匹配所有资源及其子资源。
pods/*
匹配 Pod 的所有子资源。*/scale
匹配所有的 scale 子资源。- 如果存在通配符,则合法性检查逻辑会确保 resources 中的条目不会彼此重叠。 -
-- 空的列表意味着规则适用于该 API 组中的所有资源及其子资源。 -
+ +如果存在通配符,则合法性检查逻辑会确保 resources 中的条目不会彼此重叠。
+空的列表意味着规则适用于该 API 组中的所有资源及其子资源。
string
字段 apiGroup 给出包含所引用对象的 API 组的名称。
空字符串代表 core
API 组。
@@ -634,7 +655,9 @@ ObjectReference 包含的是用来检查或修改所引用对象时将需要的
string
字段 apiVersion 是包含所引用对象的 API 组的版本。
@@ -685,7 +708,9 @@ PolicyRule 包含一个映射,基于元数据将请求映射到某审计级别Level
与此规则匹配的请求所对应的日志记录级别(Level)。
@@ -697,8 +722,10 @@ PolicyRule 包含一个映射,基于元数据将请求映射到某审计级别- + 根据身份认证所确定的用户名的列表,给出此规则所适用的用户。 空列表意味着适用于所有用户。
@@ -710,9 +737,11 @@ PolicyRule 包含一个映射,基于元数据将请求映射到某审计级别- + An empty list implies every user group. + --> 此规则所适用的用户组的列表。如果用户是所列用户组中任一用户组的成员,则视为匹配。 空列表意味着适用于所有用户组。
@@ -738,7 +767,9 @@ PolicyRule 包含一个映射,基于元数据将请求映射到某审计级别[]GroupResources
此规则所适用的资源类别列表。 空列表意味着适用于 API 组中的所有资源类别。 @@ -751,9 +782,11 @@ PolicyRule 包含一个映射,基于元数据将请求映射到某审计级别
- + An empty list implies every namespace. + --> 此规则所适用的名字空间列表。 空字符串("")意味着适用于非名字空间作用域的资源。 空列表意味着适用于所有名字空间。 @@ -766,20 +799,21 @@ PolicyRule 包含一个映射,基于元数据将请求映射到某审计级别
- 字段 nonResourceURLs 给出一组需要被审计的 URL 路径。
- 允许使用 *
s,但只能作为路径中最后一个完整分段。
- 例如:
-
nonResourceURLs
是一组需要被审计的 URL 路径。
+ 允许使用 *,但只能作为路径中最后一个完整分段。
+ 例如:
+
+ - "/metrics" - 记录对 API 服务器度量值(metrics)的所有请求;
+ - "/healthz*" - 记录所有健康检查。
omitManagedFields
bool
- - omitManagedFields 决定将请求和响应主体写入 API 审计日志时,是否省略其托管字段。 -
-omitManagedFields
bool
+
+omitManagedFields
决定将请求和响应主体写入 API 审计日志时,是否省略其托管字段。
+
json
[必需]json
[必需]JSONOptions
[Alpha] json 包含 "json" 日志格式的选项。 +
[Alpha] json
包含 "json" 日志格式的选项。
只有 LoggingAlphaOptions 特性门控被启用时才可用。
字段 | 描述 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
splitStream [必需]+ | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
splitStream [必需]bool
|
@@ -135,7 +136,7 @@ LoggingConfiguration 包含日志选项。
字段 | 描述 | | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
format [必需]+ | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
format [必需]string
|
@@ -149,7 +150,7 @@ default value of format is `text` | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
flushFrequency [必需]+ | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
flushFrequency [必需]TimeOrMetaDuration
|
@@ -168,7 +169,7 @@ Ignored if the selected logging backend writes log messages without buffering. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
verbosity [必需]+ | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
verbosity [必需]VerbosityLevel
|
@@ -185,7 +186,7 @@ are always logged. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
vmodule [必需]+ | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
vmodule [必需]VModuleConfiguration
|
@@ -200,7 +201,7 @@ Only supported for "text" log format. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
options [必需]+ | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
options [必需]FormatOptions
|
@@ -324,12 +325,10 @@ TracingConfiguration provides versioned configuration for OpenTelemetry tracing
-->
TracingConfiguration 为 OpenTelemetry 追踪客户端提供版本化的配置信息。 -
|