helm-chart-scaffolding

Helm Chart 脚手架

关于创建、组织和管理 Helm chart，以便打包和部署 Kubernetes 应用程序的全面指南。

用途

此技能提供构建可用于生产环境的 Helm chart 的分步说明，涵盖 chart 结构、模板模式、值管理和验证策略。

何时使用此技能

在以下情况下使用此技能：

• 从头开始创建新的 Helm chart
• 打包 Kubernetes 应用程序以供分发
• 使用 Helm 管理多环境部署
• 为可复用的 Kubernetes 清单实现模板
• 设置 Helm chart 仓库
• 遵循 Helm 最佳实践和约定

Helm 概述

Helm 是 Kubernetes 的包管理器，可用于：

• 对 Kubernetes 清单进行模板化，以便复用
• 管理应用程序发布和回滚
• 处理 chart 之间的依赖关系
• 为部署提供版本控制
• 简化跨环境的配置管理

分步工作流

1. 初始化 chart 结构

创建新的 chart：

helm create my-app

标准 chart 结构：

my-app/
├── Chart.yaml           # Chart metadata
├── values.yaml          # Default configuration values
├── charts/              # Chart dependencies
├── templates/           # Kubernetes manifest templates
│   ├── NOTES.txt       # Post-install notes
│   ├── _helpers.tpl    # Template helpers
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── ingress.yaml
│   ├── serviceaccount.yaml
│   ├── hpa.yaml
│   └── tests/
│       └── test-connection.yaml
└── .helmignore         # Files to ignore

2. 配置 Chart.yaml

chart 元数据定义了软件包：

apiVersion: v2
name: my-app
description: A Helm chart for My Application
type: application
version: 1.0.0 # Chart version
appVersion: '2.1.0' # Application version

# Keywords for chart discovery
keywords:
  - web
  - api
  - backend

# Maintainer information
maintainers:
  - name: DevOps Team
    email: [email protected]
    url: https://github.com/example/my-app

# Source code repository
sources:
  - https://github.com/example/my-app

# Homepage
home: https://example.com

# Chart icon
icon: https://example.com/icon.png

# Dependencies
dependencies:
  - name: postgresql
    version: '12.0.0'
    repository: 'https://charts.bitnami.com/bitnami'
    condition: postgresql.enabled
  - name: redis
    version: '17.0.0'
    repository: 'https://charts.bitnami.com/bitnami'
    condition: redis.enabled

参考： 查看 assets/Chart.yaml.template 获取完整示例

3. 设计 values.yaml 结构

按层次组织值：

# Image configuration
image:
  repository: myapp
  tag: '1.0.0'
  pullPolicy: IfNotPresent

# Number of replicas
replicaCount: 3

# Service configuration
service:
  type: ClusterIP
  port: 80
  targetPort: 8080

# Ingress configuration
ingress:
  enabled: false
  className: nginx
  hosts:
    - host: app.example.com
      paths:
        - path: /
          pathType: Prefix

# Resources
resources:
  requests:
    memory: '256Mi'
    cpu: '250m'
  limits:
    memory: '512Mi'
    cpu: '500m'

# Autoscaling
autoscaling:
  enabled: false
  minReplicas: 2
  maxReplicas: 10
  targetCPUUtilizationPercentage: 80

# Environment variables
env:
  - name: LOG_LEVEL
    value: 'info'

# ConfigMap data
configMap:
  data:
    APP_MODE: production

# Dependencies
postgresql:
  enabled: true
  auth:
    database: myapp
    username: myapp

redis:
  enabled: false

参考： 查看 assets/values.yaml.template 获取完整结构

4. 创建模板文件

使用 Go 模板和 Helm 函数：

templates/deployment.yaml：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "my-app.fullname" . }}
  labels:
    {{- include "my-app.labels" . | nindent 4 }}
spec:
  {{- if not .Values.autoscaling.enabled }}
  replicas: {{ .Values.replicaCount }}
  {{- end }}
  selector:
    matchLabels:
      {{- include "my-app.selectorLabels" . | nindent 6 }}
  template:
    metadata:
      labels:
        {{- include "my-app.selectorLabels" . | nindent 8 }}
    spec:
      containers:
      - name: {{ .Chart.Name }}
        image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
        imagePullPolicy: {{ .Values.image.pullPolicy }}
        ports:
        - name: http
          containerPort: {{ .Values.service.targetPort }}
        resources:
          {{- toYaml .Values.resources | nindent 12 }}
        env:
          {{- toYaml .Values.env | nindent 12 }}

5. 创建模板辅助函数

templates/_helpers.tpl：

{{/*
Expand the name of the chart.
*/}}
{{- define "my-app.name" -}}
{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
{{- end }}

{{/*
Create a default fully qualified app name.
*/}}
{{- define "my-app.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 }}

{{/*
Common labels
*/}}
{{- define "my-app.labels" -}}
helm.sh/chart: {{ include "my-app.chart" . }}
{{ include "my-app.selectorLabels" . }}
{{- if .Chart.AppVersion }}
app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
{{- end }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
{{- end }}

{{/*
Selector labels
*/}}
{{- define "my-app.selectorLabels" -}}
app.kubernetes.io/name: {{ include "my-app.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
{{- end }}

6. 管理依赖项

在 Chart.yaml 中添加依赖项：

dependencies:
  - name: postgresql
    version: '12.0.0'
    repository: 'https://charts.bitnami.com/bitnami'
    condition: postgresql.enabled

更新依赖项：

helm dependency update
helm dependency build

覆盖依赖项的值：

# values.yaml
postgresql:
  enabled: true
  auth:
    database: myapp
    username: myapp
    password: changeme
  primary:
    persistence:
      enabled: true
      size: 10Gi

7. 测试和验证

验证命令：

# Lint the chart
helm lint my-app/

# Dry-run installation
helm install my-app ./my-app --dry-run --debug

# Template rendering
helm template my-app ./my-app

# Template with values
helm template my-app ./my-app -f values-prod.yaml

# Show computed values
helm show values ./my-app

验证脚本：

#!/bin/bash
set -e

echo "Linting chart..."
helm lint .

echo "Testing template rendering..."
helm template test-release . --dry-run

echo "Checking for required values..."
helm template test-release . --validate

echo "All validations passed!"

参考： 查看 scripts/validate-chart.sh

8. 打包和分发

打包 chart：

helm package my-app/
# Creates: my-app-1.0.0.tgz

创建 chart 仓库：

# Create index
helm repo index .

# Upload to repository
# AWS S3 example
aws s3 sync . s3://my-helm-charts/ --exclude "*" --include "*.tgz" --include "index.yaml"

使用 chart：

helm repo add my-repo https://charts.example.com
helm repo update
helm install my-app my-repo/my-app

9. 多环境配置

环境专属的值文件：

my-app/
├── values.yaml          # Defaults
├── values-dev.yaml      # Development
├── values-staging.yaml  # Staging
└── values-prod.yaml     # Production

values-prod.yaml：

replicaCount: 5

image:
  tag: '2.1.0'

resources:
  requests:
    memory: '512Mi'
    cpu: '500m'
  limits:
    memory: '1Gi'
    cpu: '1000m'

autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 20

ingress:
  enabled: true
  hosts:
    - host: app.example.com
      paths:
        - path: /
          pathType: Prefix

postgresql:
  enabled: true
  primary:
    persistence:
      size: 100Gi

使用环境配置进行安装：

helm install my-app ./my-app -f values-prod.yaml --namespace production

10. 实现钩子和测试

安装前钩子：

# templates/pre-install-job.yaml
apiVersion: batch/v1
kind: Job
metadata:
  name: {{ include "my-app.fullname" . }}-db-setup
  annotations:
    "helm.sh/hook": pre-install
    "helm.sh/hook-weight": "-5"
    "helm.sh/hook-delete-policy": hook-succeeded
spec:
  template:
    spec:
      containers:
      - name: db-setup
        image: postgres:15
        command: ["psql", "-c", "CREATE DATABASE myapp"]
      restartPolicy: Never

测试连接：

# templates/tests/test-connection.yaml
apiVersion: v1
kind: Pod
metadata:
  name: "{{ include "my-app.fullname" . }}-test-connection"
  annotations:
    "helm.sh/hook": test
spec:
  containers:
  - name: wget
    image: busybox
    command: ['wget']
    args: ['{{ include "my-app.fullname" . }}:{{ .Values.service.port }}']
  restartPolicy: Never

运行测试：

helm test my-app

常见模式

模式 1：条件资源

{{- if .Values.ingress.enabled }}
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: {{ include "my-app.fullname" . }}
spec:
  # ...
{{- end }}

模式 2：遍历列表

env:
{{- range .Values.env }}
- name: {{ .name }}
  value: {{ .value | quote }}
{{- end }}

模式 3：包含文件

data:
  config.yaml: |
    {{- .Files.Get "config/application.yaml" | nindent 4 }}

模式 4：全局值

global:
  imageRegistry: docker.io
  imagePullSecrets:
    - name: regcred

# Use in templates:
image: {{ .Values.global.imageRegistry }}/{{ .Values.image.repository }}

最佳实践

1. 使用语义化版本控制管理 chart 和应用版本
2. 在 values.yaml 中使用注释说明所有值
3. 使用模板辅助函数处理重复逻辑
4. 在打包前验证 chart
5. 明确固定依赖项版本
6. 为可选资源使用条件
7. 遵循命名约定（小写字母、连字符）
8. 在 NOTES.txt 中添加使用说明
9. 使用辅助函数统一添加标签
10. 在所有环境中测试安装

故障排除

模板渲染错误：

helm template my-app ./my-app --debug

依赖项问题：

helm dependency update
helm dependency list

安装失败：

helm install my-app ./my-app --dry-run --debug
kubectl get events --sort-by='.lastTimestamp'

参考文件

• assets/Chart.yaml.template - chart 元数据模板
• assets/values.yaml.template - 值结构模板
• scripts/validate-chart.sh - 验证脚本
• references/chart-structure.md - chart 组织结构详解

相关技能

• k8s-manifest-generator - 用于创建基础 Kubernetes 清单
• gitops-workflow - 用于自动化 Helm chart 部署

记忆协议（强制）

开始之前：

cat C:\dev\projects\agent-studio\.claude\context\memory\learnings.md

完成之后：

• 新模式 -> C:\dev\projects\agent-studio\.claude\context\memory\learnings.md
• 发现问题 -> C:\dev\projects\agent-studio\.claude\context\memory\issues.md
• 做出决策 -> C:\dev\projects\agent-studio\.claude\context\memory\decisions.md

假设任务可能中断：如果没有记录在记忆中，就等于没有发生。