📚 课程目录第4章声明式GitOps基础

4. 声明式GitOps基础：Application与AppProject资源定义、Sync策略（Manual/Auto）、Prune行为

在Argo CD的声明式GitOps模型中，Application和AppProject是两大核心自定义资源（CRD）。Application定义了“从哪个Git仓库同步到哪个目标集群/命名空间”，AppProject则提供多租户隔离与安全边界。理解它们的资源定义、同步策略（Sync Policy）以及Prune行为，是构建生产级GitOps工作流的基础。

4.1 Application资源定义

一个完整的Application YAML包含四个关键部分：Source（代码源）、Destination（目标集群）、Project（所属项目）和Sync Policy（同步策略）。以下是一个典型示例：

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/my-org/my-repo.git
    targetRevision: HEAD
    path: k8s-manifests
  destination:
    server: https://kubernetes.default.svc
    namespace: production
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true
      - PruneLast=true

  关键字段说明：
  spec.source：定义Git仓库地址、分支/标签（targetRevision）以及清单文件路径。
spec.destination：指定目标Kubernetes集群API Server地址和命名空间。
spec.project：将Application绑定到某个AppProject，默认为default。
spec.syncPolicy：控制同步行为，包括自动/手动、Prune开关、自愈等。

4.2 AppProject资源定义

AppProject用于对Application进行逻辑分组和权限控制。它定义了允许的源仓库、目标集群/命名空间、资源类型以及角色绑定。以下是一个生产级AppProject示例：

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: team-alpha
  namespace: argocd
spec:
  description: "Team Alpha Project"
  sourceRepos:
    - 'https://github.com/team-alpha/*'
  destinations:
    - namespace: 'team-*'
      server: https://kubernetes.default.svc
  clusterResourceWhitelist:
    - group: '*'
      kind: '*'
  namespaceResourceBlacklist:
    - group: 'rbac.authorization.k8s.io'
      kind: 'RoleBinding'
  roles:
    - name: admin
      description: "Admin privileges for Team Alpha"
      policies:
        - p, proj:team-alpha:admin, applications, *, team-alpha/*, allow
      groups:
        - team-alpha-admins

字段	作用	生产建议
`sourceRepos`	允许的Git仓库列表（支持通配符）	严格限制到具体组织或仓库，避免开放所有源
`destinations`	允许的目标集群和命名空间	使用命名空间前缀匹配，防止跨租户部署
`clusterResourceWhitelist`	允许创建的集群级别资源类型	按需开放，避免授予ClusterRole/ClusterRoleBinding
`namespaceResourceBlacklist`	禁止创建的命名空间级别资源类型	常用于禁止普通团队创建RBAC资源
`roles`	定义项目内的RBAC角色和权限策略	与外部OIDC/LDAP组绑定，实现细粒度权限

最佳实践：每个团队或业务线创建一个独立的AppProject，并在sourceRepos和destinations中使用通配符匹配，既保证灵活性又维持安全边界。

4.3 Sync策略：Manual vs Auto

Sync策略决定了Argo CD何时以及如何将Git仓库中的期望状态应用到目标集群。两种模式各有适用场景：

Manual（手动同步）：需要运维人员通过Argo CD UI、CLI或API手动触发同步。适用于变更审批严格、需要人工确认的生产环境。
Auto（自动同步）：Argo CD会定期检测Git仓库与集群状态差异，一旦发现偏离立即自动同步。适用于开发/测试环境或需要快速迭代的场景。

在syncPolicy.automated下，还可以配置以下子选项：

选项	默认值	说明
`prune`	false	是否自动删除集群中Git仓库已移除的资源
`selfHeal`	false	是否自动修复集群中被手动修改的资源（回滚到Git状态）
`allowEmpty`	false	是否允许同步空的Application（无资源）

安全警告：在生产环境中启用selfHeal: true时需谨慎，它会覆盖所有手动kubectl修改。建议结合prune: false先观察，确认无误后再开启Prune。

4.4 Prune行为详解

Prune（修剪）是Argo CD同步过程中最需要谨慎对待的行为。当Git仓库中删除了某个资源定义，而集群中仍然存在该资源时，Prune决定是否将其从集群中删除。

Prune行为受以下三个层级控制：

全局开关：syncPolicy.automated.prune（true/false）
同步选项：syncOptions中的PruneLast=true（先同步新增/更新，最后再Prune）
资源注解：在资源上添加argocd.argoproj.io/sync-options: Prune=false可跳过单个资源的Prune

Prune执行顺序（当PruneLast=true时）：

Argo CD先应用Git仓库中的新增和更新资源。
等待新资源就绪（如Deployment的Pod达到期望副本数）。
最后删除Git仓库中已移除的资源。

这种顺序可以避免因先删除旧资源导致服务中断，是生产环境的推荐配置。

4.5 生产环境配置建议

环境	Sync策略	Prune	SelfHeal	说明
开发/测试	Auto	true	true	快速迭代，自动清理废弃资源
预发布（Staging）	Auto	true	false	自动同步但允许临时手动调试
生产（核心服务）	Manual	false	false	严格审批，手动触发同步
生产（非核心服务）	Auto	true	true	配合PruneLast=true降低风险

关键提醒：无论使用哪种策略，建议在Application中始终配置syncOptions:下的CreateNamespace=true，确保目标命名空间不存在时自动创建，避免因命名空间缺失导致同步失败。