Istio Helm Charts 与 values.yaml 维护指南从变更提交流程到 value 弃用规范【免费下载链接】istioConnect, secure, control, and observe services.项目地址: https://gitcode.com/GitHub_Trending/is/istioIstio 的安装形态由一组 Helm Charts 与其背后的values.yaml用户 API 共同构成。本文以仓库内 manifests/charts/UPDATING-CHARTS.md 为骨架系统讲解「什么样的 values 变更可以被接受、如何按五步完成一次 charts 变更、以及 value 的弃用与移除纪律」并结合 Makefile.core.mk、operator/pkg/apis/values_types.proto 与manifests目录下的真实 Chart 布局给出源码级依据。读完本文你将掌握为 Istio Helm Charts 提交流程合规变更的完整方法理解istioctl/Operator 与 Helm values 之间的生成关系并能正确执行make operator-proto、make copy-templates update-golden等关键命令。Helm values.yaml一份需要「受控增长」的用户 APIIstio 安装系统的底层是manifests/charts下的多个 Helm Chart。从 Makefile.core.mk 中的CHARTS变量可以确认当前被项目纳管的核心 Chart 集合gateway——独立 Gateway Chart含values.schema.json校验default——汇总默认安装形态的 Chartztunnel——Ambient 模式的 ztunnel 组件base——CRD 与基础资源gateways/istio-ingress与gateways/istio-egress——入口/出口网关模板二者模板由拷贝生成见下文 Step 4istio-control/istio-discovery——istiod 控制面istio-cni——CNI 插件。这些 Chart 的values.yaml例如 gateway/values.yaml、istio-control/istio-discovery/values.yaml汇总起来构成了面向最终用户的复杂 API。其背后被配置的 Kubernetes 资源字段数以千计用户越多、定制场景越多样就越会有人想给每个字段都开一个 values 入口。但正如原文档指出的核心矛盾如果把所有字段都暴露进values.yaml就会得到一个臃肿、失控的巨型 API其可用性甚至不如直接使用 Kubernetes API。因此项目对values.yamlAPI 的扩张采取克制策略在「开新 values」之前需要先回答一个判断问题——这个配置本质上属于哪种类型安装期install-time配置部署后不期望变动例如 Deployment 的副本数、资源规格、镜像等。这类配置适合留在 Helm values 中因为改 Helm values 就意味着重装或升级。动态运行时配置需要在不重装、不重启 Deployments 的前提下随时调整。这类配置应优先放入 MeshConfig API即 istio.io/api 仓库mesh/v1alpha1/config.proto中定义的网格级配置由控制面动态下发。什么样的 PR 会被接受values API 的准入规则为了把values.yaml维持在一个「大多数用户都够用的最小核心集」原文档给出了五条硬性准入规则以下结合仓库逐一解读。规则一安装期配置 ≠ 可以无脑开 values即使某改动确实是安装期配置也不意味着提交一个 values PR 就会被接受。只有面向大多数用户的通用需求才值得进入 values针对少数用户的特殊定制应引导其使用 Helm Chart 的高级定制机制Advanced Helm Chart Customization通过叠加自定义 Chart 或字段补丁实现任意定制而不是持续膨胀内置 API。规则二避免新增globalvalues新增global下的值是普遍被劝阻的。允许的例外非常严格必须是至少在 2 个 Chart 中被频繁且一致消费的值典型如镜像 tag、公共标签且仍需逐个 PR 单独评审、一事一议。规则三优先暴露「整块字段」而非单个子键如果一个多字段结构的整体透传更灵活就不要只暴露其中某一个子键。原文档给出的范例是 Kubernetes 的affinity错误倾向为 affinity 下的 nodeAffinity、podAffinity、podAntiAffinity 的每个复杂字段都单独设计 values 键正确做法只提供一个affinity字段按原样pass-through透传给 Kubernetes 资源。这样做以最小的 API 表面积换取最大灵活性。这一点在 gateway/values.schema.json 中得到印证——schema 中affinity被声明为type: object的整块透传字段而非展开枚举其内部子键。规则四所有 value 增删都必须附带 release notevalues 的任何新增或移除都面向用户属于破坏性或功能性变更必须随 PR 提供对应的 release note。release note 的书写模板见 releasenotes/template.yaml具体规范见 releasenotes/README.md历史记录存放于releasenotes/notes目录。规则五跨 Chart 的重复模板逻辑应提炼为共享模板如果发现同样的模板逻辑要在多个 Chart 中重复书写或需要构造复杂条件判断不要内联复制而应考虑使用共享 Helm 模板以保证一致性。这与 Step 4 中 Helm 把zzz_profile.yaml等共享模板渲染进每个 Chart 的做法是同一设计哲学。如何完成一次 Charts 变更五步标准流程原文档给出了从改 values 到提交 PR 的五步流程。下面每一步都补充了仓库内的具体落点与命令。Step 1在manifests目录中修改 charts 与 values.yaml变更的「源头」位于 manifests/charts 下对应 Chart 的values.yaml。改动的质量要求是在values.yaml内为新增值提供充分的注释文档与示例用法——每个字段都应说明其含义、类型与行为。以 gateway/values.yaml 为例其注释会明确标注该字段「为绕过 Helm 限制的内部实现用户不应显式设置」或说明service.type设None即可完全禁用 Service 等用法如果该 Chart 带有values.schema.json必须同步更新。当前仓库中 manifests/charts/gateway/values.schema.json 即对 gateway values 做了 JSON Schema 校验——例如kind字段用enum限定只能是Deployment或DaemonSetadditionalProperties: false用于拦截拼写错误的多余键。集成测试 tests/integration/helm/util.go 的注释也确认Helm 会对values.schema.json进行严格校验且版本不同严格程度有差异这说明 schema 会真实作用于用户安装体验不可遗漏。Step 2更新 istioctl/Operator 侧的 valuesgateway Chart 除外如果改动只涉及gatewayChart到这里就可以结束——gateway 独立于 istioctl 安装管线。其余所有 Chart 都会被istioctl消费manifests目录中的 Chart 用于在 istioctl 内生成安装 manifest。因此一旦改动某 Chart 的values.yaml就需在对应的默认安装 profile 中同步值覆盖。默认 profile 位于 manifests/profiles/default.yaml。从该文件第 23–34 行可以看到它的注释策略「绝大多数默认值来自 Helm Chart 的 values.yaml这里只列出与之不同的部分」——也就是说 profile 是相对 Chart values 的差量覆盖二者需保持字段一致。运行时使用的各 profile 副本由 manifests/helm-profiles 下的 YAML如default.yaml、ambient.yaml、demo.yaml、preview.yaml及各类platform-*.yaml维护执行拷贝命令时会被写入每个 Chart见 Step 4。Step 3更新 istioctl 的类型校验 schemaistioctl依赖一份protobuf schema对 values 中所有字段做类型检查type-checking。因此新增/删除 values 字段后必须同步修改 operator/pkg/apis/values_types.proto。该文件是 istioctl 校验的「真源」所有 schema 变更都必须落在这里否则 istioctl 用户会直接看到校验错误。文件内含大量带注释与默认值语义的 message 定义如ArchConfig、CNIConfig等即为values.yaml结构在 proto 层的映射更新该文件后执行$ make operator-proto该命令的实际行为可在 tools/proto/proto.mk 中看到——通过buf generate以operator/pkg/为输入重新生成 Go 结构体用于 schema 校验。所以「只改 proto 不跑生成」是不完整的。Step 4重新生成 manifestsistioctl的测试依赖自动生成的 manifests以确保 istioctl 二进制内置的 Chart 版本始终正确。改动后执行$ make copy-templates update-golden这两条目标都定义在 Makefile.core.mk 中背后做了大量工作值得展开说明copy-templatesMakefile.core.mk主要做三件事用sed把gateways/istio-ingress的 templates 复制并批量改写为gateways/istio-egress替换ingress→egress、Ingress→Egress、istio-ingress→istio-egress、app: istio-ingress→app: istio-egress等保证两个网关 Chart 模板始终同步遍历CHARTS列表把 manifests/helm-profiles 下每个 profile 前置「请勿直接编辑」警告文本后复制为各 Chart 的files/profile-*.yaml警告原文在 manifests/helm-profiles/warning-edit.txt依据模板 manifests/zzz_profile.yaml 生成每个 Chart 的templates/zzz_profile.yaml其中FLATTEN_GLOBALS_REPLACEMENT会按 Chart 类型被替换为trueztunnel、gateway或false其余以决定global字段是否在渲染时扁平化。update-goldenMakefile.core.mk其真实体是refresh-goldens通过REFRESH_GOLDENtrue go test刷新 operator、bootstrap、kube inject、gateway controller、authz、ambient、CNI iptables、istioctl writer 等众多包的 golden 文件。若想一次性验证「改完是否正确」可运行make gen-check——它等价于make gen内含copy-templates、update-golden等之后再做check-clean-repo检查仓库无残余改动。Step 5基于 Step 1–4 的产物提交 PR只要严格按上述步骤执行第 1–4 步的输出values 改动、schema、生成的 manifests/golden会保持一致PR 即可通过相关一致性检查。Value 弃用纪律至少两版本缓冲期values.yaml作为用户 API删除字段属于破坏性变更因此原文档规定了明确的两阶段弃用纪律阶段一标记弃用marking as deprecated值可以被标记为deprecated但不得立即移除从标记弃用的 PR 合并之日起最少等待 2 个 release之后才允许真正删除标记弃用的那个 PR必须附带 release note在 note 中明确写出被弃用的值是哪个、替代方案/备选值是什么。阶段二正式移除removing只有已标记弃用满 2 个 release 的值才可移除移除 PR 的 release note 中releaseNote与upgradeNote两个字段都必须填写同样要说明被移除的值以及替代方案。release note 的字段模板与说明见 releasenotes/template.yaml 与 releasenotes/README.md其中upgradeNote的存在正是为了让用户升级时能明确感知「这个我一直在用的 values 键没了、该换成什么」。这套「先标记、后移除、双 note 齐备」的纪律保证了 Helm values 这个大 API 在持续演进时不会无声地伤害存量用户。变更检查清单速览步骤关键操作仓库落点判定必要性区分安装期配置与动态运行时配置后者走 MeshConfig 而非 values见上文准入规则Step 1修改manifests/charts/chart/values.yaml并补足注释同步其values.schema.json如有manifests/charts、gateway/values.schema.jsonStep 2gateway 之外的所有 Chart 需同步 manifests/profiles/default.yaml 差量覆盖manifests/profiles/default.yamlStep 3更新 proto schema 后执行make operator-protobuf 生成 Go 校验结构体operator/pkg/apis/values_types.proto、tools/proto/proto.mkStep 4执行make copy-templates update-golden重生成 manifests 与 goldenMakefile.core.mkStep 5提交 PR附带 release notereleasenotes/template.yaml弃用标记弃用≥2 release 后才可移除移除 PR 的 note 须同时含releaseNote与upgradeNote同上遵循这套从准入判断、五步落地到弃用缓冲期的完整纪律Contributor 既能持续向 Istio 的 Helm values API 贡献新能力又能让它始终保持「最小核心配置集」的克制定位——避免 values.yaml 在 Helm 设计缺陷的放大下不可控地膨胀最终损害所有安装用户的体验。【免费下载链接】istioConnect, secure, control, and observe services.项目地址: https://gitcode.com/GitHub_Trending/is/istio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Istio Helm Charts 与 values.yaml 维护指南：从变更提交流程到 value 弃用规范
Istio Helm Charts 与 values.yaml 维护指南从变更提交流程到 value 弃用规范【免费下载链接】istioConnect, secure, control, and observe services.项目地址: https://gitcode.com/GitHub_Trending/is/istioIstio 的安装形态由一组 Helm Charts 与其背后的values.yaml用户 API 共同构成。本文以仓库内 manifests/charts/UPDATING-CHARTS.md 为骨架系统讲解「什么样的 values 变更可以被接受、如何按五步完成一次 charts 变更、以及 value 的弃用与移除纪律」并结合 Makefile.core.mk、operator/pkg/apis/values_types.proto 与manifests目录下的真实 Chart 布局给出源码级依据。读完本文你将掌握为 Istio Helm Charts 提交流程合规变更的完整方法理解istioctl/Operator 与 Helm values 之间的生成关系并能正确执行make operator-proto、make copy-templates update-golden等关键命令。Helm values.yaml一份需要「受控增长」的用户 APIIstio 安装系统的底层是manifests/charts下的多个 Helm Chart。从 Makefile.core.mk 中的CHARTS变量可以确认当前被项目纳管的核心 Chart 集合gateway——独立 Gateway Chart含values.schema.json校验default——汇总默认安装形态的 Chartztunnel——Ambient 模式的 ztunnel 组件base——CRD 与基础资源gateways/istio-ingress与gateways/istio-egress——入口/出口网关模板二者模板由拷贝生成见下文 Step 4istio-control/istio-discovery——istiod 控制面istio-cni——CNI 插件。这些 Chart 的values.yaml例如 gateway/values.yaml、istio-control/istio-discovery/values.yaml汇总起来构成了面向最终用户的复杂 API。其背后被配置的 Kubernetes 资源字段数以千计用户越多、定制场景越多样就越会有人想给每个字段都开一个 values 入口。但正如原文档指出的核心矛盾如果把所有字段都暴露进values.yaml就会得到一个臃肿、失控的巨型 API其可用性甚至不如直接使用 Kubernetes API。因此项目对values.yamlAPI 的扩张采取克制策略在「开新 values」之前需要先回答一个判断问题——这个配置本质上属于哪种类型安装期install-time配置部署后不期望变动例如 Deployment 的副本数、资源规格、镜像等。这类配置适合留在 Helm values 中因为改 Helm values 就意味着重装或升级。动态运行时配置需要在不重装、不重启 Deployments 的前提下随时调整。这类配置应优先放入 MeshConfig API即 istio.io/api 仓库mesh/v1alpha1/config.proto中定义的网格级配置由控制面动态下发。什么样的 PR 会被接受values API 的准入规则为了把values.yaml维持在一个「大多数用户都够用的最小核心集」原文档给出了五条硬性准入规则以下结合仓库逐一解读。规则一安装期配置 ≠ 可以无脑开 values即使某改动确实是安装期配置也不意味着提交一个 values PR 就会被接受。只有面向大多数用户的通用需求才值得进入 values针对少数用户的特殊定制应引导其使用 Helm Chart 的高级定制机制Advanced Helm Chart Customization通过叠加自定义 Chart 或字段补丁实现任意定制而不是持续膨胀内置 API。规则二避免新增globalvalues新增global下的值是普遍被劝阻的。允许的例外非常严格必须是至少在 2 个 Chart 中被频繁且一致消费的值典型如镜像 tag、公共标签且仍需逐个 PR 单独评审、一事一议。规则三优先暴露「整块字段」而非单个子键如果一个多字段结构的整体透传更灵活就不要只暴露其中某一个子键。原文档给出的范例是 Kubernetes 的affinity错误倾向为 affinity 下的 nodeAffinity、podAffinity、podAntiAffinity 的每个复杂字段都单独设计 values 键正确做法只提供一个affinity字段按原样pass-through透传给 Kubernetes 资源。这样做以最小的 API 表面积换取最大灵活性。这一点在 gateway/values.schema.json 中得到印证——schema 中affinity被声明为type: object的整块透传字段而非展开枚举其内部子键。规则四所有 value 增删都必须附带 release notevalues 的任何新增或移除都面向用户属于破坏性或功能性变更必须随 PR 提供对应的 release note。release note 的书写模板见 releasenotes/template.yaml具体规范见 releasenotes/README.md历史记录存放于releasenotes/notes目录。规则五跨 Chart 的重复模板逻辑应提炼为共享模板如果发现同样的模板逻辑要在多个 Chart 中重复书写或需要构造复杂条件判断不要内联复制而应考虑使用共享 Helm 模板以保证一致性。这与 Step 4 中 Helm 把zzz_profile.yaml等共享模板渲染进每个 Chart 的做法是同一设计哲学。如何完成一次 Charts 变更五步标准流程原文档给出了从改 values 到提交 PR 的五步流程。下面每一步都补充了仓库内的具体落点与命令。Step 1在manifests目录中修改 charts 与 values.yaml变更的「源头」位于 manifests/charts 下对应 Chart 的values.yaml。改动的质量要求是在values.yaml内为新增值提供充分的注释文档与示例用法——每个字段都应说明其含义、类型与行为。以 gateway/values.yaml 为例其注释会明确标注该字段「为绕过 Helm 限制的内部实现用户不应显式设置」或说明service.type设None即可完全禁用 Service 等用法如果该 Chart 带有values.schema.json必须同步更新。当前仓库中 manifests/charts/gateway/values.schema.json 即对 gateway values 做了 JSON Schema 校验——例如kind字段用enum限定只能是Deployment或DaemonSetadditionalProperties: false用于拦截拼写错误的多余键。集成测试 tests/integration/helm/util.go 的注释也确认Helm 会对values.schema.json进行严格校验且版本不同严格程度有差异这说明 schema 会真实作用于用户安装体验不可遗漏。Step 2更新 istioctl/Operator 侧的 valuesgateway Chart 除外如果改动只涉及gatewayChart到这里就可以结束——gateway 独立于 istioctl 安装管线。其余所有 Chart 都会被istioctl消费manifests目录中的 Chart 用于在 istioctl 内生成安装 manifest。因此一旦改动某 Chart 的values.yaml就需在对应的默认安装 profile 中同步值覆盖。默认 profile 位于 manifests/profiles/default.yaml。从该文件第 23–34 行可以看到它的注释策略「绝大多数默认值来自 Helm Chart 的 values.yaml这里只列出与之不同的部分」——也就是说 profile 是相对 Chart values 的差量覆盖二者需保持字段一致。运行时使用的各 profile 副本由 manifests/helm-profiles 下的 YAML如default.yaml、ambient.yaml、demo.yaml、preview.yaml及各类platform-*.yaml维护执行拷贝命令时会被写入每个 Chart见 Step 4。Step 3更新 istioctl 的类型校验 schemaistioctl依赖一份protobuf schema对 values 中所有字段做类型检查type-checking。因此新增/删除 values 字段后必须同步修改 operator/pkg/apis/values_types.proto。该文件是 istioctl 校验的「真源」所有 schema 变更都必须落在这里否则 istioctl 用户会直接看到校验错误。文件内含大量带注释与默认值语义的 message 定义如ArchConfig、CNIConfig等即为values.yaml结构在 proto 层的映射更新该文件后执行$ make operator-proto该命令的实际行为可在 tools/proto/proto.mk 中看到——通过buf generate以operator/pkg/为输入重新生成 Go 结构体用于 schema 校验。所以「只改 proto 不跑生成」是不完整的。Step 4重新生成 manifestsistioctl的测试依赖自动生成的 manifests以确保 istioctl 二进制内置的 Chart 版本始终正确。改动后执行$ make copy-templates update-golden这两条目标都定义在 Makefile.core.mk 中背后做了大量工作值得展开说明copy-templatesMakefile.core.mk主要做三件事用sed把gateways/istio-ingress的 templates 复制并批量改写为gateways/istio-egress替换ingress→egress、Ingress→Egress、istio-ingress→istio-egress、app: istio-ingress→app: istio-egress等保证两个网关 Chart 模板始终同步遍历CHARTS列表把 manifests/helm-profiles 下每个 profile 前置「请勿直接编辑」警告文本后复制为各 Chart 的files/profile-*.yaml警告原文在 manifests/helm-profiles/warning-edit.txt依据模板 manifests/zzz_profile.yaml 生成每个 Chart 的templates/zzz_profile.yaml其中FLATTEN_GLOBALS_REPLACEMENT会按 Chart 类型被替换为trueztunnel、gateway或false其余以决定global字段是否在渲染时扁平化。update-goldenMakefile.core.mk其真实体是refresh-goldens通过REFRESH_GOLDENtrue go test刷新 operator、bootstrap、kube inject、gateway controller、authz、ambient、CNI iptables、istioctl writer 等众多包的 golden 文件。若想一次性验证「改完是否正确」可运行make gen-check——它等价于make gen内含copy-templates、update-golden等之后再做check-clean-repo检查仓库无残余改动。Step 5基于 Step 1–4 的产物提交 PR只要严格按上述步骤执行第 1–4 步的输出values 改动、schema、生成的 manifests/golden会保持一致PR 即可通过相关一致性检查。Value 弃用纪律至少两版本缓冲期values.yaml作为用户 API删除字段属于破坏性变更因此原文档规定了明确的两阶段弃用纪律阶段一标记弃用marking as deprecated值可以被标记为deprecated但不得立即移除从标记弃用的 PR 合并之日起最少等待 2 个 release之后才允许真正删除标记弃用的那个 PR必须附带 release note在 note 中明确写出被弃用的值是哪个、替代方案/备选值是什么。阶段二正式移除removing只有已标记弃用满 2 个 release 的值才可移除移除 PR 的 release note 中releaseNote与upgradeNote两个字段都必须填写同样要说明被移除的值以及替代方案。release note 的字段模板与说明见 releasenotes/template.yaml 与 releasenotes/README.md其中upgradeNote的存在正是为了让用户升级时能明确感知「这个我一直在用的 values 键没了、该换成什么」。这套「先标记、后移除、双 note 齐备」的纪律保证了 Helm values 这个大 API 在持续演进时不会无声地伤害存量用户。变更检查清单速览步骤关键操作仓库落点判定必要性区分安装期配置与动态运行时配置后者走 MeshConfig 而非 values见上文准入规则Step 1修改manifests/charts/chart/values.yaml并补足注释同步其values.schema.json如有manifests/charts、gateway/values.schema.jsonStep 2gateway 之外的所有 Chart 需同步 manifests/profiles/default.yaml 差量覆盖manifests/profiles/default.yamlStep 3更新 proto schema 后执行make operator-protobuf 生成 Go 校验结构体operator/pkg/apis/values_types.proto、tools/proto/proto.mkStep 4执行make copy-templates update-golden重生成 manifests 与 goldenMakefile.core.mkStep 5提交 PR附带 release notereleasenotes/template.yaml弃用标记弃用≥2 release 后才可移除移除 PR 的 note 须同时含releaseNote与upgradeNote同上遵循这套从准入判断、五步落地到弃用缓冲期的完整纪律Contributor 既能持续向 Istio 的 Helm values API 贡献新能力又能让它始终保持「最小核心配置集」的克制定位——避免 values.yaml 在 Helm 设计缺陷的放大下不可控地膨胀最终损害所有安装用户的体验。【免费下载链接】istioConnect, secure, control, and observe services.项目地址: https://gitcode.com/GitHub_Trending/is/istio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考