📚 课程目录第2章同步窗口(Sync Window)基础

2. ArgoCD 基础架构：组件、Application、Project、同步机制与健康检查

2.1 ArgoCD 核心组件架构

ArgoCD 遵循 Kubernetes Operator 模式，由一组微服务组件构成。理解这些组件的职责与交互，是配置同步窗口和 Scheduler 参数的前提。

  核心组件一览： API Server、Repository Server、Application Controller、Redis、Dex/SSO 组件。

2.2 Application 与 Project 概念

2.2.1 Application（应用）

Application 是 ArgoCD 中的核心资源，代表一个 Git 仓库中定义的 Kubernetes 资源集合及其目标部署状态。每个 Application 包含三个关键信息：

Source（源）： Git 仓库 URL、路径、分支、Helm/Kustomize 参数。
Destination（目标）： 目标集群 API Server URL 和 Namespace。
Sync Policy（同步策略）： 手动/自动、自动修剪、自愈、同步窗口等。

2.2.2 Project（项目）

Project 是 Application 的逻辑分组和权限隔离单元。一个 Project 可以包含多个 Application，并提供以下约束：

约束类型	说明	典型配置
源仓库约束	限制 Application 只能从指定的 Git 仓库拉取清单	`sourceRepos: ['https://github.com/myorg/*']`
目标集群约束	限制 Application 只能部署到指定的目标集群	`destinations: [{'namespace': 'prod-*', 'server': 'https://...'}]`
资源白名单/黑名单	限制可创建的 Kubernetes 资源类型	`clusterResourceWhitelist: [{'group': '', 'kind': ''}]`
同步窗口	定义允许或禁止同步的时间窗口	`syncWindows: [...]`

最佳实践： 按环境（dev/staging/prod）或团队创建独立的 Project，并在 Project 级别统一配置同步窗口，避免在每个 Application 中重复定义。

2.3 同步机制详解

ArgoCD 的同步机制是 GitOps 的核心执行引擎。它负责将 Git 仓库中的期望状态（Desired State）应用到目标 Kubernetes 集群。

2.3.1 同步流程步骤

检测差异： Application Controller 定期（默认 3 分钟）或通过 Webhook 触发，比较 Git 中的期望状态与集群中的实际状态。
生成清单： Repo Server 从 Git 仓库拉取代码，并根据 Helm/Kustomize 等工具渲染最终的 Kubernetes 清单。
执行同步： API Server 接收同步请求，调用 Kubernetes API 创建/更新/删除资源。
健康检查： 同步完成后，ArgoCD 对已部署的资源进行健康状态评估。

2.3.2 同步策略对比

策略	自动修剪	自愈	适用场景
手动同步	可选	否	生产环境严格审批流程
自动同步（基础）	否	是	开发/测试环境快速迭代
自动同步 + 修剪	是	是	完全 GitOps 驱动，Git 是唯一真相来源

注意： 启用自动修剪时，务必确保 Git 仓库中的清单是完整的。任何从 Git 中删除的资源，都会在集群中被自动删除，可能导致数据丢失。

2.4 健康检查机制

健康检查是 ArgoCD 评估 Application 是否处于健康状态的核心能力。它通过内置的资源健康检查器（Resource Health Checker）来判断每个 Kubernetes 资源的运行状况。

2.4.1 内置健康检查规则

ArgoCD 为常见 Kubernetes 资源类型提供了默认的健康检查逻辑：

资源类型	健康判定标准
Deployment	所需副本数 == 可用副本数，且所有 Pod 就绪
StatefulSet	当前副本数 == 期望副本数，且所有 Pod 就绪
Service	存在 Endpoints（非 Headless Service）
Ingress	Ingress 规则有效，且关联的 Service 健康
Pod	状态为 Running 且 Ready 条件为 True
Job	Completed（成功）或 Failed（失败）

2.4.2 自定义健康检查

对于自定义资源（CRD）或特殊需求，可以通过 Resource Customizations 或 Lua 脚本 扩展健康检查逻辑。配置示例：

# argocd-cm ConfigMap 中的自定义健康检查
resource.customizations: |
  argoproj.io/Application:
    health.lua: |
      hs = {}
      hs.status = "Progressing"
      hs.message = "Waiting for application to sync"
      if obj.status ~= nil and obj.status.health ~= nil then
        hs.status = obj.status.health.status
        hs.message = obj.status.health.message
      end
      return hs

2.5 同步窗口与 Scheduler 参数的关系

同步窗口（Sync Windows）是 ArgoCD 在 Project 或 Application 级别定义的时间约束，用于控制同步操作何时可以执行。它与 Scheduler 参数配置紧密相关：

同步窗口定义： 使用 cron 表达式或时间范围指定允许/禁止同步的时段。
Scheduler 参数： 控制 Application Controller 的 reconcile 频率、同步队列深度、重试策略等。
协同工作： 同步窗口在 Scheduler 触发同步前进行拦截检查，确保同步只在允许的时间窗口内执行。

  关键配置路径： Project 级同步窗口 → Application 级同步窗口（覆盖） → Scheduler 参数（全局控制 reconcile 节奏）。

2.6 本章小结

ArgoCD 由 API Server、Repo Server、Application Controller、Redis、Dex 五大组件构成，各司其职。
Application 是部署单元，Project 是隔离与约束单元，同步窗口在 Project 级别统一管理。
同步机制包含 检测差异 → 生成清单 → 执行同步 → 健康检查 四个阶段。
健康检查支持内置规则和自定义 Lua 脚本，确保资源状态可观测。
同步窗口与 Scheduler 参数协同，实现精细化的同步节奏控制，为后续章节的 Scheduler 参数配置打下基础。