3、Argo CD 核心概念：Application、Project、Sync Policy、Sync Status、Health Status

Argo CD 围绕一套清晰的核心概念构建，理解这些概念是掌握其持续部署能力的基础。本章将逐一剖析 Application、Project、Sync Policy、Sync Status 和 Health Status，并阐明它们之间的协作关系。

3.1 核心概念总览

下表概括了五个核心概念的定义与职责，便于快速建立整体认知：

概念 定义 核心职责
Application Argo CD 中的基本部署单元，描述一个应用从 Git 仓库到目标集群的完整映射。 定义源（Git 仓库路径）、目标（集群 + 命名空间）、同步策略与状态管理。
Project 逻辑分组与隔离边界，用于管理多个 Application 的访问权限和资源约束。 提供 RBAC 控制、允许的源仓库、目标集群和资源白名单。
Sync Policy 定义 Argo CD 如何将 Git 仓库中的期望状态同步到目标集群的规则。 控制自动/手动同步、自愈、修剪资源、同步窗口等行为。
Sync Status 表示 Application 的当前实时状态与 Git 仓库中期望状态之间的一致性程度。 指示是否同步、存在差异或同步失败。
Health Status 表示 Application 中部署资源的运行健康度，反映应用是否正常工作。 评估 Pod、Service、Deployment 等资源的运行状态。

3.2 Application：部署的原子单元

Application 是 Argo CD 中最核心的资源对象。它定义了以下关键信息：

  • 源（Source）：Git 仓库 URL、目标路径、Helm Chart 或 Kustomize 配置。
  • 目标（Destination）：目标 Kubernetes 集群的 API Server URL 和命名空间。
  • 同步策略（Sync Policy）：自动或手动同步，以及自愈、修剪等选项。
  • 项目（Project）：所属的项目名称，默认为 default。

一个典型的 Application YAML 定义如下：

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: guestbook
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/argoproj/argocd-example-apps.git
    targetRevision: HEAD
    path: guestbook
  destination:
    server: https://kubernetes.default.svc
    namespace: guestbook
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true
实践提示： 建议始终为 Application 显式指定 project 字段，避免使用默认项目导致权限管理混乱。同时，开启 selfHeal: true 可以自动修复集群内的配置漂移。

3.3 Project：多租户隔离与安全边界

Project 提供了逻辑分组和访问控制能力。每个 Application 必须属于一个 Project。Project 可以限制：

  • 允许的源仓库：只允许从指定的 Git 仓库拉取清单。
  • 允许的目标集群：限制可以部署到哪些集群。
  • 允许的目标命名空间：限制可以部署到哪些命名空间。
  • 资源白名单/黑名单：控制可以创建哪些 Kubernetes 资源类型。
  • 角色绑定：通过 RBAC 控制用户对 Project 内 Application 的操作权限。

以下是一个 Project 配置示例：

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: production
  namespace: argocd
spec:
  sourceRepos:
    - 'https://github.com/company/production-apps.git'
  destinations:
    - namespace: 'production-*'
      server: 'https://kubernetes.default.svc'
  clusterResourceWhitelist:
    - group: ''
      kind: 'Namespace'
  namespaceResourceBlacklist:
    - group: 'rbac.authorization.k8s.io'
      kind: 'RoleBinding'

3.4 Sync Policy：同步行为的控制引擎

Sync Policy 决定了 Argo CD 在检测到 Git 与集群状态不一致时的响应方式。主要包含以下模式：

策略选项 说明 适用场景
手动同步 需要用户手动点击 Sync 按钮或通过 CLI 触发同步。 生产环境变更审批流程严格时使用。
自动同步 Argo CD 定期检测差异并自动执行同步。 开发/测试环境，追求快速迭代。
自愈（Self-Heal） 自动修复集群内手动修改的资源，使其与 Git 一致。 防止配置漂移，确保集群状态始终与 Git 对齐。
修剪（Prune） 自动删除 Git 中已移除但集群中仍存在的资源。 清理废弃资源，保持集群整洁。
同步窗口 限制自动同步只能在指定时间段内执行。 生产环境变更窗口管理。
注意： 在生产环境中启用 prune: true 和 selfHeal: true 时，务必确保 Git 仓库中的清单是经过充分测试的。错误的清单变更可能导致资源被意外删除或配置被强制覆盖。

3.5 Sync Status 与 Health Status：应用状态的双维评估

Argo CD 通过两个维度评估 Application 的状态：同步状态（Sync Status） 和 健康状态（Health Status）。两者共同构成了应用部署的完整视图。

3.5.1 Sync Status：一致性评估

Sync Status 反映 Git 仓库中的期望状态与集群中实际状态之间的差异程度：

  • Synced：集群状态与 Git 完全一致。
  • OutOfSync：集群状态与 Git 存在差异，需要同步。
  • SyncFailed：同步操作执行失败。
  • Unknown：状态无法确定，通常由于通信问题。

3.5.2 Health Status：运行健康度评估

Health Status 评估应用内各资源的运行健康度：

  • Healthy：所有资源正常运行。
  • Degraded：部分资源运行异常。
  • Progressing：正在部署或更新中。
  • Missing：期望的资源未在集群中找到。
  • Suspended：资源被暂停（如 HPA 缩容至 0）。
  • Unknown：健康状态无法确定。

3.6 核心概念关系图

下图展示了 Application、Project、Sync Policy、Sync Status 和 Health Status 之间的逻辑关系：

Argo CD 核心概念关系图 Project Application Sync Policy Sync Status Health Status 包含 配置 评估 评估 驱动 核心关系说明 1. Project 是 Application 的逻辑容器，提供隔离与权限控制。 2. Application 通过 Sync Policy 定义同步行为，并产生 Sync Status。 3. Health Status 独立于 Sync Status，评估应用运行健康度。 4. 一个 Application 同时拥有 Sync Status 和 Health Status，共同决定整体状态。

3.7 状态组合与决策矩阵

实际运维中，需要同时关注 Sync Status 和 Health Status 的组合情况。下表列出了常见的状态组合及应对建议：

Sync Status Health Status 含义 建议操作
Synced Healthy 理想状态，集群与 Git 一致且应用正常运行。 无需操作。
Synced Degraded 配置一致但应用运行异常，可能是资源自身故障。 检查 Pod 日志、事件，排查应用级问题。
OutOfSync Healthy 集群与 Git 不一致，但当前应用仍健康运行。 手动或自动同步以消除差异。
OutOfSync Degraded 配置不一致且应用运行异常，需优先处理。 先同步修复配置，再排查应用健康问题。
SyncFailed Unknown 同步操作失败，状态不确定。 查看同步日志，修复 Git 清单或集群连接问题。
关键洞察： Sync Status 和 Health Status 是相互独立的评估维度。一个应用可能处于 Synced + Degraded 状态（配置正确但应用故障），也可能处于 OutOfSync + Healthy 状态（配置有差异但当前运行正常）。理解这种独立性有助于快速定位问题根因。

3.8 实践：通过 CLI 查看状态

使用 Argo CD CLI 可以快速查看 Application 的同步状态和健康状态：

# 查看所有 Application 的状态概览
argocd app list

# 查看特定 Application 的详细信息
argocd app get guestbook

# 查看 Application 的同步状态和健康状态
argocd app status guestbook

输出示例：

Name:               guestbook
Project:            default
Server:             https://kubernetes.default.svc
Namespace:          guestbook
URL:                https://argocd.example.com/applications/guestbook
Repo:               https://github.com/argoproj/argocd-example-apps.git
Target:             HEAD
Path:               guestbook
Sync Policy:        Automated (Prune, SelfHeal)
Sync Status:        Synced
Health Status:      Healthy
← 上一章 📖 返回目录 下一章 →