3. Argo CD核心对象与声明式管理

Argo CD 的“声明式”并不是一句口号，而是由一组 Kubernetes CRD（Custom Resource Definition）承载的。理解这些 CRD 的字段语义与相互引用关系，是后续做多环境交付、权限隔离和自动化同步的基础。本节围绕四个最核心的对象展开：Application、AppProject、Repository、Cluster，并给出可直接参考的 YAML 声明实践。

一、四个核心 CRD 的职责边界

先建立整体认知：Application 描述“把哪个 Git 仓库的哪个路径、以什么参数，部署到哪个集群的哪个命名空间”；AppProject 是 Application 的“权限与边界容器”，限制它能访问哪些仓库、哪些集群、哪些命名空间；Repository 把 Git 仓库的连接信息（URL、认证方式）注册为集群内可复用对象；Cluster 把目标集群的 API Server 地址与凭据注册进来。四者的引用关系是：Application 引用 AppProject，AppProject 引用 Repository 与 Cluster 的许可范围。

二、Application：交付意图的完整描述

Application 是日常接触最多的对象。它的 spec.source 指向 Git 仓库与路径，spec.destination 指向目标集群与命名空间，spec.syncPolicy 决定是否自动同步。下面是一个部署到集群内 dev 命名空间的示例：

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: guestbook-dev
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://git.example.com/platform/guestbook.git
    targetRevision: HEAD
    path: overlays/dev
  destination:
    server: https://kubernetes.default.svc
    namespace: dev
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

几个关键点：targetRevision 可以是分支、Tag 或提交 SHA，生产环境建议固定 Tag 或 SHA 以保证可追溯；prune: true 表示 Git 中删除的资源会在集群中被清理；selfHeal: true 表示集群内被手工修改的资源会被自动纠正回 Git 声明状态；CreateNamespace=true 允许目标命名空间不存在时自动创建。

三、AppProject：把权限收进边界

默认的 default 项目几乎不设限，生产环境应显式创建 AppProject。它通过 sourceRepos 限定可拉取的仓库，通过 destinations 限定可部署的集群与命名空间，通过 roles 定义团队的操作权限。

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: team-payment
  namespace: argocd
spec:
  sourceRepos:
    - https://git.example.com/platform/payment.git
  destinations:
    - namespace: payment-*
      server: https://kubernetes.default.svc
  clusterResourceWhitelist:
    - group: ''
      kind: Namespace
  roles:
    - name: developer
      policies:
        - p, proj:team-payment:developer, applications, sync, team-payment/*, allow
      groups:
        - payment-devs

这里 namespace: payment-* 使用通配符，允许部署到以 payment- 开头的命名空间；clusterResourceWhitelist 控制是否允许创建集群级资源，默认应尽量收紧。角色策略中的 p, proj:team-payment:developer, applications, sync, team-payment/*, allow 表示该角色只能同步本项目下的 Application。

四、Repository 与 Cluster：连接信息的注册

Repository 把 Git 连接信息注册为集群内对象，避免在每个 Application 中重复填写凭据。声明式写法如下：

apiVersion: v1
kind: Secret
metadata:
  name: repo-payment
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: git
  url: https://git.example.com/platform/payment.git
  username: gitops-bot
  password: <token>

注意它本质是一个带特定 Label 的 Secret，而非独立 CRD。Cluster 同理，通过 Secret 注册外部集群：

apiVersion: v1
kind: Secret
metadata:
  name: cluster-prod
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: cluster
stringData:
  name: prod-cluster
  server: https://api.prod.example.com:6443
  config: |
    {
      "bearerToken": "<token>",
      "tlsClientConfig": { "insecure": false, "caData": "<base64-ca>" }
    }

五、声明式管理的落地顺序

实际落地时，推荐按“先注册连接、再划定边界、最后声明应用”的顺序组织 YAML：先创建 Repository 与 Cluster Secret，再创建 AppProject，最后创建 Application。这样 Application 在创建时其引用的项目与仓库均已存在，避免因引用缺失导致同步失败。所有对象都应纳入 Git 仓库，由 Argo CD 自身或上层流水线以 App of Apps 模式统一管理，从而实现“Git 是唯一事实来源”的闭环。

掌握这四个对象的字段语义与引用关系后，后续的多环境差异化、同步策略调优和权限治理都将建立在这一层声明式基础之上。