4. Argo CD 基础：安装、架构、核心概念

Argo CD 是 Kubernetes 生态中最主流的声明式 GitOps 持续交付工具。本章将围绕其安装流程、整体架构以及三个核心概念——Application（应用）、Project（项目）、Repo（仓库）——展开讲解，为后续面板化呈现日志平台组件拓扑与 SLO 监控奠定基础。

4.1 安装 Argo CD

Argo CD 以 Kubernetes 原生方式部署，推荐使用 kubectl 或 Helm 进行安装。以下为最简安装步骤：

  1. 创建命名空间：kubectl create namespace argocd
  2. 应用官方安装清单：kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
  3. 暴露 API Server：将 Service 类型改为 LoadBalancer 或使用 kubectl port-forward 本地转发
  4. 获取初始密码：kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d
  5. 登录 Web UI：默认用户名为 admin，使用上一步获取的密码登录
生产环境建议：使用 Helm Chart 安装，便于版本管理与参数定制。安装前确保集群已安装 ingress-nginx 或 cert-manager 等依赖组件。

4.2 架构概览

Argo CD 采用 控制面-工作负载 分离架构，核心组件包括：

组件 职责 部署位置
API Server 提供 gRPC/REST 接口，处理 Web UI、CLI、CI/CD 系统请求 控制面
Repository Server 缓存 Git 仓库内容，生成 Kubernetes 清单 控制面
Application Controller 持续对比期望状态（Git）与实际状态（集群），执行同步 控制面
Redis 缓存应用状态与 Git 数据，提升性能 控制面
Dex / 外部 OIDC 身份认证与单点登录集成 可选

下图展示了 Argo CD 各组件之间的交互关系：

Argo CD 架构组件交互图 Argo CD 核心架构 用户 / CI 系统 API Server Repository Server Application Controller Redis 缓存 Git 仓库 Kubernetes 集群 说明：API Server 统一接收请求，Repository Server 拉取 Git 清单，Application Controller 负责同步至集群

4.3 核心概念详解

4.3.1 Application（应用）

Application 是 Argo CD 中最核心的 CRD（Custom Resource Definition），它定义了一个部署单元的完整生命周期。一个 Application 包含以下关键字段：

  • source：指定 Git 仓库路径、目标修订版本（branch/tag/commit）及清单文件路径
  • destination：指定目标集群与命名空间
  • syncPolicy：定义自动同步策略（如 automated: { prune: true, selfHeal: true }）
  • syncStatus：当前同步状态（Synced / OutOfSync / Unknown）
  • healthStatus：应用健康状态（Healthy / Degraded / Progressing）
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: log-platform
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://git.example.com/log-platform.git
    targetRevision: main
    path: k8s/overlays/production
  destination:
    server: https://kubernetes.default.svc
    namespace: logging
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

4.3.2 Project（项目）

Project 是 Argo CD 中的逻辑隔离单元，用于管理多个 Application 的访问权限与资源约束。每个 Application 必须属于一个 Project。Project 的主要能力包括：

功能 说明 典型配置
源仓库白名单 限制允许使用的 Git 仓库 URL sourceRepos: ['https://git.example.com/*']
目标集群白名单 限制允许部署的目标集群与命名空间 destinations: [{'namespace': 'logging', 'server': 'https://...'}]
资源配额 限制可管理的 Kubernetes 资源类型 clusterResourceWhitelist: [{'group': '*', 'kind': '*'}]
角色绑定 通过 RBAC 控制用户/组的操作权限 roles: [{'name': 'admin', 'policies': [...]}]
最佳实践：为每个业务线或环境（如 dev/staging/production）创建独立的 Project，实现权限隔离与资源管控。

4.3.3 Repo（仓库）

Repo 是 Argo CD 连接 Git 仓库的凭证与配置对象。Argo CD 支持两种仓库注册方式：

  • 通过 CLI 注册：argocd repo add https://git.example.com/log-platform.git --username user --password pass
  • 通过 Secret 注册：在 argocd 命名空间创建包含仓库凭证的 Kubernetes Secret

仓库配置支持以下认证方式：

认证方式 适用场景 配置示例
HTTPS + 用户名密码 私有仓库基础认证 --username admin --password xxx
SSH 密钥 GitHub/GitLab SSH 访问 --ssh-private-key-path ~/.ssh/id_rsa
GitHub App / GitLab CI/CD 自动化集成 -- ghp_xxxxxxxx
OAuth2 / 自定义 CA 企业级安全合规 --tls-client-cert-path ...

下图展示了 Application、Project、Repo 三者之间的逻辑关系：

Argo CD 核心概念关系图 Application · Project · Repo 关系 Project（项目） Repo（仓库） Application（应用） 目标集群 / 命名空间 source.repoURL destination.server / namespace 一个 Project 可包含多个 Repo 与多个 Application；每个 Application 引用一个 Repo 并部署至一个目标集群

4.4 核心工作流程

Argo CD 的 GitOps 循环可概括为以下步骤：

  1. 注册仓库：将 Git 仓库凭证添加至 Argo CD
  2. 创建 Project：定义资源约束与权限边界
  3. 创建 Application：指定 source（仓库路径）与 destination（集群命名空间）
  4. 自动同步：Application Controller 定期对比 Git 与集群状态，发现差异后自动或手动同步
  5. 健康检查：同步完成后检查 Pod、Service 等资源是否达到期望状态
  6. 持续监控：Argo CD 持续监听 Git 仓库变更与集群状态变化，确保始终一致
常见陷阱：
- 忘记配置 automated.prune: true 会导致 Git 中删除的资源在集群中残留
- 多个 Application 指向同一命名空间时，需通过 Project 的 destinations 白名单避免冲突
- 仓库凭证过期会导致同步失败，建议使用 或 SSH 密钥并设置自动轮换

4.5 本章小结

← 上一章 📖 返回目录 下一章 →