From fb9821a069d5df940ec612e4f073a49224b6b804 Mon Sep 17 00:00:00 2001 From: Wilson Wu Date: Fri, 13 Dec 2024 16:45:08 +0800 Subject: [PATCH] Sync #16057 faq install and ambient install docs into Chinese --- .../faq/setup/install-method-selection.md | 31 ++++++------ content/zh/docs/ambient/install/helm/index.md | 43 ++++++++++++++++ .../zh/docs/ambient/install/istioctl/index.md | 50 +++++++++++++++++++ 3 files changed, 110 insertions(+), 14 deletions(-) diff --git a/content/zh/about/faq/setup/install-method-selection.md b/content/zh/about/faq/setup/install-method-selection.md index b03dcfcabc181..28f4377d45a3c 100644 --- a/content/zh/about/faq/setup/install-method-selection.md +++ b/content/zh/about/faq/setup/install-method-selection.md @@ -22,34 +22,37 @@ weight: 10 - `istioctl` 命令可能根据您的运行环境自动设置相关值，从而能够在不同的 Kubernetes 环境中进行不同的安装。 -1. [使用 istioctl 生成清单](/zh/docs/setup/install/istioctl/#generate-a-manifest-before-installation) +1. [使用 Helm 进行安装](/zh/docs/setup/install/helm/) - 生成 Kubernetes 的配置清单，并通过 `kubectl apply --prune` 应用到集群中， - 该方法适用于需要严格审查或者增加配置清单的情况。 + 允许轻松与基于 Helm 的工作流程集成并在升级期间自动进行资源修剪。 优点： - - 资源是由与 `istioctl install` 中使用相同的 `IstioOperator` API 生成的。 - - 使用提供了扩展的配置、自定义选项的 `IstioOperator` API。 + - 使用行业标准工具的熟悉方法。 + - Helm 原生发布和升级管理。 缺点： - - 一些在 `istioctl install` 中执行的未完成的检查将不会执行。 - - 与 `istioctl install` 相比，UX 的精简程度较低。 - - 错误报告不如 `istioctl install` 的错误报告详细、全面。 + - 与 `istioctl install` 相比，检查和验证更少。 + - 某些管理任务需要更多步骤并且复杂性更高。 + +1. 应用生成的 Kubernetes 清单 -1. [使用 Helm 安装](/zh/docs/setup/install/helm/) + - [使用 `istioctl` 生成 Kubernetes 清单](/zh/docs/setup/install/istioctl/#generate-a-manifest-before-installation) + - [使用 `helm` 生成 Kubernetes 清单](/zh/docs/setup/install/helm/#generate-a-manifest-before-installation) - 使用 Helm Chart 可以通过 Helm 的工作流程轻松的完成，并在升级的过程中自动清理资源。 + 此方法适用于需要严格审核或扩充输出清单，或存在第三方工具限制的情况。 优点： - - 使用熟悉、常用的行业标准工具。 - - Helm 原生的版本、升级管理。 + - 更容易与未使用 `helm` 或 `istioctl` 的工具集成。 + - 除了 `kubectl` 之外，不需要其他安装工具。 缺点： - - 相比于 `istioctl install`，检查较少。 - - 一些高权限任务需要更多步骤，并且具有更高的复杂性。 + - 不执行上述任一方法支持的安装时检查、环境检测或验证。 + - 不支持安装管理或升级功能。 + - 用户体验不够精简。 + - 安装过程中的错误报告不够完善。 这些安装方式的安装向导在 [Istio 安装页面](/zh/docs/setup/install)中。 diff --git a/content/zh/docs/ambient/install/helm/index.md b/content/zh/docs/ambient/install/helm/index.md index 9dae73a32d9f8..2816aee4f68cb 100644 --- a/content/zh/docs/ambient/install/helm/index.md +++ b/content/zh/docs/ambient/install/helm/index.md @@ -215,3 +215,46 @@ ztunnel-c2z4s 1/1 Running 0 10m {{< text syntax=bash snip_id=delete_system_namespace >}} $ kubectl delete namespace istio-system {{< /text >}} + +## 安装前生成清单 {#generate-a-manifest-before-installation} + +您可以在安装 Istio 之前使用 `helm template` 子命令为每个组件生成清单。 +例如，要为 `istiod` 组件生成可以使用 `kubectl` 安装的清单： + +{{< text syntax=bash snip_id=none >}} +$ helm template istiod istio/istiod -n istio-system --kube-version {Kubernetes version of target cluster} > istiod.yaml +{{< /text >}} + +生成的清单可用于检查具体安装了什么以及跟踪清单随时间的变化。 + +{{< tip >}} +您通常用于安装的任何其他标志或自定义值覆盖也应提供给 `helm template` 命令。 +{{< /tip >}} + +要安装上面生成的清单，它将在目标集群中创建 `istiod` 组件： + +{{< text syntax=bash snip_id=none >}} +$ kubectl apply -f istiod.yaml +{{< /text >}} + +{{< warning >}} +如果尝试使用 `helm template` 安装和管理 Istio，请注意以下注意事项： + +1. 必须手动创建 Istio 命名空间（默认为 `istio-system`）。 + +1. 资源可能未按照与 `helm install` 相同的依赖顺序进行安装 + +1. 此方法尚未作为 Istio 版本的一部分进行测试。 + +1. 虽然 `helm install` 会自动从 Kubernetes 上下文中检测特定于环境的设置， + 但 `helm template` 无法做到这一点，因为它是离线运行的， + 这可能会导致意外结果。特别是，如果您的 Kubernetes 环境不支持第三方服务帐户令牌， + 您必须确保遵循[这些步骤](/zh/docs/ops/best-practices/security/#configure-third-party-service-account-tokens)。 + +1. 由于集群中的资源没有按正确的顺序可用，生成的清单的 `kubectl apply` 可能会显示瞬态错误。 + +1. `helm install` 会自动修剪配置更改时应删除的任何资源（例如，如果您删除网关）。 + 当您将 `helm template` 与 `kubectl` 一起使用时， + 不会发生这种情况，必须手动删除这些资源。 + +{{< /warning >}} diff --git a/content/zh/docs/ambient/install/istioctl/index.md b/content/zh/docs/ambient/install/istioctl/index.md index 99375453b23f4..3d3d551c3c4f5 100644 --- a/content/zh/docs/ambient/install/istioctl/index.md +++ b/content/zh/docs/ambient/install/istioctl/index.md @@ -84,3 +84,53 @@ $ istioctl uninstall {{< text syntax=bash snip_id=remove_namespace >}} $ kubectl delete namespace istio-system {{< /text >}} + +## 安装前生成清单 {#generate-a-manifest-before-installation} + +您可以在安装 Istio 之前使用 `manifest generate` 子命令生成清单。 +例如，使用以下命令为可以使用 `kubectl` 安装的 `default` 配置文件生成清单： + +{{< text syntax=bash snip_id=none >}} +$ istioctl manifest generate > $HOME/generated-manifest.yaml +{{< /text >}} + +生成的清单可用于检查具体安装了什么以及跟踪清单随时间的变化。 +虽然 `IstioOperator` CR 代表完整的用户配置并且足以跟踪它， +但 `manifest generate` 的输出还捕获了底层图表中可能的变化，因此可用于跟踪实际安装的资源。 + +{{< tip >}} +您通常用于安装的任何其他标志或自定义值覆盖也应提供给 `istioctl manifest generate` 命令。 +{{< /tip >}} + +{{< warning >}} +如果尝试使用 `istioctl manifest generate` 安装和管理 Istio，请注意以下事项： + +1. 必须手动创建 Istio 命名空间（默认为 `istio-system`）。 + +1. Istio 验证默认不会启用。与 `istioctl install` 不同， + `manifest generate` 命令不会创建 `istiod-default-validator` + 验证 webhook 配置，除非设置了 `values.defaultRevision`： + + {{< text syntax=bash snip_id=none >}} + $ istioctl manifest generate --set values.defaultRevision=default + {{< /text >}} + +1. 资源可能没有按照与 `istioctl install` 相同的依赖项顺序进行安装。 + +1. 此方法尚未作为 Istio 版本的一部分进行测试。 + +1. 虽然 `istioctl install` 会自动从 Kubernetes 上下文中检测特定于环境的设置， + 但 `manifest generate` 无法做到这一点，因为它是离线运行的， + 这可能会导致意外结果。特别是，如果您的 Kubernetes 环境不支持第三方服务帐户令牌， + 则必须确保遵循[这些步骤](/zh/docs/ops/best-practices/security/#configure-third-party-service-account-tokens)。 + 建议将 `--cluster-specific` 附加到您的 `istio manifest generate` + 命令以检测目标集群的环境，这会将这些特定于集群的环境设置嵌入到生成的清单中。 + 这需要对正在运行的集群进行网络访问。 + +1. 由于集群中的资源没有按正确的顺序可用，生成的清单的 `kubectl apply` 可能会显示瞬态错误。 + +1. `istioctl install` 会自动修剪配置更改时应删除的任何资源（例如，如果您删除网关）。 + 当您将 `istio manifest generate` 与 `kubectl` 一起使用时， + 不会发生这种情况，必须手动删除这些资源。 + +{{< /warning >}}