Kapitan配置管理：基于Jsonnet与Jinja2的多环境云原生配置实践

1. 项目概述：为什么我们需要Kapitan这样的配置管理工具？

在云原生和基础设施即代码（IaC）的时代，我们手里的配置文件正以前所未有的速度膨胀。Kubernetes的YAML清单、Terraform的HCL文件、Helm的Chart、Ansible的Playbook，还有各种环境变量和密钥。你有没有经历过这样的场景：为了部署一个应用到测试环境，你需要手动修改十几个文件里的镜像标签、数据库地址和资源限制，稍有不慎，生产环境的配置就被错误地覆盖了。传统的配置管理工具，比如Helm，虽然通过模板化解决了一部分问题，但当你的部署目标横跨多个云平台（AWS, GCP, Azure），同时管理Kubernetes、虚拟机和无服务器资源时，Helm模板的复杂性会急剧上升，if-else语句嵌套得让人头晕，更别提密钥管理和多环境差异化配置带来的挑战了。

这就是Kapitan诞生的背景。它不是一个要取代Helm或Kubernetes的工具，而是一个站在它们之上的“胶水”和“编译器”。你可以把它想象成一个超级配置工厂：你把所有零散的、针对不同工具（K8s, Terraform, Dockerfile等）的配置，用一种更高级、更声明式的方式描述出来，然后告诉Kapitan：“我要部署到AWS的staging环境。” Kapitan就会帮你把这份高级描述，“编译”成最终可被kubectl apply或terraform apply直接使用的、正确的、抹平了所有差异的具体配置文件。它核心解决的是配置的复用、组合与安全分发问题，尤其是当你的配置需要根据环境、云提供商、团队等维度产生数十上百种变体时，Kapitan的价值就凸显出来了。

我第一次接触Kapitan是在一个微服务数量超过50个的项目中，每个服务都有开发、测试、预发、生产四套环境，并且部署在AWS和GCP两个云上。当时我们被Helm Chart里大量的{{ if eq .Values.cloud “aws” }}逻辑搞得苦不堪言，密钥也是硬编码在values.yaml里，审计和轮换成了噩梦。Kapitan通过引入Jsonnet和Jinja2作为模板引擎，以及内置的密钥管理机制，让我们能够将配置逻辑（比如“所有生产环境数据库用高可用模式”）与具体值（比如数据库的实际连接字符串）清晰地分离，最终将部署配置的维护成本降低了至少60%。

2. 核心设计哲学：声明式、可组合与“一次编写，多处生成”

Kapitan的设计哲学深深植根于现代DevOps实践，尤其是GitOps。它强调以下几点，理解了这些，你才能用好它：

2.1 真正的声明式配置

很多工具都宣称自己是“声明式”，但往往只是在执行层面。Kapitan将声明式推向了配置的定义阶段。你不再需要编写命令式的脚本去“生成”配置，而是声明你想要的最终状态。例如，你声明：“我需要一个在us-east-1区域的、带有自动扩缩容的Kubernetes Deployment。” Kapitan的模板和编译过程会负责计算出实现这个声明所需的所有具体YAML或JSON文件。这种范式转变，使得配置本身就像代码一样，易于推理、审查和版本控制。

2.2 可组合性与模块化

这是Kapitan最强大的特性之一。它允许你将配置分解成可重用的组件或模块。想象一下乐高积木：

• 基础积木（Classes）： 定义通用的、与环境无关的配置。比如，一个“Web服务”的类，里面定义了通用的健康检查探针、资源请求限制、服务发现标签等。
• 环境积木（Targets）： 定义特定环境（如prod-aws）的参数。比如，在这个目标里，你指定replicas: 10，domain: prod.example.com，并引用AWS特定的KMS密钥来加密敏感数据。
• 胶水（Kapitan编译）： Kapitan在编译时，会将“Web服务”类与prod-aws目标的参数组合起来，并注入具体的、加密后的密钥，生成最终的Kubernetes Manifest。

这种方式实现了配置的“DRY”（Don‘t Repeat Yourself）原则。当你需要调整所有服务的资源限制时，只需修改“Web服务”这个基础类，所有引用它的目标在重新编译后都会自动更新。

2.3 多格式输出与统一入口

Kapitan不绑定任何特定的运行时工具。它的输入是你用Jsonnet（推荐）或Jinja2编写的模板，以及YAML/JSON格式的参数文件。而它的输出可以是任何文本格式：

• Kubernetes YAML
• Terraform HCL / JSON
• Dockerfile
• Ansible Playbooks
• 甚至是一份Markdown格式的部署文档

这意味着，你可以用一个Kapitan项目仓库，统一管理整个技术栈的配置，而不是在k8s-manifests/、terraform/、ansible/等多个目录间跳转和手动同步配置值。编译命令kapitan compile就是你的单一入口。

3. 深入核心：Jsonnet与Jinja2模板引擎的抉择

Kapitan支持两种主流的模板引擎：Jsonnet和Jinja2。选择哪一个，取决于你的团队背景和配置复杂度。

3.1 Jsonnet：为结构化配置而生的语言

Jsonnet是Google开发的一种数据模板语言，它本身就是JSON的超集。如果你熟悉JSON，那么上手Jsonnet会非常快。它的核心优势在于强大的数据组合与函数式编程能力。

为什么推荐Jsonnet作为首选？

1. 类型安全与结构化： Jsonnet强制输出是良构的JSON（或YAML，本质相同）。这能在编译阶段就捕获许多配置错误，比如字段名拼写错误、类型不匹配（误将字符串当数字用）。而Jinja2输出的是纯文本，直到kubectl apply时你才可能发现YAML语法错误。
2. 函数与继承： Jsonnet支持定义函数和对象继承。你可以创建一个返回Deployment对象的函数createDeployment(name, image)，然后在各处调用。你也可以通过+操作符轻松地合并和覆盖对象，这是实现配置组合（Composition）和覆盖（Override）的利器。
3. 标准库： Jsonnet自带标准库（std），提供了大量用于字符串、数组、对象操作的函数，甚至包括MD5、Base64编码等，非常方便。

一个简单的Jsonnet示例 (components/nginx.jsonnet):

local kube = import “lib/kube.libjsonnet”; // 导入一个自定义的Kubernetes函数库 { nginx_deployment: kube.Deployment(‘nginx’, ‘nginx:1.21’) { spec+: { replicas: 3, template+: { spec+: { containers+: [{ name: ‘nginx’, ports: [{ containerPort: 80 }], }], }, }, }, }, nginx_service: kube.Service(‘nginx’) { spec+: { ports: [{ port: 80, targetPort: 80 }], }, }, }

这个例子展示了导入库、函数调用（kube.Deployment）和对象覆盖（+操作符）的用法，逻辑非常清晰。

3.2 Jinja2：来自Python世界的灵活模板

Jinja2是Python生态中广泛使用的模板引擎，以其灵活性和强大的控制流（循环、条件判断）著称。如果你团队对Python更熟悉，或者已有大量Jinja2格式的配置（比如从Ansible迁移过来），那么选择Jinja2会更顺手。

Jinja2的适用场景与注意事项：

1. 灵活性高： 可以生成任何格式的文本文件，不限于JSON/YAML。适合生成配置文件、脚本等。
2. 学习曲线平缓： 对于Python开发者，其语法非常直观。
3. 主要缺点： 如前所述，它不保证输出结构的有效性。一个缺失的引号或错误的缩进就会导致最终文件解析失败。因此，在使用Jinja2时，必须辅以严格的YAML/JSON语法检查（如yamllint,jsonlint），最好将其作为CI/CD流水线的一环。

选择建议：

• 新项目，强推Jsonnet。它的结构化特性带来的长期维护收益远大于初期的学习成本。
• 已有大量Jinja2资产或团队Python背景深厚，可以继续使用Jinja2，但务必建立强化的代码检查和验证流程。
• 混合使用： Kapitan允许你在同一个项目中混合使用两者，但这会增加复杂性，一般不建议。

4. 实战演练：从零构建一个Kapitan项目管理多环境K8s应用

让我们通过一个完整的例子，看看如何用Kapitan管理一个简单的Nginx应用在开发（dev）和生产（prod）环境的部署。我们将使用Jsonnet作为模板语言。

4.1 项目初始化与结构规划

首先，安装Kapitan。按照官方推荐，使用Docker方式可以避免本地Python环境冲突：

# 拉取最新镜像并运行帮助命令，测试安装 docker run -t --rm -v $(pwd):/src:delegated kapicorp/kapitan -h

创建一个新的项目目录并初始化结构：

mkdir my-kapitan-project && cd my-kapitan-project mkdir -p components targets inventory/classes

一个典型的Kapitan项目结构如下：

my-kapitan-project/ ├── inventory/ # 核心：库存目录，存放所有配置定义 │ ├── classes/ # 通用配置类（Classes） │ └── targets/ # 具体环境目标（Targets） ├── components/ # 可复用的组件模板（Jsonnet/Jinja2） ├── lib/ # Jsonnet库文件 ├── vendor/ # 第三方Jsonnet库（如kube.libsonnet） ├── compiled/ # （编译后自动生成）最终输出文件 └── kapitan.yml # （可选）项目级配置

4.2 定义通用配置类（Classes）

类（Class）是配置的抽象层。我们创建两个类：

1. common.yml： 所有环境都通用的配置。
2. environment目录下的类： 定义环境类型（开发/生产）的通用行为。

inventory/classes/common.yml

parameters: kapitan: vars: target_name: ${target_name} # Kapitan内置变量，当前目标名 kube: namespace: default common_labels: app: ${target_name} managed-by: kapitan

这个类定义了Kubernetes的命名空间和一个通用的标签。

inventory/classes/environment/dev.yml

classes: - common parameters: kube: environment: development replicas: 1 # 开发环境只运行1个副本 resources: requests: cpu: “10m” memory: “32Mi” limits: cpu: “100m” memory: “128Mi”

inventory/classes/environment/prod.yml

classes: - common parameters: kube: environment: production replicas: 3 # 生产环境3个副本确保高可用 resources: requests: cpu: “100m” memory: “128Mi” limits: cpu: “500m” memory: “512Mi” kapitan: secrets: # 假设生产环境使用AWS KMS加密密钥 gpg_recipients: # 或者使用GPG - ? gpg:kms-gpg-public-key

注意classes:字段，它表示继承。dev.yml和prod.yml都继承了common.yml的所有参数。这是Kapitan实现配置组合的核心机制。

4.3 创建具体目标（Targets）

目标是编译的单元，它组合类并为其提供具体的参数值。

inventory/targets/dev-nginx.yml

classes: - environment.dev # 继承开发环境类 - component.nginx # 引用名为“nginx”的组件（我们稍后创建） parameters: target_name: dev-nginx # 覆盖或设置参数 kube: namespace: dev # 覆盖common中的namespace image: nginx:1.21-alpine # 指定镜像 service_port: 8080 # 开发环境映射到8080端口

inventory/targets/prod-nginx.yml

classes: - environment.prod - component.nginx parameters: target_name: prod-nginx kube: namespace: prod image: nginx:1.21 # 生产环境使用标准镜像 service_port: 80 # 假设生产环境有特定的域名和密钥 domain: nginx.prod.example.com secret_env: API_KEY: ?{gkms:prod-api-key} # 引用一个加密的密钥

这里出现了?{gkms:prod-api-key}，这是Kapitan的秘密引用语法。它表示这个值不是明文，而是一个需要通过GPG或KMS解密的秘密标识符。我们会在密钥管理部分详细讲解。

4.4 编写可复用组件（Component）

组件是使用模板语言（这里用Jsonnet）编写的、生成最终配置文件的逻辑。

components/nginx.jsonnet

// 局部变量，从Kapitan传入的参数中提取所需值 local target = std.extVar(“target“); // `target` 变量包含了当前目标的所有参数 local params = target.parameters; local kube = params.kube; // 定义一个生成Deployment的本地函数 local deployment(name, image) = { apiVersion: “apps/v1“, kind: “Deployment“, metadata: { name: name, namespace: kube.namespace, labels: kube.common_labels, }, spec: { replicas: kube.replicas, selector: { matchLabels: kube.common_labels, }, template: { metadata: { labels: kube.common_labels, }, spec: { containers: [{ name: “app“, image: image, ports: [{ containerPort: 80 }], resources: kube.resources, env: kube.secret_env { // 这里会展开加密的secret_env if std.objectHas(kube, “secret_env“) then std.map( function(key) { { name: key, value: std.md5(std.toString(kube.secret_env[key])) } }, // 解密后处理，此处用md5模拟 std.objectFields(kube.secret_env) ) else [] }, }], }, }, }, }; // 定义一个生成Service的本地函数 local service(name, port) = { apiVersion: “v1“, kind: “Service“, metadata: { name: name, namespace: kube.namespace, }, spec: { selector: kube.common_labels, ports: [{ port: port, targetPort: 80 }], type: “ClusterIP“, }, }; // 输出对象，Kapitan会将其渲染为YAML文件 { “deployment.yml“: std.manifestYamlDoc(deployment(params.target_name, kube.image)), “service.yml“: std.manifestYamlDoc(service(params.target_name, kube.service_port)), // 可以根据条件生成更多文件，例如只有生产环境生成Ingress if std.objectHas(kube, “domain“) then “ingress.yml“: std.manifestYamlDoc({ apiVersion: “networking.k8s.io/v1“, kind: “Ingress“, metadata: { name: params.target_name, namespace: kube.namespace, annotations: { “kubernetes.io/ingress.class“: “nginx“, }, }, spec: { rules: [{ host: kube.domain, http: { paths: [{ path: “/“, pathType: “Prefix“, backend: { service: { name: params.target_name, port: { number: kube.service_port }, }, }, }], }, }], }, }) else {} }

这个组件做了几件事：

1. 通过std.extVar(“target“)获取Kapitan传入的当前目标的所有参数。
2. 定义了两个本地函数来生成Kubernetes对象。
3. 使用std.manifestYamlDoc将Jsonnet对象转换为YAML字符串。
4. 输出一个字典，键是文件名，值是文件内容。Kapitan会根据这个字典生成对应的物理文件。
5. 使用了条件判断：只有参数中存在domain字段时，才生成ingress.yml文件。这样，开发目标就不会有不必要的Ingress配置。

4.5 编译与输出

现在，我们可以编译特定的目标了：

# 使用Docker运行，将当前目录挂载到容器的 /src docker run -t --rm -v $(pwd):/src:delegated kapicorp/kapitan compile -t dev-nginx

编译后，查看compiled/目录：

compiled/ └── dev-nginx/ ├── deployment.yml └── service.yml

打开deployment.yml，你会看到一份完整的、参数已填充的Kubernetes Deployment YAML，其中replicas: 1，资源限制也是开发环境的配置。

编译生产目标：

docker run -t --rm -v $(pwd):/src:delegated kapicorp/kapitan compile -t prod-nginx

查看compiled/prod-nginx/，你会发现除了deployment.yml和service.yml，还多了一个ingress.yml文件，因为我们在参数中定义了domain。并且deployment.yml中的replicas是3，资源限制也更高。

关键技巧： 使用kapitan compile --fetch可以自动下载项目中引用的远程Jsonnet库（如kube.libsonnet）到vendor/目录。对于团队协作，建议将vendor/目录加入.gitignore，而在CI/CD流水线中使用--fetch参数来保证依赖一致。

5. 密钥管理实战：如何安全地处理敏感配置？

将数据库密码、API令牌、TLS私钥等秘密信息明文存放在Git仓库中是严重的安全隐患。Kapitan内置了强大的秘密管理功能，支持多种后端，其核心思想是：只将加密后的密文存入Git，解密密钥由运维人员在部署时提供。

5.1 支持的秘密后端

1. GPG (GNU Privacy Guard)： 使用非对称加密。每个可解密的目标配置一组GPG公钥的接收者（Recipients）。编译时用公钥加密，部署时需持有对应私钥的人解密。适合小团队或个人项目。
2. AWS KMS / GCP KMS： 使用云服务商提供的密钥管理服务。通过IAM策略控制解密权限，与云上其他服务（如Lambda, ECS）集成性好，适合云原生环境。
3. Vault： 通过Kapitan的Vault后端集成HashiCorp Vault，可以从Vault的动态秘密引擎中拉取秘密。

5.2 使用GPG管理秘密：一步步来

假设我们要为生产环境的Nginx添加一个API_KEY环境变量。

第一步：在目标文件中引用秘密修改inventory/targets/prod-nginx.yml：

parameters: ... kube: secret_env: API_KEY: ?{gpg:prod-api-key|randomstr|40} # 语法：?{后端:秘密标识符|生成类型|长度}

randomstr|40指示Kapitan在首次编译时，生成一个40字符的随机字符串作为秘密值，并用GPG加密。

第二步：首次编译并生成秘密

# 编译时，Kapitan发现`prod-api-key`不存在，会交互式地提示你输入值。 # 但我们用了`randomstr`，它会自动生成。 docker run -t --rm -v $(pwd):/src:delegated kapicorp/kapitan compile -t prod-nginx

编译后，查看inventory/targets/prod-nginx.yml，你会发现那一行变成了：

API_KEY: ?{gpg:prod-api-key|randomstr|40:567gfd...（很长一串密文）}

Kapitan自动用GPG公钥加密了生成的随机字符串，并将密文写回了目标文件。现在，这个密文可以被安全地提交到Git仓库。

第三步：配置GPG公钥Kapitan需要知道用谁的公钥加密。这通常在inventory/classes中配置。创建一个secrets/gpg.yml类：

parameters: kapitan: secrets: gpg_recipients: - alice@example.com # 你的GPG密钥ID或邮箱 - bob@example.com # 可以添加多个接收者，任何一人均可解密

然后让environment.prod类继承它：

# inventory/classes/environment/prod.yml classes: - common - secrets.gpg # 继承GPG配置类 parameters: ...

第四步：解密与使用在部署的机器上（如CI/CD Runner），需要导入包含私钥的GPG密钥环。然后，使用kapitan解密：

# 此命令会解密所有引用，并输出明文文件到 `compiled/` 目录 docker run -t --rm -v $(pwd):/src:delegated -v ~/.gnupg:/root/.gnupg kapicorp/kapitan compile -t prod-nginx

-v ~/.gnupg:/root/.gnupg将宿主机的GPG密钥环挂载到容器内。Kapitan会自动解密prod-api-key，并在编译出的deployment.yml中，将API_KEY的环境变量值设置为解密后的明文。

重要安全实践：

1. 永远不要提交私钥。私钥应通过安全渠道（如硬件令牌、密码管理器）分发给可信人员。
2. 在CI/CD中解密： CI/CD流水线应配置受信任的Runner，并注入解密所需的私钥（如从Vault获取，或使用CI系统的秘密变量功能临时导入GPG私钥）。编译和解密步骤应在CI中完成，产出的明文配置直接用于部署（如kubectl apply -f compiled/prod-nginx/），之后立即清理。
3. 密钥轮换： 定期轮换加密密钥（GPG主密钥或KMS密钥）。Kapitan支持重新加密（kapitan reclass），可以方便地用新的公钥重新加密所有现有秘密。

5.3 使用AWS KMS（推荐用于AWS环境）

使用AWS KMS更符合云原生安全模型。首先，你需要在AWS中创建一个KMS密钥（Customer Master Key, CMK），并授予部署角色（如CI/CD角色的ARN）解密权限。

配置目标使用KMS：

# inventory/targets/prod-nginx.yml parameters: kapitan: secrets: aws_kms_arn: arn:aws:kms:us-east-1:123456789012:key/your-key-id kube: secret_env: API_KEY: ?{aws:kms:prod-api-key|randomstr|40}

编译时，Kapitan会使用指定的KMS ARN进行加密。解密时，运行Kapitan的环境（如EC2实例、GitHub Actions Runner）需要配置具有kms:Decrypt权限的IAM角色或密钥，Kapitan会自动调用AWS SDK进行解密。

6. 高级特性与集成：让Kapitan融入你的工作流

6.1 依赖管理与远程导入（Jsonnet）

对于复杂的配置，你可能会依赖一些优秀的开源Jsonnet库，比如kube.libsonnet（一个用于生成Kubernetes资源的强大库）。Kapitan通过jsonnet的import语句和--fetch参数来管理这些依赖。

1. 在项目根目录创建jsonnetfile.json（类似于Python的requirements.txt）：

   { “dependencies“: [ { “source“: { “git“: { “remote“: “https://github.com/bitnami-labs/kube-libsonnet“, “subdir“: “kube.libsonnet“ } }, “version“: “master“ } ] }

2. 在组件中导入使用：

   local kube = import “kube.libsonnet“; // 现在可以使用 kube.v1.apps.deployment.new(...) 等高级函数

3. 编译时使用--fetch参数自动下载依赖到vendor/目录：

   kapitan compile --fetch -t prod-nginx

6.2 与GitOps工具（如Argo CD, Flux）集成

Kapitan与GitOps是天作之合。典型的流程是：

1. 配置即代码： 你的Kapitan项目仓库就是“单一可信源”。
2. CI流程： 当代码合并到主分支后，CI流水线触发kapitan compile，对所有目标进行编译和解密（使用注入的密钥）。
3. 输出到Git： CI将编译出的明文配置（compiled/目录）推送到另一个专门的“配置发布仓库”（例如gitops-deployments）。注意：这一步需要仔细评估安全风险，确保推送到的仓库访问权限严格控制。更安全的做法是CI只推送密文，由部署环境（如Argo CD所在集群）在拉取后解密。
4. GitOps同步： Argo CD或Flux监控这个“配置发布仓库”，一旦有新的配置推送，就自动同步到Kubernetes集群。

你也可以配置Argo CD直接使用Kapitan仓库，并利用其Config Management Plugin功能，在Argo CD内部调用kapitan compile。这样就不需要中间的配置发布仓库了，但需要在Argo CD的Repo Server中安装Kapitan并管理解密密钥。

6.3 校验与验证（Validation）

在编译后、部署前进行校验至关重要。Kapitan支持通过--validate参数调用外部验证工具。

1. Kubernetes资源验证： 使用kubeval或kubeconform。

   kapitan compile -t prod-nginx --validate “kubeconform -summary compiled/prod-nginx/*.yml“

2. Terraform验证： 如果输出Terraform文件，可以使用terraform validate。

   kapitan compile -t prod-infra --validate “cd compiled/prod-infra && terraform init -backend=false && terraform validate“

将这些验证命令集成到CI流水线中，可以及早发现配置错误。

7. 避坑指南与性能优化：来自实战的经验

在大型项目中用了Kapitan几年，我们踩过不少坑，也总结出一些最佳实践。

7.1 常见问题与排查

问题1：编译错误RUNTIME ERROR: undefined external variable

• 原因： 在Jsonnet中使用了未定义的std.extVar。最常见的是拼写错误，比如std.extVar(“targeet“)。
• 解决： 仔细检查Jsonnet文件中std.extVar的参数名。Kapitan只自动注入一个名为“target“的变量。确保你在目标文件中定义的参数路径能被正确访问。使用kapitan inventory -t <target_name>命令可以查看Kapitan为某个目标构建的完整参数树，这是调试的利器。

问题2：生成的YAML格式错误或包含“null“值

• 原因： Jsonnet中未设置的字段在转换成YAML时会变成null。某些Kubernetes工具（尤其是旧版本）无法处理null值。
• 解决： 在输出YAML前，使用std.manifestYamlDoc函数，并设置strip_namespace等选项，或者使用std.prune函数递归删除所有null值。例如：

  { “deployment.yml“: std.manifestYamlDoc(std.prune(myDeploymentObject)) }

问题3：秘密引用未解密，输出仍是?{...}格式

• 原因：
  1. 解密所需的密钥（GPG私钥或KMS权限）在当前环境不可用。
  2. 目标文件中kapitan.secrets部分的配置（如gpg_recipients）不正确或未被继承。
• 解决：
  1. 运行kapitan secrets --reveal -t <target_name>可以尝试解密并显示明文，用于测试密钥配置。
  2. 确认GPG密钥环已正确挂载或AWS CLI已配置好具有解密权限的凭证。
  3. 使用kapitan inventory -t <target_name>检查kapitan.secrets参数是否被正确合并。

问题4：编译速度慢，尤其是项目庞大时

• 原因： Jsonnet是解释型语言，复杂的模板和大量的远程导入（import）会拖慢编译速度。
• 优化：
  1. 使用--cache参数： Kapitan支持编译缓存。首次编译后，再次编译没有改动的目标会极快。

  kapitan compile --cache -t prod-nginx

  2. 并行编译： 使用-p或--parallel参数指定并行数。

  kapitan compile --cache --parallel=4

  3. 优化Jsonnet： 避免在循环内进行昂贵的操作（如网络请求模拟）。将常用函数或对象定义为局部变量（local）。
  4. 预下载依赖： 在CI镜像中预置vendor/目录，避免每次编译都执行--fetch。

7.2 项目结构演进建议

• 初期（小项目）： 按上述例子，inventory/classes/按逻辑分类（common,environment,component），targets/按应用和环境命名。
• 中期（多团队/多产品）： 考虑按产品线或团队划分目录。

  inventory/ ├── classes/ │ ├── team-a/ # A团队的通用类 │ ├── team-b/ # B团队的通用类 │ └── global/ # 全局类（如公司级安全策略） └── targets/ ├── team-a/ │ ├── app1-dev.yml │ └── app1-prod.yml └── team-b/ ├── serviceX-dev.yml └── serviceX-prod.yml

  使用类的继承链来组合配置，例如targets/team-a/app1-prod.yml的类可能是：[global.security, team-a.base, environment.prod, component.app1]。
• 后期（超大规模）： 可能需要将部分配置外部化，例如将动态的、经常变化的部分（如特性开关）存储在专门的配置服务（如etcd, Consul）中，Kapitan通过其remote_classes功能或自定义Jsonnet函数在编译时拉取。

7.3 版本控制与协作

1. .gitignore配置：

   # Kapitan compiled/ .kapitan_cache/ # 如果使用 --fetch，通常忽略 vendor/，在CI中生成 vendor/ # 秘密文件备份（如果有） *.secret.yml

2. 代码审查： 重点审查inventory/classes/下的通用类修改，因为其影响范围广。审查targets/中的参数覆盖是否合理。
3. 变更日志： 由于Kapitan项目是纯文本配置，可以很好地利用Git的提交历史作为变更日志。鼓励小颗粒度、描述清晰的提交信息。

从Helm的“模板地狱”中走出来，拥抱Kapitan的声明式组合，一开始可能会觉得有些抽象，但一旦你习惯了这种“定义what，而非描述how”的思维方式，并且体验过在多环境、多云场景下那份“一键编译，处处一致”的从容，你就会明白它在管理复杂配置方面的巨大威力。它不是一个银弹，但绝对是你在云原生配置管理武器库中一件值得深入打磨的利器。