3. Helm Chart 结构解析：Chart.yaml、values.yaml、templates 目录、_helpers.tpl

在排查资源配额故障之前，必须彻底理解 Helm Chart 的骨架结构。云原生网关的 Helm Chart 通常包含四个核心组成部分：Chart.yaml（元数据）、values.yaml（默认配置）、templates/（Kubernetes 资源模板）以及 _helpers.tpl（模板辅助函数）。本章将逐一拆解每个文件的作用、关键字段及其与资源配额模型的关联。

3.1 Chart.yaml：Chart 的身份证

Chart.yaml 位于 Chart 根目录，定义了 Chart 的名称、版本、API 版本等元数据。在资源配额故障排查中，apiVersion 和 kubeVersion 字段直接影响模板引擎的行为和兼容性。

3.2 values.yaml：资源配额的默认源头

values.yaml 是资源配额故障的“第一现场”。网关的 CPU、内存、存储请求和限制均在此定义。错误的默认值或缺失的字段会直接导致 Pod 调度失败或被 OOMKill。

# 典型的云原生网关 values.yaml 资源配额片段
replicaCount: 2

image:
  repository: envoyproxy/envoy
  tag: v1.28.0
  pullPolicy: IfNotPresent

resources:
  limits:
    cpu: "2"
    memory: "2Gi"
  requests:
    cpu: "500m"
    memory: "512Mi"

autoscaling:
  enabled: true
  minReplicas: 2
  maxReplicas: 10
  targetCPUUtilizationPercentage: 80

persistence:
  enabled: true
  size: 10Gi
  storageClass: "standard"

3.3 templates/ 目录：资源模板的战场

templates/ 目录包含所有 Kubernetes 资源的 Go 模板文件。与资源配额直接相关的模板文件包括：

• deployment.yaml：定义 Pod 的 resources.requests 和 resources.limits，是配额冲突的核心文件。
• hpa.yaml：定义 HorizontalPodAutoscaler，其 targetCPUUtilizationPercentage 与 resources.requests.cpu 联动。
• pvc.yaml：定义 PersistentVolumeClaim，其 resources.requests.storage 必须小于等于 StorageClass 允许的最大值。
• serviceaccount.yaml：ServiceAccount 本身不消耗资源，但若使用 automountServiceAccountToken: true 会增加 API Server 负载。

以下是一个 deployment.yaml 中资源配额模板的典型写法：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "gateway.fullname" . }}
spec:
  replicas: {{ .Values.replicaCount }}
  template:
    spec:
      containers:
        - name: {{ .Chart.Name }}
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
          resources:
            {{- toYaml .Values.resources | nindent 12 }}

3.4 _helpers.tpl：模板函数的复用中枢

_helpers.tpl 文件以 _ 开头，不会被渲染为 Kubernetes 资源，而是提供可复用的命名模板。在资源配额场景中，_helpers.tpl 通常用于生成资源名称、标签和选择器，这些名称直接影响配额对象的标识。

{{- /* 生成网关资源的全名 */ -}}
{{- define "gateway.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 "gateway.labels" -}}
helm.sh/chart: {{ include "gateway.fullname" . }}
app.kubernetes.io/name: {{ include "gateway.fullname" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
{{- end }}

3.5 核心文件与资源配额故障的关联矩阵

下表总结了四个核心文件在资源配额故障排查中的角色：

3.6 Helm Chart 结构总览与资源配额数据流

下图展示了 Helm Chart 四个核心文件之间的数据流，以及资源配额信息如何从 values.yaml 最终传递到 Kubernetes 集群：

3.7 故障排查路径：从文件到集群

当资源配额故障发生时，建议按照以下路径逆向排查：

1. 检查集群事件： kubectl describe pod <pod-name> 查看 FailedCreatePodSandBox 或 OutOfcpu 事件。
2. 验证渲染结果： helm template . --debug | grep -A 10 "resources:" 确认资源数值是否正确。
3. 审查 values.yaml： 检查 CPU/Memory 单位、requests/limits 是否成对出现。
4. 检查 _helpers.tpl： 确认 trunc 63 是否生效，标签选择器是否与 ResourceQuota 的 scopeSelector 匹配。
5. 分析 Chart.yaml： 确认依赖的子 Chart 是否也定义了资源配额，避免遗漏。