清单渲染与参数管理
Argo CD 在同步前先渲染清单。渲染结果必须可复现：同一 Git revision、同一 Chart 版本与同一参数应生成同样的 Kubernetes 对象。不要在 Argo CD UI 中临时覆盖生产参数而不回写 Git。
1. 选择渲染方式
| 方式 | 适用场景 | 管理重点 |
|---|---|---|
| 原生 YAML | 资源少、结构稳定 | 目录隔离、重复配置控制 |
| Kustomize | 多环境 overlay、镜像与标签替换 | base 与 overlay 的边界 |
| Helm | 第三方 Chart、参数化服务 | 固定 Chart 版本、values 审阅 |
| 多源 Application | 应用 Chart 与独立 values 仓库 | 源之间的版本一致性 |
2. 原生 YAML 与 Kustomize
推荐将环境差异显式放在 overlay，而不是复制整套清单。以下目录让生产环境只覆盖镜像和副本数：
apps/user-center/
├── base/
│ ├── deployment.yaml
│ ├── service.yaml
│ └── kustomization.yaml
└── overlays/
└── prod/
├── kustomization.yaml
└── patch-deployment.yaml
# apps/user-center/overlays/prod/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- ../../base
images:
- name: registry.example.com/platform/user-center
newTag: 1.2.0
patches:
- path: patch-deployment.yaml
Application 的 source.path 应精确指向 overlays/prod。CI 更新镜像时提交 newTag 的 PR，发布记录即可关联到 Git commit。
3. Helm Application
对 Helm Chart 固定版本，避免 targetRevision: HEAD 或不受控的最新 Chart。参数优先放在 Git 中的 values 文件而非 UI 覆盖。
spec:
source:
repoURL: https://charts.example.com/stable
chart: example-service
targetRevision: 2.4.1
helm:
valueFiles:
- $values/apps/example-service/prod-values.yaml
Helm values 中的 Secret 仍应由 External Secrets、Sealed Secrets 或受控加密流程管理。将明文 Token、数据库密码写进 values 仓库会扩大泄露面。
4. 多源 Application
当 Chart 与环境 values 分属不同仓库时可使用 sources。每个 source 都应固定 revision，并明确 ref，避免变量引用不清晰。
spec:
sources:
- repoURL: https://charts.example.com/stable
chart: example-service
targetRevision: 2.4.1
helm:
valueFiles:
- $values/apps/example-service/prod-values.yaml
- repoURL: https://git.example.com/platform/environment-config.git
targetRevision: main
ref: values
多源适合共享 Chart 与集中环境配置，不适合把多个无关应用塞进一个 Application。源仓库可访问权限必须同时受到 AppProject 的 sourceRepos 限制。
5. 发布前渲染检查
# 查看 Argo CD 实际渲染出的对象，排查 values 或 Kustomize 引用问题
argocd app manifests user-center-prod
# 刷新仓库缓存后比较差异，不直接写入集群
argocd app diff user-center-prod --refresh
渲染失败先检查 Repo Server 日志、Git revision、插件版本和仓库凭据。不要通过关闭 TLS 校验或在生产控制面随意安装插件来“修复”渲染问题。