第 5/60 天
引言
在 GitOps 的浪潮中，Argo CD 已经成为 Kubernetes 生态中最受欢迎的持续交付工具。无论是初创公司还是大型企业，Argo CD 都在生产环境中承载着关键业务的部署任务。
然而，很多初学者在第一次接触 Argo CD 时，常常被 Application、Project、Sync 策略这些核心概念搞晕：Argo CD Application 和 Kubernetes 的 Deployment 有什么关系？Project 到底在隔离什么？Sync 策略中的自动同步和自愈有什么不同？
本文将深入浅出地介绍 Argo CD 的三大核心概念——Application（应用）、Project（项目） 和 Sync（同步）策略，配合完整的 YAML 示例和实战命令，帮助你快速掌握 Argo CD 的使用精髓。无论你是刚刚接触 GitOps 的运维工程师，还是正在评估 Argo CD 的架构师，这篇文章都能为你提供清晰的认知框架。
核心概念
什么是 Argo CD？
Argo CD 是一个基于 Kubernetes 的声明式 GitOps 持续交付工具。它的核心理念是：Git 仓库中保存的 Kubernetes 清单文件是集群状态的「唯一事实来源」，Argo CD 负责确保集群中的实际状态与 Git 中声明的状态保持一致。
三大核心概念关系图
┌─────────────────────────────────────────────────────────┐
│ Argo CD 架构 │
│ │
│ ┌──────────────┐ ┌────────────────┐ │
│ │ Git 仓库 │ │ Kubernetes │ │
│ │ (声明状态) │◄───│ 集群 │ │
│ └──────────────┘ │ (实际状态) │ │
│ ▲ └────────────────┘ │
│ │ Argo CD 持续比较 & 同步 │
│ │ │
│ ┌─────────────────────────────────────┐ │
│ │ Argo CD 内部资源 │ │
│ │ │ │
│ │ ┌──────────┐ ┌───────────────┐ │ │
│ │ │ Project │───►│ Application │ │ │
│ │ │ (项目) │ │ (应用) │ │ │
│ │ └──────────┘ └───────┬───────┘ │ │
│ │ │ │ │
│ │ ┌──────▼───────┐ │ │
│ │ │ Sync 策略 │ │ │
│ │ │ (同步策略) │ │ │
│ │ └──────────────┘ │ │
│ └─────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
1. Application（应用）
Application 是 Argo CD 中最核心的资源对象，它定义了一个部署单元——从哪个 Git 仓库的哪个路径读取 Kubernetes 清单，部署到哪个目标集群和命名空间。
一个 Application 包含三个关键要素：
| 要素 | 说明 | 示例 |
|---|---|---|
| Source（来源） | Git 仓库地址、路径、分支 | https://github.com/example/app-config.git，路径 deploy/overlays/prod |
| Destination（目标） | 目标集群 URL 和命名空间 | https://kubernetes.default.svc，命名空间 production |
| Sync Policy（同步策略） | 自动/手动同步、自愈、修剪行为 | automated: { prune: true, selfHeal: true } |
2. Project（项目）
Project 是 Argo CD 中的逻辑隔离单元，用于将多个 Application 分组管理，并对其施加访问控制和安全约束。核心功能包括：
- 来源仓库白名单：限制 Project 下的 Application 只能从指定的 Git 仓库拉取配置
- 目标集群白名单：限制 Application 只能部署到指定的目标集群和命名空间
- 资源类型限制：限制可以创建的资源类型（如禁止创建 ClusterRole）
- RBAC 权限：与 Argo CD RBAC 集成，控制不同用户/团队对 Project 的访问权限
3. Sync 策略（同步策略）
Sync 策略定义了 Argo CD 如何将 Git 中的声明状态应用到集群。分为同步策略和同步选项两个维度：
同步策略类型：
| 策略 | 说明 | 适用场景 |
|---|---|---|
| 手动同步 | 需要人工触发 argocd app sync 命令或点击 UI 按钮 |
生产环境、变更审批流程严格的团队 |
| 自动同步 | Argo CD 自动检测 Git 状态变化并同步到集群 | 开发环境、快速迭代的团队 |
核心同步选项：
| 选项 | 说明 | 风险 |
|---|---|---|
| Prune（修剪） | 自动删除 Git 中已移除但集群中仍存在的资源 | 高——误删资源 |
| SelfHeal（自愈） | 自动恢复被手动修改的集群资源到 Git 声明状态 | 中——禁止临时调试修改 |
| Apply Out of Sync Only | 仅同步状态不一致的资源 | 无——默认行为，减少不必要的 API 调用 |
实战步骤
环境准备
在开始之前，请确保已经部署了 Argo CD。如果你还没有安装，以下命令可以快速部署：
# 创建命名空间
kubectl create namespace argocd
# 安装 Argo CD（最新稳定版）
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
# 查看 Pod 状态，等待所有组件就绪
kubectl wait --for=condition=Ready pods --all -n argocd --timeout=300s
# 获取初始 admin 密码
kubectl -n argocd get secret argocd-initial-admin-secret
-o jsonpath="{.data.password}" | base64 -d
第一步：创建 Argo CD Project
Project 是资源隔离的第一道防线。以下 YAML 创建一个名为 devops-team 的 Project，限制只能从指定的 Git 仓库部署，并且只能部署到 dev 和 staging 命名空间：
# project-devops.yaml
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
name: devops-team
namespace: argocd
spec:
description: "DevOps 团队项目，管理微服务部署"
# 来源仓库白名单——只允许从这些仓库拉取配置
sourceRepos:
- 'https://github.com/example/microservices-config.git'
- 'https://gitlab.internal.com/team-ops/*'
# 目标集群和命名空间白名单
destinations:
- namespace: dev
server: https://kubernetes.default.svc
- namespace: staging
server: https://kubernetes.default.svc
- namespace: production
server: https://kubernetes.default.svc
# 拒绝创建集群级别的资源（ClusterRole, ClusterRoleBinding 等）
clusterResourceWhitelist:
- group: '*'
kind: '*'
# 允许创建的命名空间资源类型
namespaceResourceBlacklist:
- group: 'rbac.authorization.k8s.io'
kind: 'ClusterRole'
- group: 'rbac.authorization.k8s.io'
kind: 'ClusterRoleBinding'
# 可选：对同步行为进行限制
syncWindows:
- kind: deny
schedule: '0 22 * * *'
duration: 6h
applications:
- '*-production'
clusters:
- 'https://kubernetes.default.svc'
namespaces:
- production
部署 Project：
kubectl apply -f project-devops.yaml
说明：
syncWindows字段定义了禁止同步的时间窗口。上面的配置禁止在每晚 22:00 到次日凌晨 4:00 之间对生产环境的任何应用进行同步——这是变更冻结窗口的典型用法。
第二步：创建 Application 资源
Application 是 Argo CD 的核心工作单元。以下示例展示了一个完整的 Application 配置，包含自动同步、自愈和修剪功能：
# application-order-service.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: order-service
namespace: argocd
# 为 Application 添加标签，便于分组管理
labels:
team: devops
tier: backend
environment: production
spec:
# 所属 Project（必须引用已存在的 Project）
project: devops-team
# 来源——Git 仓库配置
source:
repoURL: 'https://github.com/example/microservices-config.git'
targetRevision: main # 分支或标签
path: services/order-service/overlays/production
# 可选：指定 Helm 参数
helm:
valueFiles:
- values.yaml
- values-production.yaml
parameters:
- name: replicaCount
value: "5"
- name: resources.requests.cpu
value: "500m"
# 目标——部署位置
destination:
server: 'https://kubernetes.default.svc'
namespace: production
# 同步策略
syncPolicy:
automated:
prune: true # 自动删除 Git 中已移除的资源
selfHeal: true # 自动恢复被手动修改的资源
allowEmpty: false # 不允许空同步（同步后无资源则报错）
# 同步选项
syncOptions:
- CreateNamespace=true # 自动创建目标命名空间（如果不存在）
- PruneLast=true # 先创建新资源，再删除旧资源
- ApplyOutOfSyncOnly=true # 仅应用状态不一致的资源
- ServerSideApply=true # 使用服务端 Apply（K8s 1.22+）
- RespectIgnoreDifferences=true
# 忽略差异（某些字段自动变化，忽略这些差异避免一直 OutOfSync）
ignoreDifferences:
- group: apps
kind: Deployment
jsonPointers:
- /spec/replicas # 忽略 HPA 自动调整的副本数
- group: autoscaling
kind: HorizontalPodAutoscaler
jsonPointers:
- /status # 忽略 status 子资源
部署 Application：
kubectl apply -f application-order-service.yaml
第三步：使用 argocd CLI 管理 Application
除了 YAML 声明式管理，argocd CLI 提供了丰富的交互式命令：
# 登录 Argo CD API Server
argocd login argocd.example.com --username admin --password <password> --insecure
# 列出所有 Application
argocd app list
# 查看 Application 的详细状态
argocd app get order-service
# 手动触发同步（覆盖自动同步策略）
argocd app sync order-service --prune --apply-out-of-sync-only
# 查看 Application 的同步状态和资源树
argocd app diff order-service
# 回滚到上一个同步版本
argocd app rollback order-service --id 1
# 暂停自动同步（临时禁止自动同步，维护时使用）
argocd app set order-service --sync-policy manual
# 恢复自动同步
argocd app set order-service --sync-policy automated --auto-prune --self-heal
# 查看 Application 的事件日志
argocd app logs order-service
# 删除 Application（不会删除集群中的资源，除非指定 --cascade）
argocd app delete order-service
第四步：配置 Sync 窗口与策略约束
在生产环境中，我们通常需要限制同步的时间窗口，避免在业务高峰期触发部署。以下是更精细的同步策略配置：
# sync-windows.yaml
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
name: production-team
namespace: argocd
spec:
sourceRepos:
- 'https://github.com/example/*'
destinations:
- namespace: '*'
server: 'https://kubernetes.default.svc'
# 同步窗口——细粒度控制
syncWindows:
# 规则 1：工作日 9:00-18:00 允许自动同步
- kind: allow
schedule: '0 9 * * 1-5'
duration: 9h
applications:
- '*'
clusters:
- '*'
namespaces:
- 'dev'
- 'staging'
# 规则 2：工作日 22:00-次日 6:00 禁止所有同步（生产环境变更冻结）
- kind: deny
schedule: '0 22 * * 1-5'
duration: 8h
applications:
- '*-production'
namespaces:
- 'production'
# 规则 3：周末全天禁止同步生产环境
- kind: deny
schedule: '0 0 * * 0,6'
duration: 24h
applications:
- '*-production'
namespaces:
- 'production'
# 手动同步窗口覆盖（允许人工审批后手动同步）
manualSync: true
第五步：多环境 Application 管理
一个典型的微服务在不同环境（dev/staging/prod）下有不同配置。通过 Argo CD 的 Application 可以实现多环境管理：
# 开发环境 Application
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: order-service-dev
namespace: argocd
labels:
app: order-service
environment: dev
spec:
project: devops-team
source:
repoURL: 'https://github.com/example/microservices-config.git'
targetRevision: develop
path: services/order-service/overlays/dev
destination:
server: 'https://kubernetes.default.svc'
namespace: dev
syncPolicy:
automated:
prune: true
selfHeal: true
---
# 生产环境 Application（更保守的策略）
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: order-service-prod
namespace: argocd
labels:
app: order-service
environment: production
spec:
project: devops-team
source:
repoURL: 'https://github.com/example/microservices-config.git'
targetRevision: main # 生产环境使用 main 分支，更稳定
path: services/order-service/overlays/production
destination:
server: 'https://kubernetes.default.svc'
namespace: production
syncPolicy:
# 生产环境使用手动同步，需要人工审批
automated:
prune: false
selfHeal: false
第六步：验证 Application 状态
部署完成后，可以通过以下方式验证 Application 状态：
# 通过 CLI 查看 Application 同步状态
argocd app get order-service
# 输出示例：
# Name: order-service
# Project: devops-team
# Server: https://kubernetes.default.svc
# Namespace: production
# URL: https://argocd.example.com/applications/order-service
# Repo: https://github.com/example/microservices-config.git
# Target: main
# Path: services/order-service/overlays/production
# Sync Policy: Automated (Prune)
# Sync Status: Synced
# Health Status: Healthy
#
# GROUP KIND NAMESPACE NAME STATUS HEALTH
# apps Deployment production order-service Synced Healthy
# v1 Service production order-service Synced Healthy
# v1 ConfigMap production order-service-config Synced Healthy
# autoscaling Horizontal... production order-service-hpa Synced Healthy
# 通过 API 查询 Application 状态（JSON 格式）
kubectl get application order-service -n argocd -o json | jq '.status'
常见问题
Q1: Application 和 Project 的区别是什么？为什么需要 Project？
A: Application 是具体的部署单元，描述「从哪个仓库、部署到哪个集群、用什么策略」。Project 是 Application 的逻辑分组和权限边界，用于控制「哪些仓库可以拉取、哪些集群可以部署、哪些资源类型可以创建」。
简单说：Application 是「做什么」，Project 是「谁能做什么」。在多团队场景中，Project 至关重要——没有 Project，任何团队都能创建 Application 部署到生产集群，这是巨大的安全风险。
Q2: 自动同步的 SelfHeal 和 Prune 有什么区别？何时应该开启？
A:
– SelfHeal（自愈）：当有人用 kubectl edit 手动修改了集群中的资源，Argo CD 会自动将其恢复为 Git 中声明的状态。适合需要严格禁止手动修改的环境。
– Prune（修剪）：当 Git 仓库中删除了某个资源（如删除了一个 Deployment 的 YAML 文件），Argo CD 会自动删除集群中对应的资源。适合需要精确控制资源生命周期的场景。
建议： 开发环境可以同时开启两者；生产环境推荐手动同步，或仅开启 SelfHeal 不开启 Prune（避免误删资源）。
Q3: 创建 Application 报错 rpc error: code = PermissionDenied 怎么办？
A: 通常是因为 Application 引用的 Project 不存在，或者 Application 的 source.repoURL 不在 Project 的 sourceRepos 白名单中。排查步骤：
# 1. 确认 Project 存在
kubectl get appproject -n argocd
# 2. 检查 Project 的 sourceRepos 白名单
kubectl get appproject devops-team -n argocd -o yaml | grep sourceRepos -A 5
# 3. 如果需要，更新 Project 白名单
kubectl edit appproject devops-team -n argocd
Q4: 修改了 Git 仓库中的 YAML，但 Argo CD 没有自动同步？
A: 检查以下几点：
1. 同步策略是否为自动同步：kubectl get application <name> -n argocd -o yaml | grep syncPolicy 确认 automated 字段存在
2. Argo CD 轮询间隔：默认每 3 分钟检查一次 Git 仓库。可以配置 webhook 加速（GitHub/GitLab webhook 直达 Argo CD）
3. Sync 窗口限制：确认当前时间不在 syncWindows 的 deny 窗口内
4. Git 仓库访问权限：确认 Argo CD 有读取该仓库的权限（SSH key 或 token）
Q5: 如何实现 Argo CD Application 的蓝绿部署和灰度发布？
A: Argo CD 本身不支持蓝绿发布和灰度发布——这是 Argo Rollouts 的职责。Argo CD 负责部署和同步，Argo Rollouts 负责渐进式发布。两者的关系是：Argo CD 管理 Rollouts 资源，Rollouts 管理 Deployment 的流量切换。我们将在第 39 天（Argo Rollouts 渐进式发布）中详细展开。
总结
本文介绍了 Argo CD 的三大核心概念以及实战配置方法，核心要点如下：
- Application 是部署单元：定义了从 Git 仓库到 Kubernetes 集群的完整部署路径，包括来源、目标、策略三要素
- Project 是隔离边界：通过来源仓库白名单、目标集群白名单和资源类型限制，实现多团队的安全隔离
- Sync 策略控制同步行为：手动同步适合生产环境，自动同步（含 Prune 和 SelfHeal）适合开发环境；Sync 窗口可以限制变更时间
- 多环境管理：通过不同分支、不同路径、不同同步策略，可以用 Argo CD 统一管理 dev/staging/prod 环境
- CLI 与声明式 YAML 双管齐下：Application 和 Project 既可以用 YAML 声明式管理（GitOps 模式），也可以用 argocd CLI 进行交互式操作
在接下来的文章中，我们将深入 Argo CD 的安装配置、RBAC 权限模型、多环境管理最佳实践，以及 Argo CD 与 Tekton + Harbor 的完整集成方案。
暂无评论内容