Helm Chart 维护

Chart 发布流水线（本地 → CI → 集群）

  [ Chart 目录与版本 bump ]
        │
        ▼
  ┌─────────────┐     Chart.yaml / values / schema 一致；README 同步
  │  本地校验    │──── helm lint、helm template（+ kubeconform 可选）
  └─────────────┘
        │
        ▼
  ┌─────────────┐     ct lint、kind 安装矩阵、artifact 推送
  │  CI / CD    │──── 版本 semver；breaking 时 major 与迁移说明
  └─────────────┘
        │
        ▼
  ┌─────────────┐     install / upgrade；历史与 rollback 注释对齐发布技能
  │  集群 release │──── hook 与 CRD 顺序在 runbook 中写明
  └─────────────┘

Helm Chart 目录结构说明：

mychart/
├── Chart.yaml           # Chart 元数据（name、version、appVersion）
├── values.yaml          # 默认值（可开箱，文档化所有对外 key）
├── values.schema.json   # 类型约束与必填校验
├── README.md            # 关键 values 说明与使用示例
├── charts/              # 子 chart 依赖（helm dependency update 填充）
├── templates/
│   ├── _helpers.tpl     # 命名模板（全名、标准标签）
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── ingress.yaml
│   ├── configmap.yaml
│   ├── hpa.yaml
│   ├── pdb.yaml
│   ├── serviceaccount.yaml
│   ├── NOTES.txt        # install/upgrade 后打印的使用提示
│   └── tests/
│       └── test-connection.yaml   # helm test 测试 Pod
├── ci/                  # chart-testing 使用的 CI values 文件
│   └── ci-values.yaml
└── .helmignore          # 排除不需要打包进 Chart 的文件

Values 与 schema

用 values.schema.json 约束类型与必填项；默认值应适合最小演示环境。跨子 chart 共享配置放在 global，并在 README 说明覆盖优先级（-f 顺序、--set）。

• 镜像：repository + tag 分离，tag 通常由环境 values 注入而非写死在模板。
• 资源与副本：prod/stage 用独立 values 文件，文档列出「禁止在 prod 打开」的开关（如 debug）。
• 文档：每个对外暴露的 value 一行说明；breaking 改名时保留一期别名或迁移注释。

values.yaml 设计原则（必填/可选/环境差异）示例：

# values.yaml — 默认值可开箱运行（最小演示环境）
# 必须由外部覆盖的值，默认填 "" 并在 schema 标为 required

image:
  repository: myregistry/myapp   # 必填：由 CI 注入
  tag: ""                        # 必填：由环境 values 覆盖（不写死 latest）
  pullPolicy: IfNotPresent

replicaCount: 1                  # 开发环境默认 1；生产 values 覆盖为 3+

service:
  type: ClusterIP
  port: 80

ingress:
  enabled: false                 # 默认关闭；生产 values 开启
  className: nginx
  host: ""                       # 必须由环境 values 提供
  tls: false

resources:
  requests:
    cpu: 100m
    memory: 128Mi
  limits:
    cpu: 500m
    memory: 512Mi

autoscaling:
  enabled: false                 # 生产建议开启
  minReplicas: 2
  maxReplicas: 10
  targetCPUUtilizationPercentage: 70

# debug: false                   # 禁止在生产开启！见 values-prod.yaml 注释

---
# values-prod.yaml — 仅写差异项
# image.tag 由 CI pipeline 以 --set image.tag=1.2.3 注入
replicaCount: 3
ingress:
  enabled: true
  host: myapp.example.com
  tls: true
autoscaling:
  enabled: true
resources:
  requests:
    cpu: 250m
    memory: 256Mi
  limits:
    cpu: "1"
    memory: 1Gi

模板与参数化

使用 {{ .Values }}、required、default 与 tpl 保持 DRY；标签与选择器引用同一组变量，避免字符串漂移。可抽 _helpers.tpl 定义全名与标准标签。

_helpers.tpl 中的 helper 函数示例（全名、标准标签、selector）：

{{/*
  _helpers.tpl — mychart 的命名模板

  mychart.fullname：Chart name + release name，截断至 63 字符
*/}}
{{- define "mychart.fullname" -}}
{{- if .Values.fullnameOverride }}
{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
{{- else }}
{{- $name := default .Chart.Name .Values.nameOverride }}
{{- if contains $name .Release.Name }}
{{- .Release.Name | trunc 63 | trimSuffix "-" }}
{{- else }}
{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
{{- end }}
{{- end }}
{{- end }}

{{/*
  mychart.labels：所有资源的标准标签集
*/}}
{{- define "mychart.labels" -}}
helm.sh/chart: {{ printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 }}
app.kubernetes.io/name: {{ .Chart.Name }}
app.kubernetes.io/instance: {{ .Release.Name }}
app.kubernetes.io/version: {{ .Values.image.tag | default .Chart.AppVersion | quote }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
{{- end }}

{{/*
  mychart.selectorLabels：Deployment selector（不含 version，避免更新时冲突）
*/}}
{{- define "mychart.selectorLabels" -}}
app.kubernetes.io/name: {{ .Chart.Name }}
app.kubernetes.io/instance: {{ .Release.Name }}
{{- end }}

{{/* 在 deployment.yaml 中使用 */}}
{{/*
metadata:
  name: {{ include "mychart.fullname" . }}
  labels:
    {{- include "mychart.labels" . | nindent 4 }}
spec:
  selector:
    matchLabels:
      {{- include "mychart.selectorLabels" . | nindent 6 }}
  template:
    metadata:
      labels:
        {{- include "mychart.selectorLabels" . | nindent 8 }}
*/}}

依赖、Hook 与密钥

Chart.yaml 的 dependencies 使用兼容版本范围；子 chart 升级后在 CHANGELOG 标明。Hook 注明 hook-weight 与删除策略；与 CRD 安装顺序冲突时在技能或 runbook 中单列一节。

• 测试：chart-testing（ct）与 kind 上的 install 冒烟矩阵。
• 回滚：helm rollback 与 release 历史注释与发布技能对齐。
• 多环境：values-prod.yaml 覆盖原则与禁止项（如 dev 端点）。

CI 校验与多环境

PR 必跑：helm lint、helm template；若对接 kubeconform，固定 Kubernetes 版本列表与 CRD 来源。将「渲染后清单」作为 artifact 便于审查 diff。

Helm 命令片段实验室

填写 chart 路径与 release 名，勾选 values 文件与选项，生成可粘贴的 helm lint / helm template 片段（按本机 Helm 版本微调标志）。