Helm CEL插件：用表达式语言重构K8s配置校验，告别JSON Schema局限

1. Helm CEL 插件：为什么说它是 Helm 图表验证的“游戏规则改变者”？

在 Kubernetes 生态里混了这么多年，Helm 绝对是打包和部署应用的首选工具，没有之一。但每次写Chart.yaml和values.yaml的时候，心里总有点不踏实：用户传进来的参数到底合不合规？端口号是不是超范围了？内存限制的格式写对了吗？以前，我们只能依赖values.schema.json这个 JSON Schema 文件来做校验。这东西吧，能用，但写起来实在有点“反人类”——语法冗长，表达能力有限，想写个“如果 A 字段存在，那么 B 字段必须大于 C”这样的条件逻辑，得绕好几个弯子。

直到我遇到了idsulik/helm-cel这个 Helm 插件。它用CEL（Common Expression Language）彻底替换了 JSON Schema，让你能用一种近乎写代码的逻辑表达式来定义校验规则。简单来说，它把 Helm 图表的值文件验证，从一个“填空题”变成了“编程题”，灵活性和表达力直接上了一个维度。如果你正在为复杂的 Helm 图表配置管理而头疼，或者你的 CI/CD 流水线因为配置错误而频繁中断，那这个插件值得你花十分钟深入了解。它不是什么庞大复杂的系统，就是一个轻巧的 Go 语言二进制文件，但解决的是 Helm 用户长期以来的一个核心痛点。

2. 核心设计思路：从 JSON Schema 的“镣铐”到 CEL 的“自由”

在深入命令行之前，我们得先搞清楚 helm-cel 到底解决了什么问题，以及它为什么选择 CEL 这条路。这决定了你是否应该把它引入你的技术栈。

2.1 JSON Schema 的局限性：为什么我们需要更好的工具？

传统的values.schema.json并非一无是处。对于简单的类型检查（比如某个字段必须是字符串）和枚举值限制，它工作得不错。但一旦遇到稍微复杂一点的业务逻辑，它的短板就暴露无遗。

假设我们有一个 Helm Chart，用于部署一个 Web 应用，它的values.yaml可能包含：

service: type: NodePort # 或 ClusterIP, LoadBalancer port: 80 nodePort: 30080 # 仅当 type 为 NodePort 时需要 autoscaling: enabled: true minReplicas: 1 maxReplicas: 10

用 JSON Schema 来写校验，你会遇到这些麻烦：

1. 条件依赖校验困难：很难优雅地表达“当service.type == \"NodePort\"时，service.nodePort字段必须存在且值在 30000-32767 之间”。你可能需要用到if、then、else关键字，但组合起来结构非常复杂，可读性极差。
2. 跨字段逻辑校验缺失：无法方便地校验“autoscaling.minReplicas必须小于等于autoscaling.maxReplicas”。这需要定义复杂的引用和逻辑组合。
3. 字符串模式匹配笨拙：对于资源限制字段（如\"128Mi\",\"2Gi\"），用 JSON Schema 的pattern来匹配^[0-9]+(Mi|Gi)$还算可以，但如果你想校验数字部分的范围（比如内存不能小于 10Mi），就又得拆分成多个规则。
4. 可维护性差：当校验规则多达几十条时，一个庞大的、嵌套极深的 JSON 文件会让人望而生畏，修改和调试成本很高。

helm-cel 的诞生，正是为了打破这些镣铐。它不再将校验规则视为一份静态的、声明式的“合同”，而是将其视为一系列可以动态求值的逻辑“断言”。

2.2 CEL 的优势：为什么是它？

CEL 并不是一个凭空造出来的新语言。它是由 Google 开源的一种非图灵完备的表达式语言，最初在 Kubernetes 的 ValidatingAdmissionPolicy 中广泛应用，用于编写准入控制策略。选择 CEL 作为 helm-cel 的核心，是经过深思熟虑的：

1. 专为配置校验而生：CEL 的设计目标就是安全、高效地评估针对结构化数据的断言。它不能执行任意代码（没有循环、无法定义函数），这保证了其在插件中运行的安全性，避免了注入攻击的风险。
2. 表达力强大：支持丰富的操作符（逻辑、比较、算术）、成员访问、三元运算符、正则匹配、类型检查等。前面提到的所有复杂校验，用一行 CEL 表达式就能清晰表达。
3. 与 Go 天然集成：CEL 本身由 Go 实现，这使得将其集成到一个 Go 语言的 Helm 插件中变得非常自然和高效。插件可以直接利用 CEL 的 Go 库进行解析和求值，性能有保障。
4. 社区认知度渐高：随着 Kubernetes 1.26 引入 ValidatingAdmissionPolicy，越来越多的 K8s 运维和开发人员开始接触并熟悉 CEL 语法。使用 helm-cel 实际上是在统一技术栈，降低学习成本。

核心思路转换：helm-cel 不再尝试用一份复杂的“结构描述”来约束数据，而是让你编写一系列针对数据状态的“真值判断”。只要所有判断结果为true，数据就是合法的。这种“断言式”的思维，更符合程序员对业务逻辑进行编码的习惯。

3. 实战部署：三种安装方式与适用场景全解析

理论说得再多，不如动手安装。helm-cel 提供了多种安装方式，适应从本地开发到容器化流水线的不同场景。

3.1 标准安装：使用 Helm 插件管理器（推荐大多数用户）

这是最直接、最“Helm”的方式。确保你的 Helm 客户端版本在 3.0 以上。

helm plugin install https://github.com/idsulik/helm-cel

安装完成后，运行helm cel --help验证是否成功。你会看到validate和generate两个子命令。

注意：这种安装方式会将插件二进制文件下载到$HELM_PLUGINS目录（通常是~/.local/share/helm/plugins/或$XDG_DATA_HOME/helm/plugins）。它修改的是你的本地 Helm 客户端环境。如果你在 CI/CD 的 Docker 镜像中使用，可能需要选择其他方式。

3.2 容器化安装：为 GitOps 与 CI/CD 流水线量身打造

如果你的校验动作发生在 CI 服务器、GitOps 工具（如 Argo CD 的 ConfigManagementPlugin）或任何容器化环境中，使用 Docker 镜像是最干净、最可重现的选择。

# 拉取最新版本的镜像 docker pull idsulik/helm-cel:latest # 或者拉取一个特定的稳定版本（生产环境推荐） docker pull idsulik/helm-cel:2.1.2

使用方式是将你的 Chart 目录挂载到容器内：

# 基本验证：对当前目录下的 mychart 进行校验 docker run --rm -v $(pwd):/charts idsulik/helm-cel validate /charts/mychart # 使用特定 values 文件 docker run --rm -v $(pwd):/charts idsulik/helm-cel validate /charts/mychart --values-file /charts/mychart/prod-values.yaml # 生成规则文件 docker run --rm -v $(pwd):/charts idsulik/helm-cel generate /charts/mychart

实操心得：在 Jenkins 或 GitLab CI 的 Pipeline 中，我通常会定义一个专门的validate-helm阶段。在这个阶段里，直接使用这个 Docker 镜像来校验 Chart，而不是在 Agent 上安装 Helm 插件。这样做的好处是：

• 环境隔离：CI 环境保持纯净，不受主机 Helm 配置影响。
• 版本锁定：镜像标签锁定了 helm-cel 的版本，避免因版本更新导致校验行为意外变化。
• 快速启动：无需在 CI 镜像中预装任何东西，直接docker run。

3.3 从源码构建：适合开发者与定制化需求

如果你需要修改插件逻辑，或者想针对某个特定版本进行测试，可以从源码构建。

git clone https://github.com/idsulik/helm-cel cd helm-cel # 确保已安装 Go 1.22+ make install

make install会编译并将二进制文件安装到你的 Helm 插件目录。项目使用 Makefile 管理构建流程，结构清晰。如果你想贡献代码，这是一个标准的 Go 项目，go build、go test都能正常工作。

工具选型背后的逻辑：提供多种安装方式，体现了插件的设计考虑了不同的用户场景。普通用户追求便捷，用helm plugin install；自动化环境追求稳定和隔离，用 Docker；开发者和贡献者则需要源码访问能力。这种分层设计让工具更具普适性。

4. 规则编写进阶：从基础校验到复杂业务逻辑

安装好了，接下来就是重头戏：编写values.cel.yaml规则文件。这是发挥 helm-cel 威力的核心。

4.1 规则文件结构与语法精讲

一个基本的values.cel.yaml文件结构如下：

# expressions 部分用于定义可复用的子表达式，非必需 expressions: isValidPort: "values.port >= 1 && values.port <= 65535" isValidNodePort: "values.nodePort >= 30000 && values.nodePort <= 32767" # rules 部分是核心，每个规则都是一个断言 rules: - expr: "has(values.service)" # 1. 使用内置的 has() 函数检查字段是否存在 desc: "service configuration is required" severity: error # 默认为 error，可省略 - expr: "${isValidPort}" # 2. 引用上面定义的表达式 desc: "service.port must be a valid port" severity: error - expr: 'values.service.type == "NodePort" ? has(values.service.nodePort) && ${isValidNodePort} : true' # 3. 使用三元运算符实现条件逻辑 desc: "nodePort is required and must be in range when service type is NodePort" severity: error - expr: "!(has(values.autoscaling)) || (values.autoscaling.minReplicas <= values.autoscaling.maxReplicas)" # 4. 逻辑或处理可选字段的跨字段校验 desc: "if autoscaling is set, minReplicas must be <= maxReplicas" severity: warning # 设置为 warning，仅提示不阻断

关键语法解读：

• has()函数：这是 CEL 中用于检查映射（Map）或消息（Message）中是否存在某个键的核心函数。在 helm-cel 的上下文中，values就是你的values.yaml被解析成的对象，has(values.service)等价于检查service这个键是否存在。
• 字段路径访问：使用点号.来访问嵌套字段，如values.service.port。如果中间路径可能不存在，直接访问会求值错误。更安全的写法是先has()检查，或者使用 CEL 的 可选链式访问 （如果 helm-cel 使用的 CEL 版本支持）。目前看来，结合has()和逻辑运算符是通用做法。
• 表达式插值：在expr中，可以通过${expressionName}的语法来引用在expressions块中定义的子表达式。这极大地提高了复杂规则的可读性和可维护性。
• 三元运算符：condition ? true_value : false_value。这是实现“如果...那么...”逻辑的利器，比 JSON Schema 的if-then-else直观太多。
• 逻辑运算符：&&(与),||(或),!(非)。用于组合多个条件。

4.2 组织复杂的规则：多文件与模块化

当你的 Chart 非常复杂，拥有数十个甚至上百个校验规则时，把所有规则堆在一个values.cel.yaml里会是一场噩梦。helm-cel 支持多规则文件。

你可以按照 Chart 的组件或功能模块来拆分规则：

my-complex-chart/ ├── Chart.yaml ├── values.yaml └── cel/ # 创建一个专门的目录存放规则 ├── 00-required.cel.yaml # 全局必填字段校验 ├── 10-resources.cel.yaml # 资源请求与限制校验 ├── 20-network.cel.yaml # 服务、Ingress 网络相关校验 ├── 30-storage.cel.yaml # 持久化存储校验 └── 99-custom.cel.yaml # 业务特定逻辑校验

在验证时，指定多个规则文件：

helm cel validate ./my-complex-chart --rules-file cel/00-required.cel.yaml,cel/10-resources.cel.yaml,cel/20-network.cel.yaml

或者使用多个-r标志：

helm cel validate ./my-complex-chart \ -r cel/00-required.cel.yaml \ -r cel/10-resources.cel.yaml \ -r cel/20-network.cel.yaml

重要规则：所有规则文件中的expressions定义是共享全局命名空间的。这意味着你在00-required.cel.yaml中定义的表达式，可以在20-network.cel.yaml的规则中通过${expressionName}引用。但同时，表达式名称不能重复，否则会发生冲突。

实操心得：我强烈建议采用这种分文件的方式。它不仅让结构清晰，更重要的是，它允许你在 CI/CD 中实现分层校验。例如，在开发环境，你可能只运行00-required.cel.yaml和20-network.cel.yaml进行基本校验；而在生产环境部署前，则运行全部规则文件进行严格校验。这可以通过在 CI 脚本中动态组合--rules-file参数来实现。

4.3 高级校验模式与实战案例

让我们看几个更贴近真实生产环境的复杂校验案例。

案例一：互斥字段校验假设你的 Chart 支持从私有仓库拉取镜像，需要提供image.credentials，但也支持使用工作负载身份（如 K8s ServiceAccount）。两者只能选其一。

# values.yaml 片段 image: repository: my.registry.com/app tag: v1.0 # 方案A：使用密码 credentials: username: myuser passwordSecret: my-secret # 方案B：使用 workloadIdentity workloadIdentity: serviceAccount: app-sa gcpServiceAccount: app@project.iam.gserviceaccount.com

校验规则：

rules: - expr: '!(has(values.image.credentials) && has(values.image.workloadIdentity))' desc: "Cannot specify both 'image.credentials' and 'image.workloadIdentity'. Choose one."

案例二：基于枚举值的复杂依赖假设应用部署模式（deployment.mode）决定其他字段的必填性。

# values.yaml 片段 deployment: mode: "ha" # 可能为 "standalone", "ha", "cluster" replicas: 3 # 当 mode 为 "ha" 或 "cluster" 时，以下字段必填 leaderElection: enabled: true leaseDuration: 15s

校验规则：

expressions: isHaOrCluster: 'values.deployment.mode in ["ha", "cluster"]' rules: - expr: 'values.deployment.mode in ["standalone", "ha", "cluster"]' desc: "deployment.mode must be one of: standalone, ha, cluster" - expr: '${isHaOrCluster} ? has(values.deployment.leaderElection) : true' desc: "leaderElection config is required for HA or cluster mode" - expr: '${isHaOrCluster} && has(values.deployment.leaderElection) ? values.deployment.leaderElection.enabled == true : true' desc: "leaderElection must be enabled for HA or cluster mode"

案例三：列表内容校验校验一个端口列表，要求每个端口对象都有合法的配置。

# values.yaml 片段 ports: - name: http containerPort: 8080 protocol: TCP - name: metrics containerPort: 9090 protocol: TCP

校验规则：

rules: - expr: 'type(values.ports) == list' desc: "ports must be a list" - expr: 'values.ports.all(p, has(p.name) && has(p.containerPort) && p.containerPort > 0 && p.containerPort <= 65535 && p.protocol in ["TCP", "UDP", "SCTP"])' desc: "each port entry must have a name, valid containerPort, and supported protocol"

这里使用了 CEL 的list.all(p, condition)宏，它对列表中的每个元素应用条件检查，只有所有元素都满足条件时，整个表达式才为真。这是校验列表内容的强大工具。

5. 集成到工作流：CI/CD、本地开发与自动化生成

工具的强大在于如何融入现有流程。helm-cel 的设计充分考虑了从本地开发到自动化部署的各个环节。

5.1 本地开发：即时反馈与快速迭代

在开发 Chart 时，最痛苦的就是写完values.yaml后，需要等到helm install --dry-run或实际部署时才能发现配置错误。有了 helm-cel，你可以把它集成到你的编辑器或终端工作流中。

方法一：使用文件监视工具（如entr）

# 当 values.yaml 或 values.cel.yaml 文件变化时，自动运行校验 ls values.yaml values.cel.yaml | entr -c helm cel validate .

这提供了实时的、红灯/绿灯式的反馈，极大提升开发效率。

方法二：集成到 Makefile 或 Justfile在你的 Chart 项目根目录创建一个Makefile：

.PHONY: validate lint test validate: @echo "Validating Helm values..." helm cel validate . lint: validate helm lint . test: lint helm template . --dry-run > /dev/null @echo "All checks passed!"

这样，运行make test就会依次执行值校验、Chart 语法检查和模板渲染测试，形成一个完整的本地质量门禁。

5.2 CI/CD 流水线集成：作为质量关卡

这是 helm-cel 的核心应用场景。利用其不同的退出码，你可以轻松地在 CI 流水线中创建决策点。

# 以 GitLab CI 为例 stages: - validate - test - deploy validate-helm: stage: validate image: idsulik/helm-cel:latest # 直接使用插件镜像 script: - helm cel validate . --output json > validation-result.json artifacts: paths: - validation-result.json expire_in: 1 week # 根据退出码决定 job 状态 allow_failure: exit_codes: - 2 # 允许只有 warnings 的情况通过

# 以 GitHub Actions 为例 name: Helm Validation on: [push, pull_request] jobs: validate: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Install Helm uses: azure/setup-helm@v3 - name: Install helm-cel plugin run: helm plugin install https://github.com/idsulik/helm-cel - name: Validate Chart Values run: | helm cel validate . # 脚本会因非零退出码而失败，但我们可以捕获并处理 continue-on-error: true # 先继续，以便收集结果 - name: Check Validation Result run: | # 通过 $? 获取上一个命令的退出码 if [ $? -eq 1 ]; then echo "❌ Validation failed with ERRORS. Failing the build." exit 1 elif [ $? -eq 2 ]; then echo "⚠️ Validation passed with WARNINGS. Continuing..." # 可以在这里发送通知到 Slack 等 else echo "✅ Validation passed successfully." fi

退出码策略详解：

• 0 - 成功：没有错误，也没有警告。流水线可以安心进入下一步。
• 1 - 错误：至少有一条severity: error的规则未通过。这应该导致 CI 失败，阻止合并或部署。
• 2 - 警告：没有错误，但至少有一条severity: warning的规则未通过。这可以配置为“允许失败但发出警告”，让流程继续，但通过日志或通知告知开发者需要关注。

结构化输出集成：对于更高级的流水线，你可以使用-o json或-o yaml输出，然后将结果文件解析，集成到 CI 系统的测试报告界面，或者根据错误/警告的数量和类型触发不同的后续流程。

5.3 自动化生成：从现有 Values 快速搭建规则框架

对于已有的、庞大的values.yaml文件，手动编写所有校验规则是一项艰巨的任务。helm-cel 的generate子命令可以帮你快速搭建一个基础框架。

helm cel generate ./mychart

这个命令会读取./mychart/values.yaml，分析其结构，并生成一个对应的./mychart/values.cel.yaml文件。生成的内容主要包含：

1. 对所有非空字段生成has()规则，标记为warning（因为有些字段可能是可选的）。
2. 对数字类型的字段（如replicaCount,port）生成一个示例性的范围校验（如>= 0），同样标记为warning。
3. 对字符串类型的字段，如果其值看起来像特定模式（如内存\"128Mi\"），可能会生成一个简单的正则匹配规则。

重要提示：generate命令是一个辅助工具，而非最终解决方案。它生成的规则是保守的、提示性的。你必须仔细审查并修改生成的规则：

• 将真正必填字段的severity从warning改为error。
• 修正数字范围，例如将port >= 0改为port >= 1 && port <= 65535。
• 添加复杂的业务逻辑校验，如字段间依赖、条件必填等。
• 使用expressions块来提炼和复用公共逻辑。

你可以把它看作是一个“脚手架生成器”，它能节省你 50% 的初始打字工作，但剩下的 50% 关乎业务逻辑，必须由你来完成。

6. 常见问题、排查技巧与性能考量

在实际使用中，你可能会遇到一些问题。下面是我踩过的一些坑和总结的技巧。

6.1 常见错误与排查表

6.2 性能考量与最佳实践

对于包含数百条规则的复杂 Chart，校验速度是需要关注的。以下是一些优化建议：

1. 规则顺序：将最可能失败、最基础的校验（如必填字段检查）放在规则列表的前面。CEL 引擎在遇到第一个false的error规则时，会停止评估后续规则吗？这取决于实现，但将关键规则前置是一个好习惯。
2. 避免过度复杂的表达式：虽然 CEL 功能强大，但一个非常长的、嵌套很深的表达式会影响可读性和解析性能。尽量利用expressions块进行拆分和复用。
3. 谨慎使用all/exists宏遍历大列表：如果values.yaml中有一个包含成千上万个元素的列表，对其每个元素执行复杂校验可能会较慢。评估是否真的需要在 Helm 层面进行如此细粒度的校验，或许这部分校验应该放在应用启动或专门的配置服务中。
4. 在 CI 中缓存插件：如果 CI 环境每次都要下载 helm-cel 插件或 Docker 镜像，会增加流水线时间。可以考虑在自定义的 CI 镜像中预装插件，或使用本地镜像仓库缓存 Docker 镜像。

6.3 调试技巧

1. 使用详细输出：-o json输出格式包含了完整的错误上下文，包括违反的规则描述、表达式、当前值和路径，是调试的最佳工具。
2. 简化复现：当一条复杂规则失败时，尝试创建一个最小的values.yaml片段，只包含规则涉及到的字段，然后单独测试这条规则，以隔离问题。
3. 理解求值环境：记住，CEL 表达式中的values对象对应的是经过 Helm 合并和计算后的最终值（如果你用了--values-file指定了多个文件）。使用helm template --debug或helm get values <release-name>来确认最终生效的值是什么，这有助于编写准确的规则。

7. 与现有生态的对比与整合建议

helm-cel 并非要完全取代其他工具，而是填补了一个特定的空白。了解它的定位，有助于你更好地设计配置管理流程。

vs. Helmvalues.schema.json

• helm-cel：胜在表达力和可维护性。适合复杂逻辑校验、条件依赖和团队协作。规则文件是 YAML，更易读易写。
• JSON Schema：是 Helm 原生支持，无需额外插件。适合简单的类型校验和数据结构描述。一些 IDE 插件能基于 JSON Schema 提供自动补全。
• 建议：对于新项目，或现有项目遇到 JSON Schema 表达能力瓶颈时，积极采用 helm-cel。两者甚至可以共存（虽然没必要），因为 helm-cel 是独立插件。

vs. Kubernetes ValidatingAdmissionPolicy (VAP)

• helm-cel：在CI/CD 或客户端执行校验，属于“左移”实践。能在代码合并和构建镜像前就发现问题，反馈周期短，成本低。
• VAP：在Kubernetes API 服务器层面执行校验，是最后一道防线。能防止任何不符合策略的资源配置被持久化到集群。
• 建议：两者结合，形成纵深防御。用 helm-cel 在开发部署流程早期拦截大部分错误；用 VAP 在集群入口处强制执行安全策略（如“所有 Pod 必须设置资源限制”）。它们可以使用相似的 CEL 表达式，实现策略即代码的统一。

vs. 其他配置校验工具 (如kubeval,kubeconform)

• 其他工具：主要校验生成的 Kubernetes YAML 清单是否符合 Kubernetes API Schema。
• helm-cel：专注于校验Helm Values这个输入层，更早地发现问题。两者的关注点不同，是互补关系。
• 建议：在 CI 流水线中顺序执行：helm cel validate(校验输入值) ->helm template(生成清单) ->kubeconform(校验清单语法)。这样就从输入到输出建立了完整的校验链。

我个人在实际项目中的体会是，引入 helm-cel 后，关于“为什么部署失败了？”的讨论中，因values.yaml配置错误导致的比例下降了超过 80%。它把一种模糊的、容易出错的配置约定，变成了一套明确的、可执行的、可版本化的规则。对于任何维护着非 trivial 的 Helm Chart 的团队来说，这都是一项值得投入的基础设施投资。最后一个小技巧：将你的cel/规则目录和values.cel.yaml文件也纳入代码审查流程，就像审查应用代码一样。因为，这些规则本质上就是你的配置契约。