跳到主要内容

清单渲染与参数管理

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 校验或在生产控制面随意安装插件来“修复”渲染问题。