📚 课程目录第4章 Chart.yaml元数据

4. Chart.yaml 元数据：name、version、apiVersion、kubeVersion、type 字段的权限含义

Chart.yaml 是 Helm Chart 的“身份证”与“准入凭证”。在 Kubernetes 集群的权限边界与审计链路中，这五个字段不仅用于包管理，更直接决定了 Chart 能否被集群接纳、以何种身份运行、以及审计日志如何追溯。理解每个字段的权限语义，是构建安全交付流水线的第一步。

4.1 字段概览与权限映射

字段	类型	权限含义	审计影响
name	string	Chart 标识符，用于 RBAC 资源命名与策略匹配	审计日志中的资源归属主体
version	string (SemVer 2)	版本号决定升级策略与回滚权限边界	版本变更记录形成审计轨迹
apiVersion	string (v1/v2)	声明 Chart 引擎版本，决定可用的安全特性	v2 强制审计钩子与签名验证
kubeVersion	string (约束表达式)	限制 Chart 可部署的 Kubernetes 版本范围	版本不匹配时拒绝部署，产生审计事件
type	string (application/library)	定义 Chart 的运行时行为与资源创建权限	library 类型不创建资源，审计范围缩小

4.2 name 字段：身份标识与策略锚点

name 是 Chart 在集群中的唯一标识符。在权限边界层面，它直接关联到以下安全机制：

RBAC 资源命名前缀：许多组织使用 chart-{name} 作为 ServiceAccount、Role 和 RoleBinding 的命名模板。例如 chart-nginx-ingress 对应的 ServiceAccount 只能操作与 nginx-ingress 相关的资源。
OPA/Gatekeeper 策略匹配：准入控制器通过 metadata.labels.chart 标签（自动由 Helm 注入）识别 Chart 名称，从而应用差异化策略。例如禁止 name: untrusted-chart 部署到生产命名空间。
审计日志主体：Kubernetes 审计日志中的 user.username 字段会记录 helm:name:version 格式，便于追溯具体 Chart 的操作。

  安全实践： 将 name 纳入命名规范，避免使用通用名称（如 app、test），确保审计日志可明确区分不同 Chart 的行为。

4.3 version 字段：升级边界与回滚审计

version 遵循语义化版本 2.0 规范（MAJOR.MINOR.PATCH），其权限含义体现在：

升级策略约束：Helm 默认禁止跨 MAJOR 版本升级（除非使用 --force），这形成了一道天然的权限边界——未经显式授权，无法执行破坏性变更。
回滚权限控制：审计系统通过 helm history 记录的版本序列，可以精确识别谁在何时发起了回滚操作。回滚到旧版本可能绕过已生效的安全策略，因此需要额外审计关注。
版本锁定与依赖：子 Chart 的 version 约束（在 dependencies 中）决定了依赖解析的权限范围，避免意外引入恶意版本。

# 示例：version 字段的约束表达式
version: 2.1.3

# 依赖中的版本锁定
dependencies:
  - name: redis
    version: ">=16.0.0 < 17.0.0"  # 仅允许 16.x 版本

4.4 apiVersion 字段：引擎安全基线

apiVersion 只有两个合法值：v1（旧版）和 v2（当前标准）。从权限角度看，v2 引入了关键的安全增强：

特性	apiVersion: v1	apiVersion: v2
Chart 签名验证	不支持	强制支持（需配合 provenance 文件）
类型字段	不支持	支持 `type: library`
审计钩子	可选	预检钩子（pre-install/pre-upgrade）成为审计强制点
依赖管理	隐式	显式声明，依赖解析可审计

安全警告： 所有新 Chart 必须使用 apiVersion: v2。v1 Chart 无法提供签名验证和类型约束，在审计链路中属于“不可信来源”。

4.5 kubeVersion 字段：集群兼容性门禁

kubeVersion 使用语义化版本约束表达式（如 >=1.19.0-0 < 1.25.0-0），其权限含义是：

部署前准入检查：Helm 在 install 和 upgrade 时自动校验集群版本，不匹配则拒绝执行。这相当于一个前置权限门禁，防止 Chart 在不受支持的集群版本上运行。
API 资源可用性保障：不同 Kubernetes 版本可能废弃或移除 API 资源（如 extensions/v1beta1）。kubeVersion 约束确保 Chart 只使用当前集群支持的 API 版本，避免因资源不可用导致的权限错误。
审计事件触发：版本不匹配的部署尝试会生成 Failure 级别的审计事件，包含 Chart 名称、目标版本和集群版本，便于安全团队发现兼容性风险。

# kubeVersion 约束示例
kubeVersion: ">=1.21.0-0 < 1.28.0-0"

# 更严格的约束（仅允许 1.24.x）
kubeVersion: ">=1.24.0-0 < 1.25.0-0"

4.6 type 字段：资源创建权限的开关

type 字段是 Helm v2 引入的关键权限控制点，仅有两个合法值：

application（默认）：Chart 会创建 Kubernetes 资源（Deployment、Service、ConfigMap 等），需要完整的资源创建权限。
library：Chart 仅提供模板辅助函数和定义，不创建任何资源。这大幅缩小了权限边界——library Chart 只需要读取权限，无需写权限。

审计优化： 将公共模板封装为 type: library 的 Chart，可以显著减少审计日志中的资源创建事件，让安全团队聚焦于真正产生变更的 application Chart。

4.7 字段间的权限联动关系

下图展示了五个字段在 Helm 部署流程中的权限检查顺序与联动关系：

4.8 审计链路中的字段记录

在 Kubernetes 审计日志中，Chart.yaml 的元数据通过以下方式被记录：

{
  "kind": "Event",
  "apiVersion": "audit.k8s.io/v1",
  "level": "RequestResponse",
  "auditID": "xxxx-xxxx-xxxx",
  "stage": "ResponseComplete",
  "requestURI": "/apis/apps/v1/namespaces/default/deployments",
  "user": {
    "username": "helm:my-chart:2.1.3",  // name:version 格式
    "groups": ["system:serviceaccounts", "system:authenticated"]
  },
  "objectRef": {
    "resource": "deployments",
    "namespace": "default",
    "name": "my-chart-nginx"
  },
  "responseStatus": {
    "metadata": {},
    "code": 201
  },
  "annotations": {
    "helm.sh/chart": "my-chart-2.1.3",       // name-version
    "helm.sh/apiVersion": "v2",               // apiVersion
    "helm.sh/type": "application"             // type
  }
}

  审计关键点： 
  user.username 字段自动拼接 helm:{name}:{version}，是追溯 Chart 身份的核心依据。
annotations 中的 helm.sh/chart 和 helm.sh/type 可用于编写审计规则，例如过滤所有 type: library 的 Chart 事件。
kubeVersion 不直接出现在审计日志中，但版本不匹配的拒绝事件会记录在 responseStatus 的 message 字段中。

4.9 安全配置清单

基于以上分析，以下是 Chart.yaml 字段的安全配置建议：

字段	强制要求	推荐配置	审计规则
name	必须唯一	使用 `组织/项目/组件` 命名规范	监控非标准命名的 Chart 部署
version	必须符合 SemVer 2	禁止使用 `latest` 或 `dev` 等非版本号	记录所有版本变更和回滚操作
apiVersion	必须为 v2	CI/CD 流水线中校验 `apiVersion: v2`	拒绝所有 v1 Chart 的部署请求
kubeVersion	建议设置	精确到次版本号（如 `>=1.24.0 < 1.25.0`）	监控版本不匹配的失败事件
type	必须显式声明	纯模板库使用 `type: library`	审计 application 类型的资源创建

通过严格管理这五个字段，可以在 Helm Chart 接入集群的初始阶段就建立清晰的权限边界和可追溯的审计链路，为后续的运行时安全奠定基础。