⚡

Helm图表构建与部署Skill helm-chart-scaffolding

这个技能提供创建、组织和管理Helm图表的全面指导，用于通过模板化和打包Kubernetes应用程序，实现可重用配置和自动化部署。包括图表结构设计、值管理、依赖项处理、多环境支持以及最佳实践。关键词：Helm, Kubernetes, 图表模板, 应用程序部署, DevOps, 云原生, 容器编排。

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

name: helm-chart-scaffolding description: 设计、组织和管理Helm图表，用于通过可重用配置模板化和打包Kubernetes应用程序。在创建Helm图表、打包Kubernetes应用程序或实现模板化部署时使用。

Helm图表脚手架

创建、组织和打包及部署Kubernetes应用程序的Helm图表的全面指导。

目的

此技能提供构建生产就绪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. 创建模板文件

使用Helm函数的Go模板：

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图表部署