helm install my-release bitnami/nginx
  → Helm CLI 读取 Chart
  → 合并 values.yaml 和用户自定义值
  → 渲染 Go Template
  → 将生成的 YAML 提交到 Kubernetes API
  → 创建 Release（存储在 Secret 中）

# if-else
{{ if .Values.persistence.enabled }}
persistence:
  enabled: true
  size: {{ .Values.persistence.size }}
{{ end }}

# range 循环
{{ range .Values.ports }}
- name: {{ .name }}
  containerPort: {{ .containerPort }}
{{ end }}

# with 作用域
{{ with .Values.securityContext }}
securityContext:
  runAsUser: {{ .runAsUser }}
  fsGroup: {{ .fsGroup }}
{{ end }}

# 默认值
replicas: {{ .Values.replicaCount | default 1 }}

# 大小写转换
name: {{ .Values.appName | upper }}
env: {{ .Values.env | lower }}

# 缩进对齐
{{ .Files.Get "config.yaml" | indent 4 }}

# include 引用
{{ include "mychart.labels" . | nindent 4 }}

# quote 和 squote
name: {{ .Values.name | quote }}

# tpl（字符串模板渲染）
{{ tpl .Values.templateString . }}

# Chart.yaml
dependencies:
- name: postgresql
  version: "12.x"
  repository: "https://charts.bitnami.com/bitnami"
  condition: postgresql.enabled  # 条件启用
  tags:
  - database
- name: redis
  version: "17.x"
  repository: "https://charts.bitnami.com/bitnami"
  condition: redis.enabled
  tags:
  - cache
- name: local-chart
  version: "0.1.0"
  repository: "file://../local-chart"  # 本地路径

# 下载依赖到 charts/ 目录
helm dependency update

# 构建依赖（更新 Chart.lock）
helm dependency build

# 列出依赖
helm dependency list

# 父 Chart values.yaml
postgresql:
  enabled: true
  auth:
    database: myapp
    username: myapp
redis:
  enabled: false

apiVersion: batch/v1
kind: Job
metadata:
  name: {{ .Release.Name }}-db-migrate
  annotations:
    "helm.sh/hook": post-upgrade
    "helm.sh/hook-weight": "5"           # 执行顺序（数值越小越先）
    "helm.sh/hook-delete-policy": hook-succeeded  # 成功后删除
spec:
  template:
    spec:
      containers:
      - name: migrate
        image: myapp/migrate:latest
        command: ["/bin/migrate.sh"]
      restartPolicy: Never

# 优先级从高到低（后传入的 -f 优先级更高，按顺序合并）
helm install myapp ./mychart \
  --set image.tag=prod-latest \              # 最高
  -f custom-values.yaml \                    # 次高（最后 -f 优先）
  -f prod-values.yaml                        # 第三

**三路合并优势：** 手动修改过的 K8s 资源不会被直接覆盖，Helm 会识别集群状态差异并尝试智能合并。

**回滚：**

**回滚行为：**

- 回滚 = 使用旧 Revision 的 values 重新渲染并应用
- 回滚本身会创建新 Revision
- 回滚不影响 Secret 中存储的历史

helm install myapp ./mychart \
  --wait \                    # 等待所有 Pod 进入 Ready
  --timeout 10m \             # 超时时间
  --atomic \                  # 失败时自动回滚
  --create-namespace          # 自动创建命名空间

graph TD
    A["config/"] --> B["values.yaml<br/>公共基础配置"]
    A --> C["values-dev.yaml<br/>开发环境覆盖"]
    A --> D["values-staging.yaml<br/>预发布覆盖"]
    A --> E["values-prod.yaml<br/>生产覆盖"]
```text

**安装命令：**

**values.yaml（基础）：**

**values-prod.yaml（覆盖）：**

# 登录 OCI 注册表
helm registry login registry.example.com

# 推送 Chart 到 OCI
helm package mychart
helm push mychart-1.0.0.tgz oci://registry.example.com/helm-charts

# 从 OCI 安装
helm install myapp oci://registry.example.com/helm-charts/mychart --version 1.0.0

# 从 OCI 拉取
helm pull oci://registry.example.com/helm-charts/mychart --version 1.0.0

# 语法检查
helm lint ./mychart

# 带严格模式
helm lint ./mychart --strict

# 检查结果：YAML 格式、模板渲染、values 完整性
```text

**JSON Schema 校验：**

**Test（helm test）：**

# 生成 GPG 密钥
gpg --full-generate-key

# 签名 Chart
helm package --sign --key 'my-key' --keyring ~/.gnupg/secring.gpg ./mychart
# 生成 mychart-1.0.0.tgz + mychart-1.0.0.tgz.prov

# 验证签名
helm verify mychart-1.0.0.tgz
```text

**验证配置：**

# 父 Chart values.yaml
global:
  imageRegistry: "registry.internal.company.com"
  env: production

subchart1:
  enabled: true
# 子 Chart 模板引用全局值
image: "{{ .Values.global.imageRegistry }}/myapp:{{ .Values.image.tag }}"

# 使用 kustomize 作为 PostRenderer
helm install myapp ./mychart \
  --post-renderer ./kustomize-wrapper.sh
```text

**典型用途：**

- 注入 Sidecar（如 Istio）
- 添加通用 Label/Annotation
- 密钥加密（SealedSecrets）
- 资源转换（Helm → Kustomize 混合使用）

# common/Chart.yaml
apiVersion: v2
name: common
type: library        # 标记为 Library Chart
version: 1.0.0
# common/templates/_helpers.tpl
{{- define "common.name" -}}
{{- printf "%s-%s" .Release.Name .Chart.Name | trunc 63 | trimSuffix "-" }}
{{- end }}

{{- define "common.labels" -}}
app.kubernetes.io/name: {{ include "common.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
{{- end }}

{{- define "common.probe" -}}
initialDelaySeconds: {{ .delay | default 5 }}
periodSeconds: {{ .period | default 10 }}
{{- end }}
```text

**使用 Library Chart：**

# 查看 Release Secret（Secret type 字段为 helm.sh/release.v1）
kubectl get secret -n mynamespace -l owner=helm

# 查看 Secret 中的 Release 数据（Secret 名称格式：sh.helm.release.v1.<release>.v<revision>）
kubectl get secret sh.helm.release.v1.myapp.v1 -o jsonpath='{.data.release}' | base64 -d | base64 -d | gunzip
```text

**Release 存储优化：**

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: myapp
spec:
  source:
    repoURL: https://git.example.com/helm-charts
    path: mychart
    targetRevision: HEAD
    helm:
      valueFiles:
      - values.yaml
      - values-prod.yaml
      parameters:
      - name: image.tag
        value: v1.2.3
      releaseName: myapp
  destination:
    server: https://kubernetes.default.svc
    namespace: production
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

# secrets.yaml（加密文件）
apiVersion: v1
kind: Secret
metadata:
  name: mysecret
type: Opaque
stringData:
  password: ENC[AES256_GCM,data:encrypted-base64]
```bash

**方案 2：External Secrets Operator**

**方案 3：Sealed Secrets**

apiVersion: batch/v1
kind: Job
metadata:
  name: pre-upgrade-job
  annotations:
    "helm.sh/hook": pre-upgrade
    "helm.sh/hook-weight": "-5"  # 负数权重 = 更早执行
    "helm.sh/hook-delete-policy": before-hook-creation,hook-succeeded
spec:
  template:
    spec:
      restartPolicy: Never
      containers:
      - name: job
        image: busybox
        command: ["sh", "-c", "echo pre-upgrade check"]

# Chart.yaml
apiVersion: v2
name: mychart
version: 1.0.0
kubeVersion: ">= 1.21.0-0"  # 最低 K8s 版本

# 根据 K8s 版本选择 API 版本
{{- if .Capabilities.APIVersions.Has "apps/v1" }}
apiVersion: apps/v1
{{- else }}
apiVersion: extensions/v1beta1
{{- end }}

# 检查特定 CRD 是否存在
{{- if .Capabilities.APIVersions.Has "monitoring.coreos.com/v1" }}
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
{{- end }}

# 根据 K8s 版本选择特性
{{- if semverCompare ">=1.21-0" .Capabilities.KubeVersion.Version }}
topologySpreadConstraints:
- maxSkew: 1
  topologyKey: topology.kubernetes.io/zone
{{- end }}

# templates/NOTES.txt
Thank you for installing {{ .Chart.Name }}.

Your application is running at:
  http://{{ .Values.ingress.host }}

Get the admin password:
  kubectl get secret {{ .Release.Name }}-admin -o jsonpath="{.data.password}" | base64 --decode

To test the connection:
  helm test {{ .Release.Name }}

# 查询已有 ConfigMap
{{- $cm := lookup "v1" "ConfigMap" .Release.Namespace "myconfig" }}
{{- if $cm }}
configData: {{ $cm.data }}
{{- else }}
configData: {}
{{- end }}

# 查询 Secret 是否存在（避免覆盖已有密钥）
{{- $existingSecret := lookup "v1" "Secret" .Release.Namespace (printf "%s-db" .Release.Name) }}
{{- if not $existingSecret }}
apiVersion: v1
kind: Secret
metadata:
  name: {{ .Release.Name }}-db
data:
  password: {{ randAlphaNum 16 | b64enc }}
{{- end }}

{{- if and (.Values.ingress.enabled) (not .Values.ingress.host) }}
{{- fail "ingress.host is required when ingress is enabled" }}
{{- end }}

{{- if and (.Values.persistence.enabled) (not .Values.storageClass) }}
{{- fail "storageClass is required for persistent storage" }}
{{- end }}

# 版本兼容性检查
{{- if not (semverCompare ">=1.21-0" .Capabilities.KubeVersion.Version) }}
{{- fail "Kubernetes version must be >= 1.21" }}
{{- end }}

# values.yaml
ingress:
  enabled: false
monitoring:
  enabled: true
serviceMonitor:
  enabled: "{{ .Values.monitoring.enabled }}"
# templates/ingress.yaml
{{- if .Values.ingress.enabled }}
apiVersion: networking.k8s.io/v1
kind: Ingress
...
{{- end }}
# templates/servicemonitor.yaml
{{- if .Values.serviceMonitor.enabled }}
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
...
{{- end }}

# helmfile.yaml
repositories:
- name: bitnami
  url: https://charts.bitnami.com/bitnami

releases:
- name: postgresql
  namespace: database
  chart: bitnami/postgresql
  version: 12.x
  values:
  - values/postgresql.yaml

- name: myapp
  namespace: myapp
  chart: ./charts/myapp
  values:
  - values/myapp.yaml
  needs:
  - database/postgresql
```text

# 自动生成 Release 名称
helm install --generate-name ./mychart
# Release: mychart-1712345678

# 使用模板生成名称
helm install --name-template "myapp-{{ .Chart.Version }}" ./mychart
# Release: myapp-1.0.0
```yaml