从零编写一个 Helm Chart：把自研应用打包成可复用交付物

demo-app/
├── Chart.yaml          # Chart 的元信息：名称、版本、应用版本，必填
├── values.yaml         # 默认参数值，所有可变项的唯一出处
├── values-prod.yaml    # 环境覆盖文件（自备，部署时用 -f 指定，不属于 Chart 规范但很常用）
├── templates/          # 模板目录，渲染后产出最终 YAML
│   ├── _helpers.tpl    # 命名、标签等可复用模板片段，不直接产出资源
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── ingress.yaml
│   ├── serviceaccount.yaml
│   └── NOTES.txt       # 安装成功后给使用者看的提示信息
└── charts/             # 依赖的子 Chart（有依赖时由 helm dependency 生成，不要手改）

apiVersion: v2
name: demo-app
description: A demo web application chart
type: application
version: 0.3.0        # Chart 自身版本：模板或默认值有变化就递增，与应用无关
appVersion: "1.4.2"   # 应用版本：对应镜像的业务版本，默认作为镜像 tag 的取值来源

replicaCount: 1

image:
  repository: harbor.example.com/apps/demo-app
  tag: ""               # 留空时模板回退到 Chart.yaml 的 appVersion，避免两处维护
  pullPolicy: IfNotPresent

service:
  type: ClusterIP
  port: 80

ingress:
  enabled: false        # 可选资源一律用开关控制，默认关，按需打开
  host: app.example.com
  tls:
    enabled: false
    secretName: ""

resources: {}           # 资源请求与限制不给假默认值，强制部署方显式填写

config:
  logLevel: info
  featureX: "off"

# values-prod.yaml
replicaCount: 3
ingress:
  enabled: true
  host: app.example.com
  tls:
    enabled: true
    secretName: example-com-tls
resources:
  requests:
    cpu: 200m
    memory: 256Mi
  limits:
    cpu: "1"
    memory: 512Mi
config:
  logLevel: warn

{{- define "demo-app.name" -}}
{{- .Chart.Name | trunc 63 | trimSuffix "-" }}
{{- end }}

{{- define "demo-app.fullname" -}}
{{- printf "%s-%s" .Release.Name .Chart.Name | trunc 63 | trimSuffix "-" }}
{{- end }}

{{- define "demo-app.labels" -}}
app.kubernetes.io/name: {{ include "demo-app.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
helm.sh/chart: {{ printf "%s-%s" .Chart.Name .Chart.Version }}
{{- end }}

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "demo-app.fullname" . }}
  labels:
    {{- include "demo-app.labels" . | nindent 4 }}
spec:
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels:
      app.kubernetes.io/name: {{ include "demo-app.name" . }}
      app.kubernetes.io/instance: {{ .Release.Name }}
  template:
    metadata:
      labels:
        app.kubernetes.io/name: {{ include "demo-app.name" . }}
        app.kubernetes.io/instance: {{ .Release.Name }}
    spec:
      containers:
        - name: {{ .Chart.Name }}
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
          imagePullPolicy: {{ .Values.image.pullPolicy }}
          ports:
            - containerPort: 8080
          env:
            {{- range $key, $val := .Values.config }}
            - name: {{ $key | upper | quote }}
              value: {{ $val | quote }}
            {{- end }}
          {{- with .Values.resources }}
          resources:
            {{- toYaml . | nindent 12 }}
          {{- end }}

apiVersion: v1
kind: Service
metadata:
  name: {{ include "demo-app.fullname" . }}
  labels:
    {{- include "demo-app.labels" . | nindent 4 }}
spec:
  type: {{ .Values.service.type }}
  ports:
    - port: {{ .Values.service.port }}
      targetPort: 8080
  selector:
    app.kubernetes.io/name: {{ include "demo-app.name" . }}
    app.kubernetes.io/instance: {{ .Release.Name }}

{{- if .Values.ingress.enabled }}
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: {{ include "demo-app.fullname" . }}
  labels:
    {{- include "demo-app.labels" . | nindent 4 }}
spec:
  ingressClassName: nginx
  {{- if .Values.ingress.tls.enabled }}
  tls:
    - hosts:
        - {{ .Values.ingress.host }}
      secretName: {{ .Values.ingress.tls.secretName }}
  {{- end }}
  rules:
    - host: {{ .Values.ingress.host }}
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: {{ include "demo-app.fullname" . }}
                port:
                  number: {{ .Values.service.port }}
{{- end }}

# 1. 语法与规范检查
helm lint ./demo-app -f values-prod.yaml
# 2. 本地渲染，看最终 YAML 是否符合预期（排版、缩进、值是否生效）
helm template demo ./demo-app -f values-prod.yaml | less
# 3. 服务端干跑，让 API Server 做一次真实校验但不落库
helm install demo ./demo-app -f values-prod.yaml --dry-run=server -n prod
# 4. 打包并推送到 OCI 仓库（Harbor 原生支持），或上传到传统 Chart 仓库
helm package ./demo-app
helm push demo-app-0.3.0.tgz oci://harbor.example.com/charts

# 确认 Release 状态与实际资源
helm status demo -n prod
helm get values demo -n prod        # 核对生效的 values 是否与覆盖文件一致
kubectl get deploy,svc,ingress -n prod -l app.kubernetes.io/instance=demo
# 故意用错一个值再 template 一次，确认渲染会报错而不是静默产出坏 YAML
helm template demo ./demo-app --set replicaCount=abc