Istio Istiod Helm Chart 部署与配置指南：安装流程、Profile 优先级与 Control Plane 自定义

Istio Istiod Helm Chart 部署与配置指南：安装流程、Profile 优先级与 Control Plane 自定义

【免费下载链接】istioConnect, secure, control, and observe services.项目地址: https://gitcode.com/GitHub_Trending/is/istio

本指南以仓库中 manifests/charts/istio-control/istio-discovery/README.md 为骨架，结合istiod（istio-discovery）Chart 的源码与配置模板，系统讲解如何通过 Helm 在 Kubernetes 上安装/卸载控制平面、理解 Profile 与取值优先级、配置meshConfig、管理多版本 Revision，并揭示 Chart 实际生成的 Deployment、Service、ConfigMap、HPA 等资源细节。读完本文，你将掌握一套可复现、可排错的istiodHelm 部署与自定义方法，并能在源码层面定位每个配置项的真实去向。

一、Chart 是什么：istio-discovery 与 istiod

在 Istio 的模块化 Helm 安装体系中，istio-discovery Chart 负责安装istiod——Istio 的控制平面核心服务（Pilot/XDS discovery、CA 证书签发、Sidecar 注入 Webhook 与配置校验 Webhook 均由它承载）。Chart 的description即为 "Helm chart for istio control plane"，keywords包含istio、istiod、istio-discovery，源码目录对应pilot/中的istio-discovery二进制。

Chart 元信息中版本号恒为1.0.0只是占位（官方发布流程由 istio/release-builder 在打包时替换），所以不要用 Chartversion判断 Istio 版本；真实版本取决于安装时 Helm 仓库里该 Chart 的发布版本，或--set global.tag指定的镜像 tag。

安装前需要先装 istio/base

与 Istio 1.5+ 之后的 Helm 安装约定一致，istiodChart不包含任何 CRD。README 明确要求：安装本 Chart 前，必须先从istio/baseChart 安装集群级共享资源（主要是 Istio 各类 CRD）。参考 manifests/charts/base/README.md：

kubectl create namespace istio-system helm install istio-base istio/base -n istio-system

两个 Chart 的 README 使用同一套 "Setup Repo Info" 流程，也印证了这一点。

二、安装与卸载：一条命令跑通

2.1 添加官方 Helm 仓库

helm repo add istio https://istio-release.storage.googleapis.com/charts helm repo update

（该地址即 manifests/charts/README.md 中声明的官方 charts 仓库地址；除了该 HTTPS 仓库，Chart 还会以oci://registry.istio.io/release/charts/的 OCI 形式发布。）

2.2 安装 istiod

确保前面已经通过istio/base安装好 CRD 之后，执行：

kubectl create namespace istio-system helm install istiod istio/istiod --namespace istio-system

• istiod是本次 release 的名字；
• 安装后可通过helm status istiod -n istio-system与helm get all istiod -n istio-system查看发布详情（见 templates/NOTES.txt）。

安装成功时，NOTES 会提示后续动作：非 ambient profile 下通常是 "Deploy a Gateway / 查看 traffic management、security 等任务文档"；使用 ambient profile 时则提示查阅 ambient 快速开始与架构文档。

2.3 卸载

helm delete istiod --namespace istio-system

注意：这只删除istiodrelease 创建的资源。README 中的istio/base提供的 CRD 属于另一 Chart，需单独卸载或按需保留（注意 CRD 卸载会级联影响集群内已有 Istio 配置资源）。

2.4 查看可配置项

helm show values istio/istiod

该命令输出即 values.yaml 的内容，是排查"某个配置该写在哪里"的第一入口。

三、Profiles：开箱即用的预置配置集合

3.1 Profile 是什么

Helm Chart 存在profile概念：一个 profile 就是一份打包好的 value 预置集合，通过--set profile=<profile>启用。例如demoprofile 为测试环境准备了一组低资源占用、多特性开启的配置。

README 强调了两点一致性约定：

1. 跨 Chart 一致性：同一套 profile 名称在所有 Istio Chart（base / istiod / gateway / cni / ztunnel）中保持一致，即使某个 profile 对某个 Chart 没有实际影响也会照常被接受，从而保证--set profile=demo这样的命令在各 Chart 间可移植；
2. 优先级一致：显式 set 的 value > profile 中的设置 > Chart 内置默认值。

3.2 优先级在模板里如何实现

Profile 的合并逻辑写在与 Chart 同目录的渲染辅助模板 templates/zzz_profile.yaml 中，文件头部注释清楚交代了三层优先级（越靠后越优先，即 last wins）：

1. values.yaml 内置默认值；
2. 用户选择的 profile；
3. 用户的输入（-f或--set）。

由于 Helm 把默认值与用户输入混在同一个.Values里，模板用了一个巧妙的变通方案：所有内置默认值被放置在特殊键_internal_defaults_do_not_set下，渲染时先把该键取出作为$defaults，再从files/profile-<name>.yaml读取 profile 内容，最后mustMergeOverwrite $defaults $.Values完成合并。Chart 其余模板完全无感知，行为一致。

模板还会根据.Values.compatibilityVersion（对应files/profile-compatibility-version-*.yaml）与.Values.platform（对应files/profile-platform-*.yaml）叠加对应 profile。

3.3 千万不能写defaults.前缀

正因为默认值被收拢在内部键下，README 特别提醒：最终用户配置 Chart 时不要带defaults.前缀，应写：

helm install istiod istio/istiod -n istio-system --set some.field=true

而不是：

# 错误示例 helm install istiod istio/istiod -n istio-system --set defaults.some.field=true

若误写，templates/zzz_profile.yaml 中的{{- if $.Values.defaults }}分支会直接fail，把检测到的defaults.*内容打印出来并终止渲染，提示改为--set hub=foo这种形式。

3.4 本仓库内置的 profile

本 Chart 的files/目录实际携带的 profile 分为三类（均可在 manifests/helm-profiles/ 找到原始版本，Chart 内为make gen生成的拷贝，文件头注明 "DO NOT EDIT, THIS FILE IS A COPY"）：

• 常规 profile：demo、preview、ambient、remote、stable；
• 平台 profile：platform-gke、platform-k3d、platform-k3s、platform-microk8s、platform-minikube、platform-openshift（以--set platform=...生效）；
• 兼容性版本 profile：profile-compatibility-version-1.25~1.30（以--set compatibilityVersion=1.30这类方式生效）。

以 demo profile 为例，它实际做了这些事：

• meshConfig.accessLogFile: /dev/stdout：开启访问日志到标准输出；
• 预置多个meshConfig.extensionProviders：otel（Envoy OTLP ALS）、skywalking、otel-tracing、jaeger（OpenTelemetry 采集器地址）；
• pilot.autoscaleEnabled: false、pilot.traceSampling: 100、pilot.resources.requests.cpu/memory降到10m/100Mi，实现"低资源 + 全量 trace 采样"的演示体验；
• 同时降低global.proxy、ztunnel、gateways等组件的资源请求。

而 remote profile 则用于"远程控制平面"场景，开启istiodRemote.enabled: true、关闭本地 ConfigMap 与遥测、并设置global.omitSidecarInjectorConfigMap: true。stable profile 当前只做一件事：开启experimental.stableValidationPolicy: true，用 admission control 保证只使用稳定版资源与字段（文件注明"当前为实验特性，可能变更"）。

四、常用配置深入解析

4.1 meshConfig：Mesh 运行期配置

README 指出，任何 Mesh Config 选项都可以直接写进meshConfig：

meshConfig: accessLogFile: /dev/stdout

其底层生成逻辑位于 templates/configmap.yaml：

• 模板先用include "mesh"拼出一份由独立 values 字段推导出的基础 mesh 配置（如trustDomain: cluster.local、rootNamespace（默认取global.istioNamespace）、根据global.proxy.tracer生成的defaultConfig.tracing、discoveryAddress: istiod[-<rev>].<namespace>.svc:15012、defaultConfig.image.imageType等）；
• 再把用户提供的meshConfig.*通过mergeOverwrite覆盖到基础配置之上，最终写入名为istio[-<revision>]的 ConfigMap 的meshkey 中。

也就是说：meshConfig是面向用户的 API，而单个 values 字段是它的便捷别名，二者最终殊途同归地落入同一份istioConfigMap。values.yaml 中meshConfig.enablePrometheusMerge: true即为默认开启的示例。

另外，Chart 默认会额外生成一个名为values[-<revision>]的 ConfigMap（见 templates/configmap-values.yaml），其中original-values与merged-values记录渲染前后的 Helm 值，供排查与外部工具使用，注释明确说明修改该 ConfigMap不会影响运行。

网格网络配置（Split Horizon EDS 用）走global.meshNetworks，同样被写入该 ConfigMap 的meshNetworkskey（见 configmap.yaml 中meshNetworks分支与 values.yaml 中带network1/network2示例的注释块）。

4.2 Revision：同集群多版本控制平面（金丝雀升级）

控制平面 Revision 允许在同一集群部署多个版本的控制平面，从而实现安全的金丝雀升级（canary upgrade），配置方式：

revision: my-revision-name

Revision 在资源层面的具体表现可从模板中看到：

• Deployment / Service / ConfigMap 等资源名会带上后缀，例如istiod-my-revision-name（见 templates/deployment.yaml、templates/service.yaml）；
• Pod 打上istio.io/rev: <revision>标签，Deployment 环境变量REVISION默认default；
• 当revision为空时，Service 的 selector 用istio: pilot，当revision非空时改用app: istiod+istio.io/rev匹配，注释明确说明这是为了避免默认 Service 把金丝雀实例也选中；
• meshConfig.defaultConfig.discoveryAddress指向istiod-<rev>.<ns>.svc:15012（见 configmap.yaml）。

配合revision使用的还有revisionTags（revision 别名，见 values.yaml 中revisionTags: []），渲染时会生成对应的 revision tag 服务与 MutatingWebhookConfiguration 资源（见模板目录中 revision-tags-svc.yaml 与 revision-tags-mwc.yaml）。升级时让工作负载所在的命名空间/标签从旧 revision 切到新 revision，即可逐步灰度。

4.3 其它值得注意的高频配置

• 资源与调度：replicaCount（关闭自动扩缩时才生效）、autoscaleEnabled/autoscaleMin/autoscaleMax、resources（不设置时回退到global.defaultResources）、nodeSelector/affinity/tolerations/topologySpreadConstraints/podAnnotations/deploymentLabels等，全部在 deployment.yaml 中逐项展开；
• 自动扩缩（HPA）：当autoscaleEnabled && autoscaleMin && autoscaleMax同时满足时，渲染autoscaling/v2的 HPA（见 templates/autoscale.yaml），默认按 CPU 80% 利用率扩缩（cpu.targetAverageUtilization: 80），配置memory.targetAverageUtilization或autoscaleBehavior可加内存指标与扩缩策略；
• PDB：默认创建 PodDisruptionBudget（global.defaultPodDisruptionBudget.enabled: true，pdb.minAvailable: 1）；
• CNI 协同：taint.enabled开启后自动注入PILOT_ENABLE_NODE_UNTAINT_CONTROLLERS=true环境变量，Deployment 同时默认携带cni.istio.io/not-ready容忍（taint/untaint 控制器负责在 istio-cni 就绪后去除节点污点）；cni.enabled/provider控制是否复用既有 CNI 安装；
• Ambient 模式：trustedZtunnelNamespace/trustedZtunnelName用于声明可信 ztunnel 所在命名空间与名称，渲染时会写入CA_TRUSTED_NODE_ACCOUNTS环境变量，默认值为<release-namespace>/ztunnel（见 deployment.yaml 注释）；
• 远程 istiod：istiodRemote.enabled为 true 时本集群不安装 istiod，只渲染消费远程实例所需的支撑资源（webhook/injection URL 等），可参考 remote-istiod 相关模板与 profile-remote.yaml；
• 资源范围：global.resourceScope（all/cluster/namespace）控制 Helm 只处理部分资源，便于集群管理员与网格管理员分权（见 deployment、service 等模板开头resourceScope条件）；
• 日志：global.logAsJson会给容器追加--log_as_json；global.logging.level（默认default:info）会映射为--log_output_level。

五、Chart 生成的运行时拓扑：Deployment 与 Service

5.1 istiod Deployment

核心 Deployment 见 templates/deployment.yaml，容器名为discovery，镜像规则为：

<hub>/<image|pilot>:<tag>[-<variant>]

其中 hub/tag/variant 均可由顶层hub/tag/variant覆盖，否则回退到global.hub/global.tag/global.variant（镜像默认值可查看 values.yaml，Chart 内默认hub: registry.istio.io/testing、tag: latest）。

容器启动参数与关键端口（对应 deployment.yaml 中 args 与 ports 段）：

容器端口	名称	用途
8080	http-debug	debug/就绪检查（/readyreadinessProbe 轮询该端口）
15010	grpc-xds	XDS 明文 gRPC
15012	tls-xds	使用 K8s 签发证书的 mTLS XDS
15017	https-webhooks	校验与注入 Webhook
15014	http-monitoring	Prometheus 指标抓取

命令默认discovery --monitoringAddr=:15014 --domain <clusterDomain> --keepaliveMaxServerConnectionAge <30m>；--keepaliveMaxServerConnectionAge用来控制 Sidecar 最长连接时长，用于在多个 istiod 实例间均衡负载（代价是连接重建频率上升）。容器以非 root、只读根文件系统运行并 drop 全部 capabilities；可选挂载cacertssecret、istiod-tls（istio-csr DNS 证书）、istio-kubeconfig、jwksResolverExtraRootCA（写入PILOT_CA_*/EXTERNAL_ISTIOD/ FIPSGODEBUG=fips140=only等环境变量由相关 values 驱动）。

5.2 istiod Service

service.yaml 将上述端口以对外形式暴露：

Service 端口	名称	说明
15010	grpc-xds	明文 XDS
15012	https-dns	mTLS XDS（K8s 签名证书）
443 → 15017	https-webhook	校验与注入
15014	http-monitoring	指标

此外支持ipFamilyPolicy/ipFamilies（双栈）与trafficDistribution。

六、升级与排错实用提示

• NOTES 中的弃用告警：安装/升级后，NOTES.txt 会对已弃用字段（如global.proxy.accessLogFile、global.tracer.*、pilot.ingress等）输出 "deprecated; use ... instead" 的 WARNING，并提示它们的新位置几乎都收敛到了meshConfig.*与PeerAuthentication等 CRD。对严重废弃项（如 stackdriver trace 相关）甚至直接fail拒绝渲染。
• 证书提供方：global.pilotCertProvider目前仅支持istiod，NOTES 中对设为kubernetes的情况会直接报错 "pilotCertProvider=kubernetes is not supported"。
• 配置追踪：安装后通过kubectl get cm istio -n istio-system -o yaml查看落地的最终mesh配置，通过valuesConfigMap 对比 original/merged 取值；若想快速了解模板对全部 values 的处理，本 Chart 模板文件集中在 templates/，可逐个对照。

七、小结

istio-discoveryChart 的 README 虽短，但它覆盖了 Helm 安装 Istio 控制平面的完整闭环：前置 CRD（istio/base）→ 安装/卸载 →helm show values查询配置 → Profile 预置与优先级 →meshConfig与 Revision 两大核心扩展点。结合仓库内的模板源码可以发现，README 中每条约定（defaults.前缀陷阱、profile 跨 Chart 一致、显式值最高优先）都有对应的模板代码可验证，而meshConfig、revision、resourceScope、istiodRemote等配置最终会精确落到 Deployment、Service、ConfigMap 与各类 Webhook/RBAC/HPA 资源上。掌握本 Chart，你就掌握了在生产集群中按需定制、平滑金丝雀升级并准确排错 Istio 控制平面的基本能力。

建议继续阅读仓库内的相关文件深化理解：

• Chart 定义与 values 全量默认值：Chart.yaml、values.yaml
• 关键渲染模板：deployment.yaml、service.yaml、configmap.yaml、autoscale.yaml、zzz_profile.yaml
• Profile 原始定义：manifests/helm-profiles/（Chart 内拷贝位于 files/）
• 前置 CRD Chart：manifests/charts/base/README.md
• istiod 对应二进制源码：pilot/cmd/pilot-discovery、pilot/pkg/xds

【免费下载链接】istioConnect, secure, control, and observe services.项目地址: https://gitcode.com/GitHub_Trending/is/istio