[zh] improve validation wasm-pull-policy envoy-stats (#13227)

Signed-off-by: xin.li <xin.li@daocloud.io>
2023-05-23 09:21:07 +08:00 · 2023-05-23 09:21:07 +08:00 · 7614bd2d1e
parent 578711163e
commit 7614bd2d1e
3 changed files with 68 additions and 35 deletions
--- a/content/zh/docs/ops/common-problems/validation/index.md
+++ b/content/zh/docs/ops/common-problems/validation/index.md
@ -13,17 +13,20 @@ test: no

 ## 看似有效的配置不生效 {#valid-configuration-is-rejected}

-使用 [istioctl validate -f](/zh/docs/reference/commands/istioctl/#istioctl-validate) 以及 [istioctl analyze](/zh/docs/reference/commands/istioctl/#istioctl-analyze) 来获取更多为什么配置不生效的信息。使用和控制面版本相似的 _istioctl_ CLI 。
+使用 [istioctl validate -f](/zh/docs/reference/commands/istioctl/#istioctl-validate)
+以及 [istioctl analyze](/zh/docs/reference/commands/istioctl/#istioctl-analyze)
+来获取更多为什么配置不生效的信息。使用和控制面版本相似的 **istioctl** CLI。

-最常见的配置问题是关于 YAML 文件空格缩进以及数组符号 (`-`) 的错误。
+最常见的配置问题是关于 YAML 文件空格缩进以及数组符号（`-`）的错误。

-手动验证您的配置是否正确，当有必要的时候请参照 [Istio API 文档](/zh/docs/reference/config) 。
+手动验证您的配置是否正确，当有必要的时候请参照 [Istio API 文档](/zh/docs/reference/config)。

 ## 接受无效配置 {#invalid-configuration-is-accepted}

 验证存在正确的名为 `istio-validator-` 且后跟 `<revision>-` 的 `validatingwebhookconfiguration`，
 如果不是默认的修订版则后跟 Istio 系统命名空间（例如 `istio-validator-myrev-istio-system`）。
-有效配置的 `apiVersion`、`apiGroup` 和 `resource` 应列举在 `validatingwebhookconfiguration` 的 `webhooks` 部分。
+有效配置的 `apiVersion`、`apiGroup` 和 `resource` 应列举在 `validatingwebhookconfiguration`
+的 `webhooks` 部分。

 {{< text bash yaml >}}
 $ kubectl get validatingwebhookconfiguration istio-validator-istio-system -o yaml
@ -47,11 +50,11 @@ webhooks:
  - v1beta1
  - v1
  clientConfig:
-    # caBundle should be non-empty. This is periodically (re)patched
-    # every second by the webhook service using the ca-cert
-    # from the mounted service account secret.
+    # caBundle 应该是非空的。webhook
+    # 服务使用已安装服务帐户密码中的 ca-cert
+    # 每隔一秒定期（重新）修订一次。
    caBundle: LS0t...
-    # service corresponds to the Kubernetes service that implements the webhook
+    # service 对应实现 webhook 的 Kubernetes 服务
    service:
      name: istiod
      namespace: istio-system
@ -85,15 +88,20 @@ webhooks:
  timeoutSeconds: 10
 {{< /text >}}

-如果 `istio-validator-` webhook 不存在，那就验证 `global.configValidation` 安装选项是否被设为 `true`。
+如果 `istio-validator-` webhook 不存在，那就验证 `global.configValidation`
+安装选项是否被设为 `true`。

 校验配置如果失败会自动关闭。如果配置存在且作用范围正确，webhook 将被调用。
 在资源创建或更新的时候，如果 `caBundle` 缺失或证书错误，亦或网络连接问题都将会导致报错。
-如果你确信你的配置没有问题，webhook 没有被调用却看不到任何错误信息，你的集群配置肯定有问题。
+如果您确信您的配置没有问题，webhook 没有被调用却看不到任何错误信息，您的集群配置肯定有问题。

 ## 创建配置失败报错：x509 certificate errors {#x509-certificate-errors}

-`x509: certificate signed by unknown authority` 错误通常和 webhook 配置中的空 `caBundle` 有关，所以要确认它不为空 (请查阅[验证 webhook 配置](#invalid-configuration-is-accepted))。Istio 有意识地使用 `istio-validation` `configmap` 和根证书，调整了 webhook 配置。
+`x509: certificate signed by unknown authority` 错误通常和 webhook
+配置中的空 `caBundle` 有关，所以要确认它不为空
+（请查阅[验证 webhook 配置](#invalid-configuration-is-accepted)）。
+Istio 有意识地使用 `istio-validation` `configmap` 和根证书，调整了
+webhook 配置。

 1. 验证 `istio-pilot` Pod 是否在运行：

@ -131,7 +139,9 @@ webhooks:

 ## 创建配置报错：`no such hosts` 或 `no endpoints available` {#creating-configuration-fail}

-校验失败自动关闭。如果 `istiod` Pod 没有准备就绪，配置是不会被创建或者更新的，在下面的例子里您可以看到关于 `no endpoints available` 的错误信息。
+校验失败自动关闭。如果 `istiod` Pod 没有准备就绪，
+配置是不会被创建或者更新的，在下面的例子里您可以看到关于
+`no endpoints available` 的错误信息。

 检查 `istiod` Pod 是否运行，并且检查 endpoint 是否准备就绪。

@ -147,7 +157,8 @@ NAME           ENDPOINTS                          AGE
 istiod         10.48.6.108:15014,10.48.6.108:443   3d
 {{< /text >}}

-如果 Pod 或者 endpoint 尚未准备就绪，请检查 Pod 日志和任何导致 webhook Pod 无法启动的异常状态以及服务流量。
+如果 Pod 或者 endpoint 尚未准备就绪，请检查 Pod 日志和任何导致
+webhook Pod 无法启动的异常状态以及服务流量。

 {{< text bash >}}
 $ for pod in $(kubectl -n istio-system get pod -lapp=istiod -o jsonpath='{.items[*].metadata.name}'); do \
--- a/content/zh/docs/ops/configuration/extensibility/wasm-pull-policy/index.md
+++ b/content/zh/docs/ops/configuration/extensibility/wasm-pull-policy/index.md
@ -12,7 +12,8 @@ status: Alpha

 [WasmPlugin API](/zh/docs/reference/config/proxy_extensions/wasm-plugin)
 提供了一种[将 Wasm 模块分发给](/zh/docs/tasks/extensibility/wasm-module-distribution)代理的方法。
-由于每个代理将从远程镜像仓库或 HTTP 服务器中拉取 Wasm 模块，所以了解 Istio 如何选择拉取模块的机制在可用性和性能方面都很重要。
+由于每个代理将从远程镜像仓库或 HTTP 服务器中拉取 Wasm 模块，所以了解
+Istio 如何选择拉取模块的机制在可用性和性能方面都很重要。

 ## 镜像拉取策略和异常 {#image-pull-policy-and-exceptions}

@ -20,27 +21,37 @@ status: Alpha
 [WasmPlugin](/zh/docs/reference/config/proxy_extensions/wasm-plugin/#WasmPlugin)
 也有`IfNotPresent` 和 `Always` 的概念，这分别意味着“使用缓存模块”和“不管缓存而始终拉取模块”。

-用户使用 `ImagePullPolicy` 字段显式配置 Wasm 模块检索的行为。但是，在以下场景中 Istio 可以覆盖用户提供的行为：
+用户使用 `ImagePullPolicy` 字段显式配置 Wasm 模块检索的行为。
+但是，在以下场景中 Istio 可以覆盖用户提供的行为：

-1. 如果用户在 [WasmPlugin](/zh/docs/reference/config/proxy_extensions/wasm-plugin/#WasmPlugin) 中设置 `sha256`，则不管 `ImagePullPolicy`，使用 `IfNotPresent` 策略。
-1. 如果 `url` 字段指向一个 OCI 镜像且该字段有一个摘要后缀（例如 `gcr.io/foo/bar@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef`），则使用 `IfNotPresent` 策略。
+1. 如果用户在 [WasmPlugin](/zh/docs/reference/config/proxy_extensions/wasm-plugin/#WasmPlugin)
+   中设置 `sha256`，则不管 `ImagePullPolicy`，使用 `IfNotPresent` 策略。

-如果没有为某资源指定 `ImagePullPolicy`，则 Istio  默认为 `IfNotPresent` 行为。
-但是如果提供的 `url` 字段指定一个标记值为 `latest` 的 OCI 镜像，则 Istio 将使用 `Always` 行为。
+1. 如果 `url` 字段指向一个 OCI 镜像且该字段有一个摘要后缀（例如
+   `gcr.io/foo/bar@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef`），
+   则使用 `IfNotPresent` 策略。
+
+如果没有为某资源指定 `ImagePullPolicy`，则 Istio  默认为 `IfNotPresent`
+行为。但是如果提供的 `url` 字段指定一个标记值为 `latest` 的 OCI 镜像，则
+Istio 将使用 `Always` 行为。

 ## 缓存模块的生命周期 {#lifecycle-of-cached-modules}

-每个代理，无论是 Sidecar 代理还是网关，都会缓存 Wasm 模块。因此，缓存 Wasm 模块的生存期受相应 Pod 的生存期限制。
-此外，还有一种过期机制可以将代理内存占用量保持在最小：如果在某个时间段内未使用缓存的 Wasm 模块，则会清除该模块。
+每个代理，无论是 Sidecar 代理还是网关，都会缓存 Wasm 模块。因此，缓存
+Wasm 模块的生存期受相应 Pod 的生存期限制。此外，还有一种过期机制可以将代理内存占用量保持在最小：
+如果在某个时间段内未使用缓存的 Wasm 模块，则会清除该模块。

 这个过期行为可以通过 [pilot-proxy](/zh/docs/reference/commands/pilot-agent/#envvars)
-的环境变量 `WASM_MODULE_EXPIRY` 和 `WASM_PURGE_INTERVAL` 进行配置，具体包括过期的持续时间和检查过期的时间间隔。
+的环境变量 `WASM_MODULE_EXPIRY` 和 `WASM_PURGE_INTERVAL` 进行配置，
+具体包括过期的持续时间和检查过期的时间间隔。

 ## “始终”的含义 {#the-meaning-of-always}

-在 Kubernetes 中，`ImagePullPolicy: Always` 意味着每次创建 Pod 时都会直接从其镜像源中拉取镜像。
-每次新的 Pod 启动时，Kubernetes 就会重新拉取新的镜像。
+在 Kubernetes 中，`ImagePullPolicy: Always` 意味着每次创建
+Pod 时都会直接从其镜像源中拉取镜像。每次新的 Pod 启动时，Kubernetes
+就会重新拉取新的镜像。

-对于 `WasmPlugin`，`ImagePullPolicy: Always` 意味着每次创建或更改相应的 `WasmPlugin` Kubernetes 资源时，Istio 将直接从其镜像源中拉取镜像。
-请注意，当使用 `Always` 策略时，`spec` 和 `metadata` 中的变更都会触发 Wasm 模块的拉取。
+对于 `WasmPlugin`，`ImagePullPolicy: Always` 意味着每次创建或更改相应的
+`WasmPlugin` Kubernetes 资源时，Istio 将直接从其镜像源中拉取镜像。请注意，当使用
+`Always` 策略时，`spec` 和 `metadata` 中的变更都会触发 Wasm 模块的拉取。
 这可能意味着在 Pod 的生命周期和单个代理的生命周期内，会多次从镜像源中拉取镜像。
--- a/content/zh/docs/ops/configuration/telemetry/envoy-stats/index.md
+++ b/content/zh/docs/ops/configuration/telemetry/envoy-stats/index.md
@ -12,7 +12,8 @@ test: yes
 Envoy 代理收集了关于网络流量的详细统计信息。

 Envoy 的统计信息只覆盖了特定 Envoy 实例的流量。参考[可观测性](/zh/docs/tasks/observability/)
-了解关于服务级别的 Istio 遥测方面的内容。这些由 Envoy 代理产生的统计数据记录能够提供更多关于 Pod 实例的具体信息。
+了解关于服务级别的 Istio 遥测方面的内容。这些由 Envoy 代理产生的统计数据记录能够提供更多关
+Pod 实例的具体信息。

 查看某个 Pod 的统计信息：

@ -20,7 +21,8 @@ Envoy 的统计信息只覆盖了特定 Envoy 实例的流量。参考[可观测
 $ kubectl exec "$POD" -c istio-proxy -- pilot-agent request GET stats
 {{< /text >}}

-Envoy 会生成与 Pod 行为相关的统计数据，并通过代理函数来限定统计范围。参考示例包括：
+Envoy 会生成与 Pod 行为相关的统计数据，并通过代理函数来限定统计范围。
+参考示例包括：

 - [上游连接](https://www.envoyproxy.io/docs/envoy/latest/configuration/upstream/cluster_manager/cluster_stats)
 - [监听器](https://www.envoyproxy.io/docs/envoy/latest/configuration/listeners/stats)
@ -28,7 +30,8 @@ Envoy 会生成与 Pod 行为相关的统计数据，并通过代理函数来限
 - [TCP 代理](https://www.envoyproxy.io/docs/envoy/latest/configuration/listeners/network_filters/tcp_proxy_filter#statistics)
 - [路由](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/router_filter.html?highlight=vhost#statistics)

-Istio 默认配置下 Envoy 只会记录最小化的统计信息，以减少代理服务器的整体 CPU 和内存占用情况。缺省的关键词集合有：
+Istio 默认配置下 Envoy 只会记录最小化的统计信息，
+以减少代理服务器的整体 CPU 和内存占用情况。缺省的关键词集合有：

 - `cluster_manager`
 - `listener_manager`
@ -36,16 +39,21 @@ Istio 默认配置下 Envoy 只会记录最小化的统计信息，以减少代
 - `cluster.xds-grpc`

 要查看关于统计数据收集的 Envoy 配置，可以使用
-[`istioctl proxy-config bootstrap`](/zh/docs/reference/commands/istioctl/#istioctl-proxy-config-bootstrap) 命令，还可以参考
-[深入研究 Envoy 配置](/zh/docs/ops/diagnostic-tools/proxy-cmd/#deep-dive-into-envoy-configuration)。
+[`istioctl proxy-config bootstrap`](/zh/docs/reference/commands/istioctl/#istioctl-proxy-config-bootstrap)
+命令，还可以参考[深入研究 Envoy 配置](/zh/docs/ops/diagnostic-tools/proxy-cmd/#deep-dive-into-envoy-configuration)。
 Envoy 只收集在 `stats_matcher` JSON 字段中能匹配上 `inclusion_list` 的统计数据。

 {{< tip >}}
-注意：Envoy 统计数据的名称由组成 Envoy 的不同配置而导致其拥有不同的名称。因此，由 Istio 管理的 Envoy 的统计数据暴露的名称会受到 Istio 配置行为的影响。
-如果您基于 Envoy 建立或者维护仪表盘或者告警，**强烈建议**您在**升级 Istio 之前**先在[金丝雀环境](/zh/docs/setup/upgrade/canary/index.md)检查统计信息。
+注意：Envoy 统计数据的名称由组成 Envoy 的不同配置而导致其拥有不同的名称。因此，
+由 Istio 管理的 Envoy 的统计数据暴露的名称会受到 Istio 配置行为的影响。
+如果您基于 Envoy 建立或者维护仪表盘或者告警，**强烈建议**您在**升级 Istio
+之前**先在[金丝雀环境](/zh/docs/setup/upgrade/canary/index.md)检查统计信息。
 {{< /tip >}}

-想让 Istio 代理能够记录更多的统计信息，您可以在您的网格配置中添加 [`ProxyConfig.ProxyStatsMatcher`](/zh/docs/reference/config/istio.mesh.v1alpha1/#ProxyStatsMatcher)。例如，为了全局启用断路器、请求重试、上游连接和请求超时的统计数据，您可以指定如下的数据统计的匹配配置：
+想让 Istio 代理能够记录更多的统计信息，您可以在您的网格配置中添加
+[`ProxyConfig.ProxyStatsMatcher`](/zh/docs/reference/config/istio.mesh.v1alpha1/#ProxyStatsMatcher)。
+例如，为了全局启用断路器、请求重试、上游连接和请求超时的统计数据，
+您可以指定如下的数据统计的匹配配置：

 {{< tip >}}
 为了能加载数据统计的匹配配置，代理需要重新启动。
@ -83,5 +91,8 @@ metadata:
 {{< /text >}}

 {{< tip >}}
-注意：如果您使用 `sidecar.istio.io/statsInclusionPrefixes`、`sidecar.istio.io/statsInclusionRegexps` 和 `sidecar.istio.io/statsInclusionSuffixes`，考虑需要切换到基于 `ProxyConfig` 配置，因此它提供了一个全局默认并且统一的方法去重载 Gateway 和 Sidecar 代理。
+注意：如果您使用 `sidecar.istio.io/statsInclusionPrefixes`、
+`sidecar.istio.io/statsInclusionRegexps` 和 `sidecar.istio.io/statsInclusionSuffixes`，
+考虑需要切换到基于 `ProxyConfig` 配置，因此它提供了一个全局默认并且统一的方法去重载
+Gateway 和 Sidecar 代理。
 {{< /tip >}}