[zh] sync 1.24 concepts-7

2022-05-10 09:48:34 +08:00 · 2022-05-10 09:48:34 +08:00 · 05b868e703
parent 1bd0ade6a1
commit 05b868e703
3 changed files with 148 additions and 102 deletions
--- a/content/zh/docs/concepts/cluster-administration/system-logs.md
+++ b/content/zh/docs/concepts/cluster-administration/system-logs.md
@ -192,6 +192,82 @@ I1025 00:15:15.525108       1 example.go:116] "Example" data="This is text with
 second line.}
 ```

+<!-- 
+### Contextual Logging 
+-->
+### 上下文日志
+
+{{< feature-state for_k8s_version="v1.24" state="alpha" >}}
+
+<!-- 
+Contextual logging builds on top of structured logging. It is primarily about
+how developers use logging calls: code based on that concept is more flexible
+and supports additional use cases as described in the [Contextual Logging
+KEP](https://github.com/kubernetes/enhancements/tree/master/keps/sig-instrumentation/3077-contextual-logging). 
+-->
+上下文日志建立在结构化日志之上。
+它主要是关于开发人员如何使用日志记录调用：基于该概念的代码将更加灵活，
+并且支持在[结构化日志 KEP](https://github.com/kubernetes/enhancements/tree/master/keps/sig-instrumentation/3077-contextual-logging) 
+中描述的额外用例。
+
+<!-- 
+If developers use additional functions like `WithValues` or `WithName` in
+their components, then log entries contain additional information that gets
+passed into functions by their caller. 
+-->
+如果开发人员在他们的组件中使用额外的函数，比如 `WithValues` 或 `WithName`，
+那么日志条目将会包含额外的信息，这些信息会被调用者传递给函数。
+
+<!-- 
+Currently this is gated behind the `StructuredLogging` feature gate and
+disabled by default. The infrastructure for this was added in 1.24 without
+modifying components. The
+[`component-base/logs/example`](https://github.com/kubernetes/kubernetes/blob/v1.24.0-beta.0/staging/src/k8s.io/component-base/logs/example/cmd/logger.go)
+command demonstrates how to use the new logging calls and how a component
+behaves that supports contextual logging. 
+-->
+目前这一特性是由 `StructuredLogging` 特性门控所控制的，默认关闭。
+这个基础设施是在 1.24 中被添加的，并不需要修改组件。
+该 [`component-base/logs/example`](https://github.com/kubernetes/kubernetes/blob/v1.24.0-beta.0/staging/src/k8s.io/component-base/logs/example/cmd/logger.go)
+命令演示了如何使用新的日志记录调用以及组件如何支持上下文日志记录。
+
+```console
+$ cd $GOPATH/src/k8s.io/kubernetes/staging/src/k8s.io/component-base/logs/example/cmd/
+$ go run . --help
+...
+      --feature-gates mapStringBool  A set of key=value pairs that describe feature gates for alpha/experimental features. Options are:
+                                     AllAlpha=true|false (ALPHA - default=false)
+                                     AllBeta=true|false (BETA - default=false)
+                                     ContextualLogging=true|false (ALPHA - default=false)
+$ go run . --feature-gates ContextualLogging=true
+...
+I0404 18:00:02.916429  451895 logger.go:94] "example/myname: runtime" foo="bar" duration="1m0s"
+I0404 18:00:02.916447  451895 logger.go:95] "example: another runtime" foo="bar" duration="1m0s"
+```
+
+<!-- 
+The `example` prefix and `foo="bar"` were added by the caller of the function
+which logs the `runtime` message and `duration="1m0s"` value, without having to
+modify that function.
+
+With contextual logging disable, `WithValues` and `WithName` do nothing and log
+calls go through the global klog logger. Therefore this additional information
+is not in the log output anymore: 
+-->
+`example` 前缀和 `foo="bar"` 会被函数的调用者添加上，
+不需修改该函数，它就会记录 `runtime` 消息和 `duration="1m0s"` 值。
+
+禁用上下文日志后，`WithValues` 和 `WithName` 什么都不会做，
+并且会通过调用全局的 klog 日志记录器记录日志。
+因此，这些附加信息不再出现在日志输出中：
+
+```console
+$ go run . --feature-gates ContextualLogging=false
+...
+I0404 18:03:31.171945  452150 logger.go:94] "runtime" duration="1m0s"
+I0404 18:03:31.171962  452150 logger.go:95] "another runtime" duration="1m0s"
+```
+
 <!--
 ### JSON log format
 -->
@ -258,45 +334,6 @@ List of components currently supporting JSON format:
 * {{< glossary_tooltip term_id="kube-scheduler" text="kube-scheduler" >}}
 * {{< glossary_tooltip term_id="kubelet" text="kubelet" >}}

-<!--
-### Log sanitization
-->
-### 日志清洗    {#log-sanitization}
-
-{{< feature-state for_k8s_version="v1.20" state="alpha" >}}
-
-{{<warning >}}
-<!--
-Log sanitization might incur significant computation overhead and therefore should not be enabled in production.
-->
-日志清洗（Log Sanitization）可能会导致大量的计算开销，因此不应在生产环境中启用。
-{{< /warning >}}
-
-<!--
-The `--experimental-logging-sanitization` flag enables the klog sanitization filter.
-If enabled all log arguments are inspected for fields tagged as sensitive data (e.g. passwords, keys, tokens) and logging of these fields will be prevented.
-->
-`--experimental-logging-sanitization` 参数可用来启用 klog 清洗过滤器。
-如果启用后，将检查所有日志参数中是否有标记为敏感数据的字段（比如：密码，密钥，令牌），
-并且将阻止这些字段的记录。
-
-<!--
-List of components currently supporting log sanitization:
-->
-当前支持日志清洗的组件列表：
-
-* kube-controller-manager
-* kube-apiserver
-* kube-scheduler
-* kubelet
-
-{{< note >}}
-<!--
-The Log sanitization filter does not prevent user workload logs from leaking sensitive data.
-->
-日志清洗过滤器不会阻止用户工作负载日志泄漏敏感数据。
-{{< /note >}}
-
 <!--
 ### Log verbosity level

@ -347,11 +384,13 @@ The `logrotate` tool rotates logs daily, or once the log size is greater than 10
 <!--
 * Read about the [Kubernetes Logging Architecture](/docs/concepts/cluster-administration/logging/)
 * Read about [Structured Logging](https://github.com/kubernetes/enhancements/tree/master/keps/sig-instrumentation/1602-structured-logging)
+* Read about [Contextual Logging](https://github.com/kubernetes/enhancements/tree/master/keps/sig-instrumentation/3077-contextual-logging)
 * Read about [deprecation of klog flags](https://github.com/kubernetes/enhancements/tree/master/keps/sig-instrumentation/2845-deprecate-klog-specific-flags-in-k8s-components)
 * Read about the [Conventions for logging severity](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-instrumentation/logging.md)
 -->
 * 阅读 [Kubernetes 日志架构](/zh/docs/concepts/cluster-administration/logging/)
 * 阅读[结构化日志提案（英文）](https://github.com/kubernetes/enhancements/tree/master/keps/sig-instrumentation/1602-structured-logging)
+* 阅读[上下文日志提案（英文）](https://github.com/kubernetes/enhancements/tree/master/keps/sig-instrumentation/3077-contextual-logging)
 * 阅读 [klog 参数的废弃（英文）](https://github.com/kubernetes/enhancements/tree/master/keps/sig-instrumentation/2845-deprecate-klog-specific-flags-in-k8s-components)
 * 阅读[日志严重级别约定（英文）](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-instrumentation/logging.md)

--- a/content/zh/docs/concepts/containers/runtime-class.md
+++ b/content/zh/docs/concepts/containers/runtime-class.md
@ -113,18 +113,21 @@ RuntimeClass 资源当前只有两个重要的字段：RuntimeClass 名 (`metada
 对象定义如下所示：

 ```yaml
-apiVersion: node.k8s.io/v1  # RuntimeClass 定义于 node.k8s.io API 组
+# RuntimeClass 定义于 node.k8s.io API 组
+apiVersion: node.k8s.io/v1
 kind: RuntimeClass
 metadata:
-  name: myclass  # 用来引用 RuntimeClass 的名字
+  # 用来引用 RuntimeClass 的名字
  # RuntimeClass 是一个集群层面的资源
-handler: myconfiguration  # 对应的 CRI 配置的名称
+  name: myclass  
+# 对应的 CRI 配置的名称
+handler: myconfiguration
 ```

 <!--
 It is recommended that RuntimeClass write operations (create/update/patch/delete) be
-restricted to the cluster administrator. This is typically the default. See [Authorization
-Overview](/docs/reference/access-authn-authz/authorization/) for more details.
+restricted to the cluster administrator. This is typically the default. See 
+[Authorization Overview](/docs/reference/access-authn-authz/authorization/) for more details.
 -->
 {{< note >}}
 建议将 RuntimeClass 写操作（create、update、patch 和 delete）限定于集群管理员使用。
@ -134,13 +137,13 @@ Overview](/docs/reference/access-authn-authz/authorization/) for more details.
 <!--
 ## Usage

-Once RuntimeClasses are configured for the cluster, using them is very simple. Specify a
-`runtimeClassName` in the Pod spec. For example:
+Once RuntimeClasses are configured for the cluster, you can specify a
+`runtimeClassName` in the Pod spec to use it. For example:
 -->
 ## 使用说明  {#usage}

-一旦完成集群中 RuntimeClasses 的配置，使用起来非常方便。
-在 Pod spec 中指定 `runtimeClassName` 即可。例如:
+一旦完成集群中 RuntimeClasses 的配置，
+你可以在 Pod spec 中指定 `runtimeClassName` 来使用它。例如:

 ```yaml
 apiVersion: v1
@ -181,25 +184,7 @@ For more details on setting up CRI runtimes, see [CRI installation](/docs/setup/
 关于如何安装 CRI 运行时，请查阅
 [CRI 安装](/zh/docs/setup/production-environment/container-runtimes/)。

-#### dockershim
-
-<!--
-{{< feature-state for_k8s_version="v1.20" state="deprecated" >}}
-
-Dockershim is deprecated as of Kubernetes v1.20, and will be removed in v1.24. For more information on the deprecation,
-see [dockershim deprecation](/blog/2020/12/08/kubernetes-1-20-release-announcement/#dockershim-deprecation)
-->
-Dockershim 自 Kubernetes v1.20 起已弃用，并将在 v1.24 中删除。 
-有关弃用的更多信息查看 [dockershim 弃用](/blog/2020/12/08/kubernetes-1-20-release-announcement/#dockershim-deprecation)。
-
-<!--
-RuntimeClasses with dockershim must set the runtime handler to `docker`. Dockershim does not support
-custom configurable runtime handlers.
-->
-为 dockershim 设置 RuntimeClass 时，必须将运行时处理程序设置为 `docker`。
-Dockershim 不支持自定义的可配置的运行时处理程序。
-
-#### [containerd](https://containerd.io/)
+#### {{< glossary_tooltip term_id="containerd" >}}

 <!--
 Runtime handlers are configured through containerd's configuration at
@ -213,10 +198,10 @@ handler 需要配置在 runtimes 块中：
 ```

 <!--
-See the containerd [CRI Plugin Config Guide](https://github.com/containerd/containerd/blob/main/docs/cri/config.md) for more details.
+See containerd's [config documentation](https://github.com/containerd/cri/blob/master/docs/config.md)
+for more details:
 -->
-更详细信息，请查阅 containerd 
-[CRI 插件配置指南](https://github.com/containerd/cri/blob/master/docs/config.md)
+更详细信息，请查阅 containerd 的[配置指南](https://github.com/containerd/cri/blob/master/docs/config.md)

 #### [cri-o](https://cri-o.io/)

@ -278,8 +263,8 @@ by each.
 与 `nodeSelector` 一样，tolerations 也在 admission 阶段与 pod 的 tolerations 合并，取二者的并集。

 <!--
-To learn more about configuring the node selector and tolerations, see [Assigning Pods to
-Nodes](/docs/concepts/configuration/assign-pod-node/).
+To learn more about configuring the node selector and tolerations, see 
+[Assigning Pods to Nodes](/docs/concepts/configuration/assign-pod-node/).
 -->
 更多有关 node selector 和 tolerations 的配置信息，请查阅 
 [将 Pod 分派到节点](/zh/docs/concepts/scheduling-eviction/assign-pod-node/)。
@ -289,26 +274,21 @@ Nodes](/docs/concepts/configuration/assign-pod-node/).
 -->
 ### Pod 开销   {#pod-overhead}

-{{< feature-state for_k8s_version="v1.18" state="beta" >}}
+{{< feature-state for_k8s_version="v1.24" state="stable" >}}

 <!--
 You can specify _overhead_ resources that are associated with running a Pod. Declaring overhead allows
 the cluster (including the scheduler) to account for it when making decisions about Pods and resources.  
-To use Pod overhead, you must have the PodOverhead [feature gate](/docs/reference/command-line-tools-reference/feature-gates/)
-enabled (it is on by default).
 -->
 你可以指定与运行 Pod 相关的 _开销_ 资源。声明开销即允许集群（包括调度器）在决策 Pod 和资源时将其考虑在内。
-若要使用 Pod 开销特性，你必须确保 PodOverhead
-[特性门控](/zh/docs/reference/command-line-tools-reference/feature-gates/)
-处于启用状态（默认为启用状态）。

 <!--
-Pod overhead is defined in RuntimeClass through the `Overhead` fields. Through the use of these fields,
+Pod overhead is defined in RuntimeClass through the `overhead` field. Through the use of this field,
 you can specify the overhead of running pods utilizing this RuntimeClass and ensure these overheads
 are accounted for in Kubernetes.
 -->
 Pod 开销通过 RuntimeClass 的 `overhead` 字段定义。
-通过使用这些字段，你可以指定使用该 RuntimeClass 运行 Pod 时的开销并确保 Kubernetes 将这些开销计算在内。
+通过使用这个字段，你可以指定使用该 RuntimeClass 运行 Pod 时的开销并确保 Kubernetes 将这些开销计算在内。

 ## {{% heading "whatsnext" %}}

--- a/content/zh/docs/concepts/overview/kubernetes-api.md
+++ b/content/zh/docs/concepts/overview/kubernetes-api.md
@ -145,29 +145,63 @@ Kubernetes 为 API 实现了一种基于 Protobuf 的序列化格式，主要用

 ### OpenAPI V3

-{{< feature-state state="alpha"  for_k8s_version="v1.23" >}}
+{{< feature-state state="beta"  for_k8s_version="v1.24" >}}

 <!--
-Kubernetes v1.23 offers initial support for publishing its APIs as OpenAPI v3; this is an
-alpha feature that is disabled by default.
-You can enable the alpha feature by turning on the
+Kubernetes {{< param "version" >}} offers beta support for publishing its APIs as OpenAPI v3; this is a
+beta feature that is enabled by default.
+You can disable the beta feature by turning off the
 [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) named `OpenAPIV3`
 for the kube-apiserver component.
 -->
-Kubernetes v1.23 提供将其 API 以 OpenAPI v3 形式发布的初始支持；这一功能特性处于 Alpha
-状态，默认被禁用。
-你可以通过为 kube-apiserver 组件启用 `OpenAPIV3`
-[特性门控](/zh/docs/reference/command-line-tools-reference/feature-gates/)来启用此
-Alpha 特性。
+Kubernetes {{< param "version" >}} 提供将其 API 以 OpenAPI v3 形式发布的 beta 支持；
+这一功能特性处于 beta 状态，默认被开启。
+你可以通过为 kube-apiserver 组件关闭 `OpenAPIV3`
+[特性门控](/zh/docs/reference/command-line-tools-reference/feature-gates/)来禁用此 beta 特性。

 <!--
-With the feature enabled, the Kubernetes API server serves an
-aggregated OpenAPI v3 spec per Kubernetes group version at the
-`/openapi/v3/apis/<group>/<version>` endpoint. Please refer to the
-table below for accepted request headers.
+A discovery endpoint `/openapi/v3` is provided to see a list of all
+group/versions available. This endpoint only returns JSON. These group/versions
+are provided in the following format:
 -->
-特性被启用时，Kubernetes API 服务器会在端点 `/openapi/v3/apis/<group>/<version>`
-提供按 Kubernetes 组版本聚合的 OpenAPI v3 规范。
+发现端点 `/openapi/v3` 被提供用来查看可用的所有组、版本列表。
+此列表仅返回 JSON。这些组、版本以下面的格式提供：
+```json
+{
+    "paths": {
+        ...
+        "api/v1": {
+            "serverRelativeURL": "/openapi/v3/api/v1?hash=CC0E9BFD992D8C59AEC98A1E2336F899E8318D3CF4C68944C3DEC640AF5AB52D864AC50DAA8D145B3494F75FA3CFF939FCBDDA431DAD3CA79738B297795818CF"
+        },
+        "apis/admissionregistration.k8s.io/v1": {
+            "serverRelativeURL": "/openapi/v3/apis/admissionregistration.k8s.io/v1?hash=E19CC93A116982CE5422FC42B590A8AFAD92CDE9AE4D59B5CAAD568F083AD07946E6CB5817531680BCE6E215C16973CD39003B0425F3477CFD854E89A9DB6597"
+        },
+        ...
+}
+```
+
+<!-- 
+The relative URLs are pointing to immutable OpenAPI descriptions, in
+order to improve client-side caching. The proper HTTP caching headers
+are also set by the API server for that purpose (`Expires` to 1 year in
+the future, and `Cache-Control` to `immutable`). When an obsolete URL is
+used, the API server returns a redirect to the newest URL. 
+-->
+为了改进客户端缓存，相对的 URL 会指向不可变的 OpenAPI 描述。
+为了此目的，API 服务器也会设置正确的 HTTP 缓存标头
+（`Expires` 为未来 1 年，和 `Cache-Control` 为 `immutable`）。
+当一个过时的 URL 被使用时，API 服务器会返回一个指向最新 URL 的重定向。
+
+<!-- 
+The Kubernetes API server publishes an OpenAPI v3 spec per Kubernetes
+group version at the `/openapi/v3/apis/<group>/<version>?hash=<hash>`
+endpoint.
+
+Refer to the table below for accepted request headers. 
+-->
+Kubernetes API 服务器会在端点 `/openapi/v3/apis/<group>/<version>?hash=<hash>`
+发布一个 Kubernetes 组版本的 OpenAPI v3 规范。
+
 请参阅下表了解可接受的请求头部。

 <table>
@ -201,13 +235,6 @@ table below for accepted request headers.
  </tbody>
 </table>

-<!--
-A discovery endpoint `/openapi/v3` is provided to see a list of all
-group/versions available. This endpoint only returns JSON.
-->
-发现端点 `/openapi/v3` 被提供用来查看可用的所有组、版本列表。
-此列表仅返回 JSON。
-
 <!--
 ## API changes