From 05b868e7037c3373eab5638b15b65b35a8be16cd Mon Sep 17 00:00:00 2001 From: huangminjie Date: Tue, 10 May 2022 09:48:34 +0800 Subject: [PATCH] [zh] sync 1.24 concepts-7 --- .../cluster-administration/system-logs.md | 117 ++++++++++++------ .../docs/concepts/containers/runtime-class.md | 62 ++++------ .../docs/concepts/overview/kubernetes-api.md | 71 +++++++---- 3 files changed, 148 insertions(+), 102 deletions(-) diff --git a/content/zh/docs/concepts/cluster-administration/system-logs.md b/content/zh/docs/concepts/cluster-administration/system-logs.md index 8548c82310..164d416b9f 100644 --- 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.} ``` + +### 上下文日志 + +{{< feature-state for_k8s_version="v1.24" state="alpha" >}} + + +上下文日志建立在结构化日志之上。 +它主要是关于开发人员如何使用日志记录调用：基于该概念的代码将更加灵活， +并且支持在[结构化日志 KEP](https://github.com/kubernetes/enhancements/tree/master/keps/sig-instrumentation/3077-contextual-logging) +中描述的额外用例。 + + +如果开发人员在他们的组件中使用额外的函数，比如 `WithValues` 或 `WithName`， +那么日志条目将会包含额外的信息，这些信息会被调用者传递给函数。 + + +目前这一特性是由 `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" +``` + + +`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" +``` + @@ -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} - -{{< feature-state for_k8s_version="v1.20" state="alpha" >}} - -{{}} - -日志清洗（Log Sanitization）可能会导致大量的计算开销，因此不应在生产环境中启用。 -{{< /warning >}} - - -`--experimental-logging-sanitization` 参数可用来启用 klog 清洗过滤器。 -如果启用后，将检查所有日志参数中是否有标记为敏感数据的字段（比如：密码，密钥，令牌）， -并且将阻止这些字段的记录。 - - -当前支持日志清洗的组件列表： - -* kube-controller-manager -* kube-apiserver -* kube-scheduler -* kubelet - -{{< note >}} - -日志清洗过滤器不会阻止用户工作负载日志泄漏敏感数据。 -{{< /note >}} - * 阅读 [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) diff --git a/content/zh/docs/concepts/containers/runtime-class.md b/content/zh/docs/concepts/containers/runtime-class.md index 63e14b435c..11f8d83e86 100644 --- 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 ``` {{< note >}} 建议将 RuntimeClass 写操作（create、update、patch 和 delete）限定于集群管理员使用。 @@ -134,13 +137,13 @@ Overview](/docs/reference/access-authn-authz/authorization/) for more details. ## 使用说明 {#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 - - -Dockershim 自 Kubernetes v1.20 起已弃用，并将在 v1.24 中删除。 -有关弃用的更多信息查看 [dockershim 弃用](/blog/2020/12/08/kubernetes-1-20-release-announcement/#dockershim-deprecation)。 - - -为 dockershim 设置 RuntimeClass 时，必须将运行时处理程序设置为 `docker`。 -Dockershim 不支持自定义的可配置的运行时处理程序。 - -#### [containerd](https://containerd.io/) +#### {{< glossary_tooltip term_id="containerd" >}} -更详细信息，请查阅 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 合并，取二者的并集。 更多有关 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" >}} 你可以指定与运行 Pod 相关的 _开销_ 资源。声明开销即允许集群（包括调度器）在决策 Pod 和资源时将其考虑在内。 -若要使用 Pod 开销特性，你必须确保 PodOverhead -[特性门控](/zh/docs/reference/command-line-tools-reference/feature-gates/) -处于启用状态（默认为启用状态）。 Pod 开销通过 RuntimeClass 的 `overhead` 字段定义。 -通过使用这些字段，你可以指定使用该 RuntimeClass 运行 Pod 时的开销并确保 Kubernetes 将这些开销计算在内。 +通过使用这个字段，你可以指定使用该 RuntimeClass 运行 Pod 时的开销并确保 Kubernetes 将这些开销计算在内。 ## {{% heading "whatsnext" %}} diff --git a/content/zh/docs/concepts/overview/kubernetes-api.md b/content/zh/docs/concepts/overview/kubernetes-api.md index 61cf1a2c2e..52b9c32b1e 100644 --- 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 提供将其 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 特性。 -特性被启用时，Kubernetes API 服务器会在端点 `/openapi/v3/apis//` -提供按 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" + }, + ... +} +``` + + +为了改进客户端缓存，相对的 URL 会指向不可变的 OpenAPI 描述。 +为了此目的，API 服务器也会设置正确的 HTTP 缓存标头 +（`Expires` 为未来 1 年，和 `Cache-Control` 为 `immutable`）。 +当一个过时的 URL 被使用时，API 服务器会返回一个指向最新 URL 的重定向。 + + +Kubernetes API 服务器会在端点 `/openapi/v3/apis//?hash=` +发布一个 Kubernetes 组版本的 OpenAPI v3 规范。 + 请参阅下表了解可接受的请求头部。 @@ -201,13 +235,6 @@ table below for accepted request headers.
- -发现端点 `/openapi/v3` 被提供用来查看可用的所有组、版本列表。 -此列表仅返回 JSON。 -