深入解析 Istio base Helm Chart：安装方式、Profile 机制与 CRD/准入校验资源的源码剖析

本文以 Istio 仓库中的 manifests/charts/base/README.md 及其 chart 文件为主体，讲清 istio/base 这个基础 Helm Chart 到底安装了哪些集群共享资源，以及其 profile 配置机制的实现原理。读完本文，你将能够独立部署 base chart、理解 --set profile=<name> 背后的合并逻辑与优先级规则，并能结合 values.yaml 与 模板文件 对 CRD 安装、准入校验 Webhook、istio-reader 账号等细节做到源码级掌控。

一、base Chart 的定位：所有 Istio Revision 共享的集群资源

Istio 的 Helm 部署被拆分为多个 chart（base、istio-control、gateways、istio-cni、ztunnel 等，见 manifests/charts）。其中 base chart 的职责在 Chart.yaml 中被明确描述为：

description: Helm chart for deploying Istio cluster resources and CRDs

它安装的是被所有 Istio revision 共享的资源，核心就是 Istio 的 CRD 族，外加与 revision 无关的集群级/命名空间级配套资源。其模板目录 manifests/charts/base/templates 中只有 5 个资源模板和 1 个安装后提示文件：

文件	渲染出的资源	作用
crds.yaml	15 个 CustomResourceDefinition	安装 Istio 全部 API 的 CRD，来源是 files/crd-all.gen.yaml
defaultrevision-validatingwebhookconfiguration.yaml	ValidatingWebhookConfiguration istiod-default-validator	对 Istio 配置资源做服务端校验的准入 Webhook
defaultrevision-validatingadmissionpolicy.yaml	ValidatingAdmissionPolicy + Binding（实验特性）	用原生 CEL 策略做稳定通道校验
reader-serviceaccount.yaml	ServiceAccount istio-reader-service-account	多集群 remote-secret 工作流所需的读取权限
zzz_profile.yaml	不渲染资源，仅注入逻辑	实现 profile 值合并机制（详见第四节）
NOTES.txt	安装后提示	提示使用 helm status / helm get all 查看 release

从 Chart.yaml 还能看到一个构建细节：version: 1.0.0 旁注释写着 “This version is never actually shipped. istio/release-builder will replace it at build-time with the appropriate version”，即仓库内是占位版本，发布时由构建流程替换为真实版本号。

二、快速安装：仓库配置与安装命令

官方 README（manifests/charts/base/README.md）给出的标准安装流程如下。

第一步，配置 Istio chart 仓库并更新索引：

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

第二步，创建命名空间并安装 base chart，release 名固定为 istio-base：

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

安装成功后，NOTES.txt 会打印验证命令：

$ helm status istio-base -n istio-system
$ helm get all istio-base -n istio-system

需要说明的是：base chart 只负责“共享资源 + CRD”，完整的功能部署（istiod、网关、CNI、ztunnel）还需在 manifests/charts/istio-control、manifests/charts/gateways 等 chart 上继续安装；实践中通常直接用 istioctl install 一次性完成，其底层同样是按 chart 逐个渲染的。

三、核心参数解读（values.yaml）

manifests/charts/base/values.yaml 整体不长，但每个字段都有明确的运维含义。按分组说明如下：

3.1 global 分组

参数	默认值	说明
global.imagePullSecrets	[]	控制面 ServiceAccount 拉取镜像所需的私有仓库 secret 列表，配置私有 registry 的集群必须设置
global.istioNamespace	istio-system	用于定位 istiod 所在命名空间，Webhook 的 service 引用即依赖它
global.resourceScope	all	控制 Helm 处理哪些资源：all（全部）、cluster（仅集群级资源）、namespace（仅命名空间级资源）。适用于集群资源由集群管理员持有、Mesh 资源由 Mesh 管理员持有的权限分离场景
global.enableReaderRBAC	true	是否安装 istio-reader ServiceAccount 及其 RBAC，仅多集群 remote-secret 工作流需要
global.readerServiceAccount	未设置（注释示例 name/namespace）	自定义要绑定 istio-reader ClusterRole 的 ServiceAccount；设置后默认 SA 不再创建

3.2 base 分组

参数	默认值	说明
base.excludedCRDs	[]	排除的 CRD 列表，例如 excludedCRDs: ["envoyfilters.networking.istio.io"]。要求 enableCRDTemplates 为 true；若用 istioctl 安装，还需同时设置 enableIstioConfigCRDs=false
base.enableCRDTemplates	true	是否把 CRD 作为普通模板自管理。注释引用了 Helm 官方最佳实践：Helm v3 默认不支持升级 CRD，Istio 依靠自身向后兼容承诺将 CRD 按标准 K8S 资源自管理
base.validationURL	""	校验 Webhook 的自定义 URL，例如远端 pilot 地址加 /validate 路径
base.validationCABundle	""	Webhook 的 caBundle 值，适合 pilot 使用已知证书的远端校验场景；设置后 failurePolicy 固定为 Fail 并停止 pilot 内的 webhook 控制器自动 patch
base.enableIstioConfigCRDs	true	供 istioctl 使用，可在 base 中关闭 Istio 配置类 CRD

3.3 顶层参数

• defaultRevision: "default"：与 Webhook 模板联动，defaultRevision 为空字符串时整个 ValidatingWebhookConfiguration 不渲染；为 default 时指向 istiod 服务，其他值则指向 istiod-<revision>（见 defaultrevision-validatingwebhookconfiguration.yaml 第 21–25 行的分支逻辑）。
• experimental.stableValidationPolicy: false：实验开关，启用后渲染 defaultrevision-validatingadmissionpolicy.yaml 中的原生 ValidatingAdmissionPolicy（CEL 表达式），对 EnvoyFilter、WasmPlugin、ProxyConfig、Telemetry、AuthorizationPolicy 的若干字段做 Deny 校验。

一个容易被忽视的细节：所有默认值都嵌套在 _internal_defaults_do_not_set 这个“障眼法”键之下，且文件头注释明确警告用户不要直接设置这个前缀——应直接 --set foo=bar 而不是 --set _internal_defaults_do_not_set.foo=bar。这是 profile 机制的实现基础，下一节详解。

四、Profile 机制：README 核心概念的源码级还原

README 对 profile 的定义是：

一组捆绑的值预设（bundled collection of value presets），通过 --set profile=<profile> 设置。例如 demo 提供面向测试环境的预设配置：降低资源需求、默认启用更多特性。

并给出两条规则：各 chart 使用同一套 profile 以保持一致性（即使某个 profile 不影响当前 chart）；优先级为：显式设置的值 > profile 设置 > chart 默认值，同时提醒“默认值全部嵌套在 defaults 之下，配置时不要带上这个前缀”。

这套机制的实际实现位于 zzz_profile.yaml（文件名以 zzz 开头保证它在模板中最后执行）。注释和代码揭示了完整原理：

1. 三层值的优先级：内置 values.yaml 默认值 → 用户选中的 profile → 用户输入（-f 或 --set）。问题是 Helm 会把第 1、3 层合并成同一个 .Values 传进来，无法直接插入第 2 层。
2. 绕行方案：把内置默认值整体塞到 _internal_defaults_do_not_set 键下（即第 3 节看到的嵌套结构）。模板中 $defaults := $.Values._internal_defaults_do_not_set 取出后先 unset 掉该键。
3. 加载 profile 文件：$.Files.Get (printf "files/profile-%s.yaml" .) 从 manifests/charts/base/files 目录读取对应预设文件，找不到则直接 fail "unknown profile"。当前仓库内置的 profile 包括 ambient、demo、preview、remote、stable、各平台（gke、k3d、k3s、microk8s、minikube、openshift）以及 1.25–1.30 的 compatibility-version-* 系列。
4. 叠加兼容版本与平台：compatibilityVersion 会合并 profile-compatibility-version-<v>.yaml，platform 会合并 profile-platform-<p>.yaml，均以 mustMergeOverwrite 覆盖 profile 本身，且未知值会 fail。
5. 最终合并：mustMergeOverwrite $defaults $profile 得到中间值，再与用户 .Values 合并写回，保证其余模板像没有任何机制存在一样直接读 .Values。
6. 防呆校验：模板开头显式检查 $.Values.defaults，一旦用户真的按字面设置了 defaults. 前缀的值，安装会失败并打印形如 “Setting with .default prefix found; remove it...” 的错误信息——这正是 README 里“should not include this”警告的强制执行手段。

以 --set profile=demo 为例，加载的 files/profile-demo.yaml 头部注释说明了 demo 预设的三个目标：降低资源占用（cni/ztunnel/proxy/waypoint 的请求降到 10m CPU / 40Mi 内存，pilot 关闭 autoscale 并 traceSampling: 100）、默认启用若干教学演示特性（meshConfig 中内置 otel、skywalking、otel-tracing、jaeger 等 extensionProviders）、以及为 ingress 网关开放更多端口（15021/80/443/31400/15443）。这也印证了 README 中 “the demo profile offers a preset configuration to try out Istio in a test environment” 的表述——demo profile 的主要价值其实作用在其他 chart 上，对 base 本身几乎无感，因此 README 才会强调 “even if they do not impact a given chart”。

五、CRD 安装实现：模板渲染而非 crds/ 目录

Helm chart 把 CRD 放在 crds/ 目录是常见做法，但 Istio 有意采用了“方法二”：CRD 放在 templates/crds.yaml 中按普通模板渲染，配合 values.yaml 中 enableCRDTemplates: true 的注释，实现了 CRD 可随 Helm release 正常升级与卸载。模板逻辑可以概括为：

• resourceScope 门禁：仅当 global.resourceScope 为 all 或 cluster 时渲染（CRD 是集群级资源，namespace 模式下跳过）。
• 排除机制：逐段遍历 files/crd-all.gen.yaml（以 --- 分隔，当前包含 15 个 CRD，如 trafficextensions.extensions.istio.io 等），用 metadata.name 与 base.excludedCRDs 比对，命中即跳过。
• 标签重写：渲染时会把生成的 CRD 中静态的遗留标签（chart: istio、heritage: Tiller 等，见 crd-all.gen.yaml 文件头）替换为模板生成的标准 istio.labels（app.kubernetes.io/part-of: istio、helm.sh/chart 等）。注释特意说明：这样即使有人直接 kubectl apply -f crd-all.gen.yaml 也仍然可行，两条路径不冲突。
• enableCRDTemplates=false 的兜底：直接原样输出 files/crd-all.gen.yaml，且文件头注释标记了 enableCRDTemplates 默认将一直为 true，计划几个版本后移除该开关。
• 每个 CRD 还带 helm.sh/resource-policy: keep 注解，保证 helm uninstall 后 CRD 保留，避免误删用户配置数据。

六、准入校验资源：Webhook 与实验性 CEL 策略

base chart 还托管了 default revision 的校验入口，这是它“跨 revision 共享”定位的另一个体现。

defaultrevision-validatingwebhookconfiguration.yaml 渲染 istiod-default-validator，关键行为：

• 监听 security.istio.io、networking.istio.io、telemetry.istio.io、extensions.istio.io 四个 API 组下所有资源的 CREATE/UPDATE；
• 默认通过 Service 引用 istiod（或 istiod-<revision>）的 /validate 路径；设置了 base.validationURL 则改走自定义 URL；
• failurePolicy 有三段逻辑：设置了 validationCABundle 时固定 Fail（同时注释说明这会关闭 pilot 内的 webhook 控制器停止自动 patch）；否则安装（非 upgrade）阶段先用 Ignore “失败开放”，等 webhook 端点就绪后由 pilot 的 webhook 控制器把策略改为 Fail 并 patch 入 caBundle。

defaultrevision-validatingadmissionpolicy.yaml 则展示了 Istio 向原生 ValidatingAdmissionPolicy 迁移的实验方向：由 experimental.stableValidationPolicy 开关控制，使用 CEL 表达式实现 failurePolicy: Fail 的 Deny 校验，覆盖例如禁止 EnvoyFilter/WasmPlugin/ProxyConfig 之外若干字段（Telemetry 的 useRequestIdForTraceSampling、reportingInterval、accessLogging 的 filter，AuthorizationPolicy 中的 trustDomains/notTrustDomains 等稳定通道外特性）。

七、istio-reader：多集群工作流的权限入口

reader-serviceaccount.yaml 在 resourceScope 为 all/namespace、enableReaderRBAC 开启、且未指定自定义 readerServiceAccount 时，创建单例 ServiceAccount istio-reader-service-account，并支持 global.imagePullSecrets。模板注释交代了两点背景：该账号聚合了给定集群内各 revision 的读取权限，用于多集群 remote-secret 的创建流程；同时它目前是“每集群一个、不分 revision”的单例，注释坦承“泄露该 SA 的 token 意味着可以访问集群中所有已安装 revision”，因此未来可能改为按 revision 划分。

八、小结

istio/base 看似只是一个安装文档（manifests/charts/base/README.md）加几个模板，实则是整个 Helm 安装体系的基石：它用 15 个 CRD 定义了 Istio 的全部 API 面，用自管理模板解决了 Helm 对 CRD 升级的限制，用 zzz_profile.yaml 的默认值重嵌套技巧实现了“显式值 > profile > 默认值”的三层合并，并为多集群与准入校验提供了共享入口。理解这一层后，istioctl install 或分 chart 安装时的任何行为——包括为什么 --set defaults.xxx 会报错、为什么排除 CRD 需要 excludedCRDs 与 enableIstioConfigCRDs 联动、为什么升级后 Webhook 的 failurePolicy 会自动从 Ignore 变为 Fail——都能在这套文件里找到确定性答案。