📚 课程目录第4章第一个Schema文件

4、第一个Schema文件：创建最简单的values.schema.json，定义type和properties。

在 Helm 应用交付中，values.schema.json 是集群模板蓝图的第一道防线。它使用 JSON Schema 标准对 values.yaml 中的参数进行类型校验与结构约束，从而在部署前拦截高风险变更。本节将带领你从零创建最简 Schema 文件，理解其核心骨架。

4.1 为什么需要 Schema 文件？

没有 Schema 时，Helm 仅将 values.yaml 视为纯文本键值对，任何拼写错误、类型不匹配或缺失字段都会在运行时暴露，导致集群资源创建失败甚至安全漏洞。Schema 文件在 helm install 或 helm upgrade 时主动校验，将错误提前到 CLI 阶段。

对比维度	无 Schema	有 Schema
校验时机	运行时（Pod 启动失败）	部署前（CLI 报错）
类型安全	无，字符串/数字混用	强制类型，如 `integer`
字段缺失检测	不检测，默认空值	通过 `required` 强制
文档化能力	无	`description` 字段自描述

4.2 最简 Schema 文件结构

一个合法的 values.schema.json 必须包含两个顶级关键字：$schema 声明使用的 JSON Schema 版本，以及 type 定义根数据类型。对于 Helm values，根类型固定为 "object"，因为 values.yaml 本质是一个 YAML 对象。

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {}
}

上述代码块是 Schema 的最小可行版本。它告诉 Helm：

$schema：使用 Draft-07 规范（Helm 3.x 默认支持）。
type：根必须是对象。
properties：当前为空，表示不校验任何子字段。

实践建议：即使 properties 为空，这个 Schema 已经能拦截非对象类型的 values 输入（例如误将 values.yaml 写成纯字符串或数组）。这是最基础的准入保护。

4.3 添加第一个属性定义

在 properties 中定义具体字段。以下示例为 replicaCount 字段添加类型和描述：

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "replicaCount": {
      "type": "integer",
      "description": "应用实例副本数",
      "minimum": 1,
      "maximum": 100
    }
  }
}

此时，如果用户将 replicaCount 设置为 "3"（字符串）或 0，Helm 会立即拒绝：

Error: values don't meet the specifications of the schema(s) in the following chart(s):
- mychart:
  - replicaCount: Invalid type. Expected: integer, Given: string

4.4 Schema 与 values.yaml 的映射关系

下面的 SVG 图展示了 Schema 如何逐层映射到 values.yaml 的键值结构：

4.5 常见 type 类型速查

JSON Schema 支持六种基础类型，在 Helm values 中各有典型用途：

类型	JSON 示例	Helm 典型字段
`string`	`"nginx"`	镜像名称、命名空间、标签
`integer`	`3`	副本数、端口号、超时秒数
`number`	`0.5`	CPU 请求、内存比例
`boolean`	`true`	功能开关、启用/禁用标志
`array`	`["a","b"]`	环境变量列表、域名列表
`object`	`{}`	嵌套配置块（如 resources、affinity）

4.6 完整的最小 Schema 示例

结合上述知识，一个可用于生产的最小 Schema 文件如下。它定义了三个核心字段，并设置了合理的约束：

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "replicaCount": {
      "type": "integer",
      "description": "Pod 副本数量",
      "minimum": 1,
      "maximum": 50
    },
    "image": {
      "type": "object",
      "properties": {
        "repository": {
          "type": "string",
          "description": "容器镜像仓库地址"
        },
        "tag": {
          "type": "string",
          "description": "镜像标签",
          "pattern": "^[a-zA-Z0-9._-]+$"
        }
      },
      "required": ["repository", "tag"]
    },
    "ingress": {
      "type": "object",
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "是否启用 Ingress"
        }
      }
    }
  },
  "required": ["replicaCount", "image"]
}

高风险变更拦截点：上述 Schema 中 required 字段强制要求 replicaCount 和 image 必须存在。如果用户误删这两个字段，Helm 会直接拒绝部署，避免集群模板蓝图因缺失关键配置而崩溃。

4.7 验证 Schema 是否生效

将上述内容保存为 values.schema.json，放在 Chart 根目录（与 Chart.yaml 同级）。执行以下命令验证：

# 正常 values 应通过校验
helm install myapp ./mychart --values good-values.yaml

# 错误 values 应被拦截
helm install myapp ./mychart --values bad-values.yaml
# 输出：Error: values don't meet the specifications of the schema(s)

至此，你已经创建了第一个 values.schema.json 文件。它虽然简单，但已经具备了类型校验、字段约束和必填项检查三大核心能力，为后续覆盖更复杂的集群模板蓝图高风险变更打下了基础。