4、定义网络服务的Schema：Service类型（ClusterIP/NodePort/LoadBalancer）的schema校验规则编写

在 Helm Chart 中，values.schema.json 是校验用户输入的第一道防线。对于网络拓扑中的 Service 资源，我们需要精确约束其类型（type）以及不同类型下的必填字段与可选字段。本章将聚焦于 ClusterIP、NodePort、LoadBalancer 三种核心 Service 类型的 Schema 定义规则，确保发布时不会因类型与端口配置冲突而导致部署失败。

4.1 Service 类型与字段依赖关系

Kubernetes Service 的 type 字段决定了网络流量的暴露方式。不同类型对 nodePort、loadBalancerIP、externalTrafficPolicy 等字段的约束截然不同。下表总结了三种类型的核心差异：

4.2 Schema 校验规则核心结构

在 values.schema.json 中，我们通过 JSON Schema 的 oneOf 或 if-then-else 实现类型分支校验。以下是一个针对 Service 类型的高可用 Schema 框架：

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "service": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": ["ClusterIP", "NodePort", "LoadBalancer"]
        },
        "clusterIP": {
          "type": "string",
          "pattern": "^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$"
        },
        "ports": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "port": { "type": "integer", "minimum": 1, "maximum": 65535 },
              "targetPort": { "type": "integer", "minimum": 1, "maximum": 65535 },
              "nodePort": { "type": "integer", "minimum": 30000, "maximum": 32767 }
            },
            "required": ["port"]
          }
        },
        "loadBalancerIP": { "type": "string" },
        "externalTrafficPolicy": {
          "type": "string",
          "enum": ["Cluster", "Local"]
        }
      },
      "required": ["type", "ports"],
      "allOf": [
        {
          "if": {
            "properties": { "type": { "const": "ClusterIP" } }
          },
          "then": {
            "properties": {
              "clusterIP": { "type": "string" },
              "loadBalancerIP": { "not": {} },
              "externalTrafficPolicy": { "not": {} }
            }
          }
        },
        {
          "if": {
            "properties": { "type": { "const": "NodePort" } }
          },
          "then": {
            "properties": {
              "loadBalancerIP": { "not": {} }
            }
          }
        },
        {
          "if": {
            "properties": { "type": { "const": "LoadBalancer" } }
          },
          "then": {
            "properties": {
              "loadBalancerIP": { "type": "string" },
              "externalTrafficPolicy": { "type": "string" }
            }
          }
        }
      ]
    }
  }
}

4.3 类型分支校验的 SVG 流程

下图展示了 Schema 根据 Service 类型进行条件分支校验的完整逻辑：

4.4 端口与 nodePort 的精细化校验

端口配置是 Service 校验中最容易出错的部分。我们通过 if-then 嵌套，确保 nodePort 只在 NodePort 或 LoadBalancer 类型下生效：

"allOf": [
  {
    "if": {
      "properties": { "type": { "const": "ClusterIP" } }
    },
    "then": {
      "properties": {
        "ports": {
          "items": {
            "properties": {
              "nodePort": { "not": {} }
            }
          }
        }
      }
    }
  },
  {
    "if": {
      "properties": { "type": { "enum": ["NodePort", "LoadBalancer"] } }
    },
    "then": {
      "properties": {
        "ports": {
          "items": {
            "properties": {
              "nodePort": {
                "type": "integer",
                "minimum": 30000,
                "maximum": 32767
              }
            }
          }
        }
      }
    }
  }
]

4.5 完整校验规则清单

下表汇总了三种 Service 类型下各字段的校验行为，供你在编写 Schema 时直接参考：

4.6 发布差异中的 Schema 作用

在 Helm 发布差异对比中，Schema 校验失败会导致 helm install 或 helm upgrade 直接报错退出，而不会生成 Release。这意味着：

• 提前拦截： 错误在客户端被捕获，不会发送无效配置到 Kubernetes API Server。
• 差异对比清晰： 如果 Schema 通过但实际部署失败，问题一定出在模板渲染或集群侧，缩小了排查范围。
• 团队协作： 通过 Schema 约束，不同团队提交的 values 文件格式统一，减少因类型误配导致的线上事故。