4. Helm Chart 结构详解：Chart.yaml、values.yaml、templates 目录、NOTES.txt、helpers.tpl

在将 Helm Chart 接入云原生网关回滚护栏并进行租户配额校准之前，必须透彻理解 Chart 的标准目录结构与各文件的职责。一个标准的 Helm Chart 包含以下核心文件与目录：

4.1 Chart.yaml — Chart 的身份证

Chart.yaml 是每个 Helm Chart 的入口文件，定义了 Chart 的名称、版本、描述、依赖关系等元数据。在租户配额校准场景中，该文件需要额外声明配额 API 版本兼容性。

apiVersion: v2
name: tenant-quota-calibrator
description: 租户配额校准 Chart，集成云原生网关回滚护栏
type: application
version: 1.2.0
appVersion: "1.2.0"
kubeVersion: ">=1.21.0-0"
keywords:
  - tenant
  - quota
  - calibration
  - gateway
  - rollback
home: https://example.com/tenant-quota-calibrator
sources:
  - https://github.com/example/tenant-quota-calibrator
dependencies:
  - name: common
    version: ">=2.0.0"
    repository: "https://charts.example.com"
    condition: common.enabled
annotations:
  quota.api.version: "v1beta1"
  rollback.guardrail.enabled: "true"

4.2 values.yaml — 默认配置的中央仓库

values.yaml 定义了 Chart 的所有可配置参数及其默认值。在租户配额校准场景中，该文件需要包含租户配额阈值、回滚策略、网关连接信息等核心配置。

# 租户配额校准全局配置
global:
  tenantId: "default-tenant"
  environment: "production"

# 配额阈值配置
quota:
  cpu:
    limit: "4"
    request: "2"
    burst: "6"
  memory:
    limit: "8Gi"
    request: "4Gi"
    burst: "12Gi"
  storage:
    capacity: "100Gi"
    class: "ssd"

# 回滚护栏配置
rollback:
  guardrail:
    enabled: true
    maxRetries: 3
    cooldownPeriod: "30s"
    thresholdViolationPercent: 20

# 云原生网关配置
gateway:
  endpoint: "https://gateway.example.com"
  : ""
  timeout: "10s"

# 配额校准 Job 配置
calibration:
  schedule: "*/30 * * * *"
  image:
    repository: "example/quota-calibrator"
    tag: "1.2.0"
    pullPolicy: "IfNotPresent"
  resources:
    requests:
      cpu: "100m"
      memory: "128Mi"
    limits:
      cpu: "500m"
      memory: "512Mi"

4.3 templates/ 目录 — 资源模板的核心

templates/ 目录包含所有 Kubernetes 资源模板文件，使用 Go 模板语法渲染。在租户配额校准场景中，该目录通常包含以下模板：

• quota-job.yaml：创建 CronJob 或 Job，执行租户配额校验与校准逻辑。
• configmap.yaml：存储配额校准脚本或配置文件。
• gateway-route.yaml：定义云原生网关的路由规则，用于回滚护栏。
• rbac.yaml：为配额校准 Job 创建 ServiceAccount 和 RBAC 权限。
• hpa.yaml：可选，根据配额使用率自动扩缩容。

{{- /* templates/quota-job.yaml */ -}}
apiVersion: batch/v1
kind: CronJob
metadata:
  name: {{ include "tenant-quota-calibrator.fullname" . }}-calibrator
  labels:
    {{- include "tenant-quota-calibrator.labels" . | nindent 4 }}
spec:
  schedule: "{{ .Values.calibration.schedule }}"
  jobTemplate:
    spec:
      template:
        spec:
          serviceAccountName: {{ include "tenant-quota-calibrator.serviceAccountName" . }}
          containers:
          - name: calibrator
            image: "{{ .Values.calibration.image.repository }}:{{ .Values.calibration.image.tag }}"
            env:
            - name: TENANT_ID
              value: "{{ .Values.global.tenantId }}"
            - name: QUOTA_CPU_LIMIT
              value: "{{ .Values.quota.cpu.limit }}"
            - name: QUOTA_MEM_LIMIT
              value: "{{ .Values.quota.memory.limit }}"
            - name: GATEWAY_ENDPOINT
              value: "{{ .Values.gateway.endpoint }}"
            - name: ROLLBACK_ENABLED
              value: "{{ .Values.rollback.guardrail.enabled }}"
          restartPolicy: OnFailure

4.4 NOTES.txt — 安装后的用户指引

NOTES.txt 在 helm install 或 helm upgrade 成功后自动输出。在配额校准场景中，该文件用于向用户展示配额状态、回滚护栏状态以及后续操作指引。

租户配额校准 Chart 已成功部署！

部署信息：
  租户 ID: {{ .Values.global.tenantId }}
  环境: {{ .Values.global.environment }}
  配额 CPU 限制: {{ .Values.quota.cpu.limit }} 核
  配额内存限制: {{ .Values.quota.memory.limit }}
  回滚护栏: {{ if .Values.rollback.guardrail.enabled }}已启用{{ else }}未启用{{ end }}

访问配额校准状态：
  kubectl get cronjob -n {{ .Release.Namespace }} | grep calibrator

查看最近一次校准日志：
  kubectl logs -n {{ .Release.Namespace }} job/$(kubectl get jobs -n {{ .Release.Namespace }} --sort-by=.metadata.creationTimestamp -o jsonpath='{.items[-1].metadata.name}')

注意：如果配额超出阈值，回滚护栏将自动触发回滚操作。

4.5 helpers.tpl — 模板函数的复用中枢

_helpers.tpl（通常命名为 _helpers.tpl）是 Helm Chart 中定义可复用模板函数的文件。在租户配额校准场景中，该文件承担以下核心职责：

• 命名规范统一：生成统一的资源名称、标签、选择器。
• 配额计算逻辑：封装配额阈值计算、百分比校验等函数。
• 回滚判定条件：根据配额使用率判断是否需要触发回滚。
• 租户标识生成：根据全局配置生成租户唯一标识。

{{- /* _helpers.tpl */ -}}
{{- /* 生成资源全名 */ -}}
{{- define "tenant-quota-calibrator.fullname" -}}
{{- printf "%s-%s" .Release.Name .Chart.Name | trunc 63 | trimSuffix "-" }}
{{- end }}

{{- /* 生成通用标签 */ -}}
{{- define "tenant-quota-calibrator.labels" -}}
helm.sh/chart: {{ include "tenant-quota-calibrator.fullname" . }}
{{ include "tenant-quota-calibrator.selectorLabels" . }}
{{- if .Chart.AppVersion }}
app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
{{- end }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
{{- end }}

{{- /* 生成选择器标签 */ -}}
{{- define "tenant-quota-calibrator.selectorLabels" -}}
app.kubernetes.io/name: {{ include "tenant-quota-calibrator.fullname" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
{{- end }}

{{- /* 计算配额使用率百分比 */ -}}
{{- define "tenant-quota-calibrator.quotaUsagePercent" -}}
{{- $used := .used -}}
{{- $limit := .limit -}}
{{- if gt $limit 0.0 -}}
{{- printf "%.2f" (div (mul $used 100.0) $limit) -}}
{{- else -}}
0.00
{{- end -}}
{{- end }}

{{- /* 判断是否需要触发回滚 */ -}}
{{- define "tenant-quota-calibrator.shouldRollback" -}}
{{- $usagePercent := include "tenant-quota-calibrator.quotaUsagePercent" . -}}
{{- $threshold := .Values.rollback.guardrail.thresholdViolationPercent -}}
{{- if gt (float64 $usagePercent) (float64 $threshold) -}}
true
{{- else -}}
false
{{- end -}}
{{- end }}

{{- /* 生成租户唯一标识 */ -}}
{{- define "tenant-quota-calibrator.tenantId" -}}
{{- printf "%s-%s" .Values.global.tenantId .Values.global.environment | lower | replace "_" "-" }}
{{- end }}

4.6 文件组织最佳实践

在租户配额校准场景中，建议遵循以下文件组织规范：