⚡

Helm图表脚手架Skill helm-chart-scaffolding

这个技能提供创建、组织和管理Helm图表的全面指导，用于打包和部署Kubernetes应用程序。关键词：Helm、Kubernetes、图表、脚手架、模板、部署、DevOps。

Docker/K8s 0 次安装 0 次浏览 更新于 3/10/2026

名称: helm-chart-scaffolding 描述: 设计、组织和管理Helm图表，用于模板化和打包Kubernetes应用程序，使用可重用配置。在创建Helm图表、打包Kubernetes应用程序或实现模板化部署时使用。 版本: 1.0.0 模型: sonnet 调用者: [devops] 工具: [Read, Write, Edit, Bash, Glob, Grep] 已验证: false 最后验证时间: 2026-02-19T05:29:09.098Z

Helm图表脚手架

全面指导如何创建、组织和管理Helm图表，用于打包和部署Kubernetes应用程序。

目的

本技能提供逐步指南，用于构建生产就绪的Helm图表，包括图表结构、模板模式、值管理和验证策略。

何时使用此技能

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

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

Helm概述

Helm是Kubernetes的包管理器，功能包括：

  • 模板化Kubernetes清单以提高可重用性
  • 管理应用程序发布和回滚
  • 处理图表之间的依赖关系
  • 为部署提供版本控制
  • 简化跨环境的配置管理

逐步工作流程

1. 初始化图表结构

创建新图表：

helm create my-app

标准图表结构：

my-app/
├── Chart.yaml           # 图表元数据
├── values.yaml          # 默认配置值
├── charts/              # 图表依赖
├── templates/           # Kubernetes清单模板
│   ├── NOTES.txt       # 安装后说明
│   ├── _helpers.tpl    # 模板辅助函数
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── ingress.yaml
│   ├── serviceaccount.yaml
│   ├── hpa.yaml
│   └── tests/
│       └── test-connection.yaml
└── .helmignore         # 忽略文件

2. 配置Chart.yaml

图表元数据定义包：

apiVersion: v2
name: my-app
description: My应用程序的Helm图表
type: application
version: 1.0.0 # 图表版本
appVersion: '2.1.0' # 应用程序版本

# 图表发现关键词
keywords:
  - web
  - api
  - backend

# 维护者信息
maintainers:
  - name: DevOps团队
    email: devops@example.com
    url: https://github.com/example/my-app

# 源代码仓库
sources:
  - https://github.com/example/my-app

# 主页
home: https://example.com

# 图表图标
icon: https://example.com/icon.png

# 依赖关系
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:
  repository: myapp
  tag: '1.0.0'
  pullPolicy: IfNotPresent

# 副本数量
replicaCount: 3

# 服务配置
service:
  type: ClusterIP
  port: 80
  targetPort: 8080

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

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

# 自动扩缩
autoscaling:
  enabled: false
  minReplicas: 2
  maxReplicas: 10
  targetCPUUtilizationPercentage: 80

# 环境变量
env:
  - name: LOG_LEVEL
    value: 'info'

# ConfigMap数据
configMap:
  data:
    APP_MODE: production

# 依赖
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：

{{/*
扩展图表名称。
*/}}
{{- define "my-app.name" -}}
{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
{{- end }}

{{/*
创建默认的完全限定应用名称。
*/}}
{{- 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 }}

{{/*
通用标签
*/}}
{{- 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 }}

{{/*
选择器标签
*/}}
{{- 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. 测试与验证

验证命令：

# 检查图表语法
helm lint my-app/

# 模拟安装
helm install my-app ./my-app --dry-run --debug

# 模板渲染
helm template my-app ./my-app

# 使用值文件渲染模板
helm template my-app ./my-app -f values-prod.yaml

# 显示计算值
helm show values ./my-app

验证脚本：

#!/bin/bash
set -e

echo "检查图表语法..."
helm lint .

echo "测试模板渲染..."
helm template test-release . --dry-run

echo "检查必需值..."
helm template test-release . --validate

echo "所有验证通过！"

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

8. 打包与分发

打包图表：

helm package my-app/
# 创建：my-app-1.0.0.tgz

创建图表仓库：

# 创建索引
helm repo index .

# 上传到仓库
# AWS S3示例
aws s3 sync . s3://my-helm-charts/ --exclude "*" --include "*.tgz" --include "index.yaml"

使用图表：

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          # 默认
├── values-dev.yaml      # 开发
├── values-staging.yaml  # 预发布
└── values-prod.yaml     # 生产

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

# 在模板中使用：
image: {{ .Values.global.imageRegistry }}/{{ .Values.image.repository }}

最佳实践

  1. 使用语义版本控制 用于图表和应用版本
  2. 在values.yaml中用注释记录所有值
  3. 使用模板辅助函数 用于重复逻辑
  4. 打包前验证图表
  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 - 图表元数据模板
  • assets/values.yaml.template - 值结构模板
  • scripts/validate-chart.sh - 验证脚本
  • references/chart-structure.md - 详细图表组织

相关技能

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

内存协议（强制）

开始前：

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

假设中断：如果不在内存中，则未发生。