📚 课程目录第4章多集群部署模式

4、多集群部署模式：Hub-and-Spoke模式、控制平面集中管理、工作集群注册机制

在云原生多集群治理中，Hub-and-Spoke（中心辐射） 是最主流、最成熟的部署模式。Argo CD 作为控制平面（Hub），集中管理多个工作集群（Spoke），通过统一的注册机制实现集群发现、凭证存储与应用分发。本章深入剖析该模式的架构原理、控制平面职责以及工作集群的注册流程。

4.1 Hub-and-Spoke 模式架构总览

Hub-and-Spoke 模式的核心思想是：一个控制平面（Hub）管理多个工作集群（Spoke）。控制平面运行 Argo CD 核心组件（API Server、Repo Server、Application Controller），工作集群仅运行轻量级的 argocd-agent 或通过 kubeconfig 暴露 API Server 端点。所有应用编排、同步策略、状态监控均在 Hub 侧完成。

  关键优势：
  统一管控： 所有集群的应用状态在一个控制台内可见，无需逐个登录工作集群。
安全隔离： 工作集群无需暴露 API Server 给外部网络，仅需 Hub 侧具备网络可达性。
策略一致性： 可在 Hub 侧定义全局策略（如 RBAC、Project 配额），并下发至所有 Spoke 集群。
弹性扩展： 新增工作集群只需注册凭证，无需重新部署控制平面。

4.2 控制平面集中管理职责

在 Hub-and-Spoke 模式下，控制平面承担了所有核心管理职能。下表列出了控制平面各组件在多集群场景下的具体职责：

组件	多集群职责	关键行为
API Server	集群注册、凭证管理、RBAC 策略下发	接收 `argocd cluster add` 请求，验证 kubeconfig 有效性，存储加密凭证
Repo Server	Git 仓库统一管理、多集群差异化参数生成	根据目标集群名称/标签，渲染 Helm/Kustomize 参数，生成集群专属清单
Application Controller	跨集群应用状态同步、健康检查、自动修复	为每个集群维护独立的 sync 循环，通过集群 Secret 中的凭证连接目标集群 API
Redis	缓存集群列表、应用状态、Git 数据	存储集群元数据，加速多集群查询响应

最佳实践： 控制平面应部署在独立的 Kubernetes 集群中，避免与工作集群共享资源。推荐使用高可用部署（至少 3 个副本），并配置持久化存储用于 Redis 和 ArgoCD 配置。

4.3 工作集群注册机制

工作集群注册是 Hub-and-Spoke 模式的核心操作。Argo CD 提供了两种注册方式：kubeconfig 导入 和 argocd-agent 反向连接。以下为两种方式的对比与详细步骤。

4.3.1 注册方式对比

特性	kubeconfig 导入	argocd-agent 反向连接
网络要求	Hub 侧需直接访问 Spoke 集群 API Server	Spoke 侧主动连接 Hub（反向隧道）
安全模型	Hub 持有 Spoke 集群的 ServiceAccount	Spoke 集群运行 agent，仅需出站访问 Hub
适用场景	Hub 与 Spoke 在同一 VPC 或 VPN 内	Spoke 集群位于防火墙后或 NAT 环境
注册命令	`argocd cluster add <context>`	`argocd-agent install` (在 Spoke 侧)
凭证存储	Hub 侧 Namespace 中创建 Secret	Hub 侧自动创建 Secret，agent 管理轮换

4.3.2 kubeconfig 导入注册步骤

准备 kubeconfig： 在工作集群中创建一个 ServiceAccount，并绑定 cluster-admin 角色（或最小权限角色），导出其 kubeconfig。
执行注册命令： 在 Hub 侧运行 argocd cluster add <context-name> --kubeconfig <path>。
验证注册： 使用 argocd cluster list 查看集群状态，确认 STATUS 为 Successful。
配置应用： 在 Application 的 spec.destination 中指定 name 或 server 为目标集群。

# 示例：注册工作集群
argocd cluster add prod-cluster --kubeconfig ./prod-kubeconfig.yaml

# 查看已注册集群
argocd cluster list
# 输出示例：
# SERVER                          NAME           STATUS     MESSAGE
# https://prod-api.example.com    prod-cluster   Successful

4.3.3 argocd-agent 反向连接注册

argocd-agent 是 Argo CD 官方提供的轻量级代理，适用于工作集群无法被 Hub 直接访问的场景。agent 在 Spoke 集群内运行，主动建立与 Hub 的 gRPC 连接。

在 Hub 侧生成令牌： argocd account generate- --account agent
在 Spoke 侧安装 agent： 使用 Helm Chart 或 manifest 部署 argocd-agent，配置 Hub 地址和令牌。
自动注册： agent 启动后自动向 Hub 注册，Hub 侧创建对应的集群 Secret。
验证连接： 在 Hub 侧 argocd cluster list 中看到新集群，STATUS 为 Connected。

# 示例：在 Spoke 集群中安装 argocd-agent（使用 Helm）
helm repo add argo https://argoproj.github.io/argo-helm
helm install argocd-agent argo/argocd-agent \
  --namespace argocd-agent \
  --create-namespace \
  --set config.hubAddress=wss://hub.example.com:443 \
  --set config.=your-agent-

4.4 集群注册后的凭证管理

无论使用哪种注册方式，Argo CD 都会在控制平面的 argocd Namespace 中创建一个 Secret，用于存储目标集群的访问凭证。该 Secret 的命名格式为 cluster-<cluster-name>-<hash>，内容包含 server、config（kubeconfig 内容）等字段。

安全注意事项：

集群 Secret 包含高权限，应严格控制对 argocd Namespace 的 RBAC 访问。
建议启用 Argo CD 的 secret management 功能（如 Sealed Secrets、External Secrets Operator）对集群凭证进行加密存储。
定期轮换工作集群的 ServiceAccount ，并更新对应的 Secret。

4.5 多集群应用分发示例

注册完成后，即可通过 Application 或 ApplicationSet 将应用分发到多个工作集群。以下是一个使用 ApplicationSet 同时部署到三个集群的示例：

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: multi-cluster-app
spec:
  generators:
    - clusters:
        selector:
          matchLabels:
            environment: production
  template:
    metadata:
      name: '{{name}}-guestbook'
    spec:
      project: default
      source:
        repoURL: https://github.com/argoproj/argocd-example-apps.git
        targetRevision: HEAD
        path: guestbook
      destination:
        name: '{{name}}'
        namespace: guestbook
      syncPolicy:
        automated:
          prune: true
          selfHeal: true

该 ApplicationSet 会遍历所有带有 environment: production 标签的已注册集群，为每个集群生成一个独立的 Application，实现一键多集群部署。