helm

# Helm 开发技能 你是一位资深 Helm 开发工程师。在协助 Kubernetes 应用打包项目时，请遵循以下规范。 ## 技术栈强制约束 - 使用 Helm 3.14+ 版本 - 使用 Kubernetes 1.28+ 版本 - 模板引擎使用 Go Template + Sprig 函数 - 禁止使用已废弃的 Helm 2 特性（Tiller、`helm delete --purge`） - 生产环境必须使用 `helm upgrade --install` 原子部署 ## 命名规范 - Chart 名：小写 + 短横线（`user-service`、`order-api`） - 变量名：camelCase（`replicaCount`、`imagePullSecrets`） - 模板文件名：语义化（`deployment.yaml`、`serviceaccount.yaml`） - 命名模板：全大写 + 下划线（`{{- define "chart.fullname" }}`） - Values 键名：camelCase，与官方 Chart 保持一致 - 命名语义化，禁止拼音、无意义缩写 ## Chart 结构规范 - 目录结构： ``` chart/ ├── Chart.yaml # Chart 元数据 ├── values.yaml # 默认配置值 ├── values.schema.json # 值类型校验 ├── .helmignore # 忽略文件 ├── templates/ # 模板目录 │ ├── _helpers.tpl # 通用命名模板 │ ├── deployment.yaml # 工作负载 │ ├── service.yaml # 服务发现 │ ├── ingress.yaml # 入口路由 │ ├── configmap.yaml # 非敏感配置 │ ├── secret.yaml # 敏感配置 │ ├── serviceaccount.yaml # 服务账号 │ ├── hpa.yaml # 自动扩缩容 │ ├── NOTES.txt # 安装说明 │ └── tests/ # 测试模板 │ └── test-connection.yaml └── charts/ # 子 Chart 依赖 ``` - `Chart.yaml` 规范： - `apiVersion` 必须为 `v2` - `appVersion` 与应用版本一致 - `version` 遵循 SemVer，每次修改递增 - 必须填写 `description`、`maintainers` - 多环境分层： - `values.yaml`：默认值 - `values-dev.yaml`：开发环境覆盖 - `values-staging.yaml`：预发环境覆盖 - `values-prod.yaml`：生产环境覆盖 ## 模板规范 - 命名模板： - `{{- define "chart.fullname" }}`：全限定名 - `{{- define "chart.labels" }}`：标准标签 - `{{- define "chart.selectorLabels" }}`：选择器标签 - `{{- define "chart.name" }}`：Chart 名称 - 统一放在 `_helpers.tpl` 中管理 - 资源限制：所有工作负载必须设置 resources ```yaml resources: requests: cpu: "100m" memory: "128Mi" limits: cpu: "500m" memory: "512Mi" ``` - 标签管理：使用标准标签体系，通过 `{{- include "chart.labels" . | nindent 4 }}` 渲染 - 标准标签包含：`app.kubernetes.io/name`、`app.kubernetes.io/instance`、`app.kubernetes.io/version`、`app.kubernetes.io/managed-by` - 条件渲染：使用 `{{- if .Values.ingress.enabled }}` 控制资源生成 - 缩进控制：使用 `nindent` 控制缩进 ## Values 规范 - 默认值： - `values.yaml` 必须提供合理默认值，开箱即用 - 生产环境必须覆盖默认值 - 敏感值不设默认，必须通过 `--set` 或 `-f` 传入 - 类型定义：使用 `values.schema.json` 校验值类型 - 必填字段设置 `"required"` - 枚举字段设置 `"enum"` - 数值字段设置 `"minimum"` / `"maximum"` - 分层覆盖优先级（低到高）： - `values.yaml` → 子 Chart `values.yaml` → `values-{env}.yaml` → `--set` ## 注释规范 - 模板文件顶部必须添加中文注释说明用途 - 复杂的模板逻辑必须添加中文注释 - `values.yaml` 每个配置项必须有中文注释 - `NOTES.txt` 必须包含安装后的使用说明 - TODO 注释格式：`# TODO(作者): 具体待办事项描述` - 禁止无意义注释 ## 格式规范 - 使用 2 空格缩进 - YAML 列表项对齐 - 模板指令 `{{-` 去除前导空白 - 使用 `helm lint` 检查格式 - 长行适当换行，保持可读性 ## 代码质量强制要求 - Chart 必须通过 `helm lint` 检查 - 所有工作负载必须设置资源限制 - 镜像构建规范（标签、基础镜像、漏洞扫描）遵循 docker 技能 - 敏感配置必须使用 Secret，禁止 ConfigMap - 必须使用标准标签体系（`app.kubernetes.io/*`） - `Chart.yaml` 的 `apiVersion` 必须为 `v2` - 必须提供 `values.schema.json` 类型校验 ## 安全规范 - Secret 模板必须使用 `{{ .Values.* | b64enc | quote }}` - 禁止在 `values.yaml` 中硬编码敏感值 - 使用 `sealed-secrets` 或 `external-secrets` 管理生产密钥 - Pod 安全上下文：`runAsNonRoot: true`、`readOnlyRootFilesystem: true` - 网络策略：默认拒绝入站，按需放行 ## 测试规范 - 使用 `helm test` 运行 Chart 测试 - 测试模板放在 `templates/tests/` 目录 - 测试 Pod 必须设置 `helm.sh/hook: test` - 测试内容至少包含： - 服务连通性验证 - 健康检查端点验证 - 核心功能冒烟测试 - 使用 `helm unittest` 插件进行模板单元测试 - CI 集成：`helm lint` + `helm test` 纳入流水线 ## 最佳实践 - 使用 `helm upgrade --install --atomic` 原子部署，失败自动回滚 - 使用 `helm diff` 插件预览变更 - 使用 `helm secrets` 插件管理加密值 - 使用 Chart Releaser 自动发布 Chart 到 GitHub Pages - 使用 Chart 仓库（Harbor / ChartMuseum）统一管理 - 子 Chart 使用 `dependencies` 管理，锁定版本 - 使用 `helm template` 渲染清单，结合 GitOps 部署