3. 集群注册与多集群管理：使用 Argo CD 管理多个 Kubernetes 集群

在生产环境中，单一 Kubernetes 集群往往无法满足隔离性、地域分布或资源扩展的需求。Argo CD 作为声明式 GitOps 工具，原生支持多集群管理，允许用户通过一个中心 Argo CD 实例，将应用同步至多个远端集群。本章节将深入讲解集群注册的核心机制、Secret 的创建与维护，以及多集群场景下的最佳实践。

3.1 多集群架构与核心概念

Argo CD 采用 Hub-and-Spoke（中心辐射）模型。中心集群运行 Argo CD 控制平面，负责监听 Git 仓库、维护应用状态；远端集群仅需运行标准 kubelet 组件，无需安装 Argo CD 实例。控制平面通过 集群 Secret 中存储的 kubeconfig 或 bearer 与远端集群的 API Server 通信。

关键术语：
  • 控制平面集群（Hub）： 部署 Argo CD 组件（application-controller, api-server, repo-server）的集群。
  • 目标集群（Spoke）： 被 Argo CD 管理的远端集群，运行实际工作负载。
  • 集群 Secret： 位于控制平面集群 argocd 命名空间下的 Kubernetes Secret，包含连接远端集群所需的认证信息。
Argo CD 多集群 Hub-and-Spoke 架构图 Argo CD 多集群 Hub-and-Spoke 架构 控制平面集群 (Hub) Argo CD 组件 application-controller api-server / repo-server 集群 Secret 存储 远端集群 A kubelet / API Server 生产工作负载 远端集群 B kubelet / API Server 预发布工作负载 远端集群 C kubelet / API Server 灾备工作负载 说明：控制平面通过集群 Secret 中的 kubeconfig 与远端集群 API Server 通信，实现应用同步。

3.2 集群注册方式与 Secret 结构

Argo CD 提供两种主要的集群注册方式：CLI 命令注册 和 手动创建 Secret。无论哪种方式，最终都会在 argocd 命名空间下生成一个类型为 Opaque 的 Secret，并带有特定标签 argocd.argoproj.io/secret-type: cluster。

3.2.1 集群 Secret 核心字段

字段 类型 说明 是否必填
name string 集群在 Argo CD 中的显示名称 是
server string 远端集群 API Server 的 URL 地址 是
config JSON (string) 包含认证凭据（bearer 、TLS 证书或 kubeconfig 内容） 是
labels map 可选标签，用于按环境或区域筛选集群 否
annotations map 可选注解，如描述信息或自定义元数据 否

3.2.2 方法一：使用 argocd CLI 注册

这是最便捷的方式，适用于拥有远端集群 kubeconfig 的场景。

# 将当前 kubeconfig 的 context 注册到 Argo CD
argocd cluster add <context-name> \
  --name <cluster-display-name> \
  --label env=production \
  --label region=us-east-1

# 验证集群列表
argocd cluster list
提示： CLI 会自动读取当前 kubeconfig 中的 context，提取 API Server 地址和用户凭据，并创建对应的集群 Secret。建议使用 --label 参数为集群打上环境标签，便于后续应用按标签选择目标集群。

3.2.3 方法二：手动创建集群 Secret

当无法直接使用 CLI（如 CI/CD 流水线、基础设施即代码场景）时，可以手动创建 Secret YAML 文件并 apply 到控制平面集群。

apiVersion: v1
kind: Secret
metadata:
  name: cluster-production-01
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: cluster
    env: production
    region: us-east-1
type: Opaque
stringData:
  name: production-01
  server: https://api.prod-cluster.example.com:6443
  config: |
    {
      "bearerToken": "<your-service-account->",
      "tlsClientConfig": {
        "insecure": false,
        "caData": "<base64-encoded-ca-cert>"
      }
    }
  # 可选：直接嵌入 kubeconfig
  # kubeconfig: |
  #   apiVersion: v1
  #   kind: Config
  #   ...
安全警告： 切勿将明文 提交到 Git 仓库。建议使用 Sealed Secrets、External Secrets Operator 或 Vault 等工具加密存储敏感字段。生产环境中应优先使用 bearerToken 结合 ServiceAccount，而非长期有效的 kubeconfig 文件。

3.3 集群生命周期维护与漂移复测

多集群管理的核心挑战在于保持集群注册信息的准确性和一致性。当集群证书轮换、API Server 地址变更或集群被销毁时，Argo CD 需要及时感知并更新集群 Secret。

3.3.1 集群健康状态监控

Argo CD 会定期（默认每 30 秒）向已注册集群的 API Server 发送健康检查请求。如果连续多次失败，该集群会被标记为 Unhealthy 或 Unknown 状态。

# 查看集群健康状态
argocd cluster list

# 输出示例：
# SERVER                          NAME             STATUS     MESSAGE
# https://api.prod-cluster.com    production-01    Successful
# https://api.staging-cluster.com staging-01       Unhealthy  Failed to establish connection

3.3.2 集群 Secret 更新流程

当集群凭据发生变化时，需要更新对应的 Secret。更新后，Argo CD 会自动重新加载配置，无需重启服务。

  1. 获取当前 Secret： kubectl get secret cluster-production-01 -n argocd -o yaml
  2. 更新 config 字段： 修改 bearerToken 或 caData 为新值。
  3. 应用更新： kubectl apply -f updated-secret.yaml
  4. 验证连接： 使用 argocd cluster list 确认状态恢复为 Successful。

3.3.3 漂移复测：集群注册一致性校验

在 GitOps 实践中，集群注册信息本身也应作为代码管理。通过定期复测（Reconciliation），确保控制平面中的集群 Secret 与 Git 仓库中的声明式定义保持一致。

复测策略：
  • 声明式集群定义： 将集群 Secret 的 YAML 模板存储在 Git 仓库的 clusters/ 目录下。
  • 自动同步： 使用 Argo CD Application 管理集群 Secret 自身（自管理模式），或通过 CI/CD 流水线定期 apply。
  • 漂移检测： 对比 Git 中的期望 Secret 与集群中的实际 Secret，若发现 过期、地址变更等差异，自动触发更新。
集群注册漂移复测流程 集群注册漂移复测流程 Git 仓库 期望集群 Secret 定义 CI/CD 流水线 对比 & 同步 控制平面集群 实际集群 Secret 漂移检测 发现不一致 自动修复 更新 Secret 并验证 反馈闭环：持续复测 说明：通过 GitOps 闭环，确保集群注册信息始终与声明式定义一致，消除配置漂移。

3.4 多集群管理最佳实践

实践项 说明 推荐等级
使用 ServiceAccount 而非用户 为每个远端集群创建专用 ServiceAccount，并绑定最小权限的 RBAC 角色。避免使用 admin 级别的 kubeconfig。 强制
标签化集群分类 使用 env、region、team 等标签对集群进行分类，便于 Application 按标签选择目标。 推荐
集群 Secret 加密存储 在 Git 仓库中仅存储加密后的 Secret（如 SealedSecret），或使用 External Secrets Operator 从 Vault 拉取。 强制
定期健康检查与告警 配置 Prometheus 监控 Argo CD 集群状态指标，对 Unhealthy 集群发送告警。 推荐
集群生命周期自动化 通过 CI/CD 流水线自动注册新集群、更新过期证书、注销已销毁集群。 可选

3.5 常见问题与排错

  • 集群状态一直显示 Unknown： 检查控制平面到远端集群的网络连通性，确认 API Server 地址是否可达，防火墙是否放行 6443 端口。
  • 认证失败（Unauthorized）： 确认 ServiceAccount 的 是否过期，RBAC 权限是否足够（至少需要 get, list, watch 资源权限）。
  • 证书错误（x509）： 更新 Secret 中的 caData 字段，或设置 insecure: true（仅测试环境）。
  • 集群 Secret 被误删除： 如果使用 GitOps 管理集群 Secret，重新 apply 即可恢复；否则需重新注册集群。
排错命令速查： 
# 查看集群详情
argocd cluster get <cluster-server-url>

# 查看 Argo CD 日志
kubectl logs -n argocd deployment/argocd-application-controller | grep -i cluster

# 手动触发集群重新连接
argocd cluster update <cluster-server-url>
← 上一章 📖 返回目录 下一章 →