4. 多集群注册与管理：使用 Argo CD CLI 与 UI 注册多个目标集群，管理 Cluster Secrets，实现集群的增删改查

在多集群 GitOps 架构中，Argo CD 作为控制平面（Control Plane），需要与多个目标集群（Target Clusters）建立信任关系，才能将应用部署到不同环境。本章将深入讲解集群注册的两种方式（CLI 与 UI）、底层 Cluster Secret 的结构，以及如何通过增删改查操作实现集群生命周期的管理。

4.1 集群注册的核心原理

Argo CD 并不直接存储集群的完整 kubeconfig，而是将每个目标集群的访问凭证封装为一个 Kubernetes Secret，存放在 Argo CD 所在的命名空间（通常为 argocd）中。这个 Secret 被称为 Cluster Secret，其命名规范为 cluster-<集群名称>-<随机后缀>。

4.2 使用 Argo CD CLI 注册集群

CLI 是最直接、最常用的注册方式，尤其适合自动化脚本和 CI/CD 流水线。核心命令为 argocd cluster add。

4.2.1 前置条件

• 已安装 Argo CD CLI 并登录到 Argo CD 服务端。
• 本地 kubeconfig 中已包含目标集群的上下文（context）。
• 目标集群的 kubeconfig 中需包含一个具有足够权限的 ServiceAccount 或用户凭证。

4.2.2 注册命令与参数

# 注册一个名为 "prod-cluster" 的集群
argocd cluster add prod-cluster

# 指定 kubeconfig 中的 context 名称（如果与集群名不同）
argocd cluster add prod-context --name prod-cluster

# 指定集群标签，便于后续按环境筛选
argocd cluster add prod-cluster --label env=production --label team=platform

# 跳过 TLS 验证（仅用于测试环境）
argocd cluster add dev-cluster --insecure

4.2.3 注册后的自动操作

执行 argocd cluster add 后，Argo CD 会自动完成以下步骤：

1. 在目标集群中创建一个 argocd-manager ServiceAccount 和对应的 ClusterRole（拥有集群管理权限）。
2. 获取该 ServiceAccount 的 。
3. 在 Argo CD 所在集群创建 Cluster Secret，包含 和 API Server 地址。
4. 将集群信息写入 Argo CD 的 ConfigMap argocd-cm 中的 clusters 字段。

4.3 使用 Argo CD UI 注册集群

UI 方式适合手动操作、临时添加或可视化查看集群状态。操作路径为：Settings > Clusters > Connect Cluster。

4.3.1 操作步骤

1. 登录 Argo CD Web UI，点击左侧导航栏的 Settings。
2. 在 Settings 页面选择 Clusters 标签页。
3. 点击右上角的 Connect Cluster 按钮。
4. 在弹出的对话框中，填写以下信息：
   • Name：集群在 Argo CD 中的显示名称。
   • Server URL：目标集群的 API Server 地址。
   • Config：粘贴 kubeconfig 文件内容，或手动填写 Bearer / 证书。
   • Labels：可选，添加键值对标签。
5. 点击 Connect 完成注册。

4.4 Cluster Secret 深度解析

每个注册的集群都会在 argocd 命名空间下生成一个对应的 Secret。理解其结构对于排障和自动化管理至关重要。

4.4.1 Secret 数据结构

apiVersion: v1
kind: Secret
metadata:
  name: cluster-prod-cluster-abc123
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: cluster
  annotations:
    managed-by: argocd.argoproj.io
type: Opaque
data:
  name: cHJvZC1jbHVzdGVy        # base64 编码的集群名称
  server: aHR0cHM6Ly9hcGkuLi4=   # base64 编码的 API Server URL
  config: ewogICJ0b2tlbiI6ICJleU... # base64 编码的 JSON 配置（包含 、证书等）
  labels: eyJlbnYiOiAicHJvZCJ9    # base64 编码的标签 JSON

4.4.2 config 字段详解

config 字段是一个 JSON 字符串，其内部结构如下：

{
  "bearerToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ii...",
  "tlsClientConfig": {
    "insecure": false,
    "caData": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t..."
  }
}

除了 bearerToken，还支持 username/password、awsAuthConfig（EKS）、execProviderConfig（GKE、AKS 等云厂商插件）等多种认证方式。

4.5 集群的增删改查操作

Argo CD 提供了完整的集群生命周期管理能力，支持通过 CLI、UI 和声明式 YAML 三种方式进行操作。

4.5.1 查询集群列表

# CLI 方式：列出所有集群
argocd cluster list

# 输出示例：
# SERVER                          NAME            STATUS  MESSAGE
# https://api.prod.example.com    prod-cluster    Successful
# https://api.staging.example.com staging-cluster Successful

# 查看集群详细信息
argocd cluster get prod-cluster

在 UI 中，Settings > Clusters 页面会以表格形式展示所有集群，包含名称、Server URL、状态、标签等信息。状态列显示 Successful 表示连接正常，Failed 表示连接异常。

4.5.2 更新集群配置

更新集群通常用于修改标签、更换 或更新证书。

# CLI 方式：更新集群标签
argocd cluster update prod-cluster --label env=prod --label region=us-east-1

# CLI 方式：更新集群的 kubeconfig（重新认证）
argocd cluster update prod-cluster --kubeconfig /path/to/new-kubeconfig

# 声明式方式：直接编辑 Cluster Secret
kubectl edit secret cluster-prod-cluster-abc123 -n argocd

4.5.3 删除集群

# CLI 方式：删除集群
argocd cluster rm prod-cluster

# 声明式方式：删除对应的 Cluster Secret
kubectl delete secret cluster-prod-cluster-abc123 -n argocd

删除集群时，Argo CD 会同时清理目标集群中的 argocd-manager ServiceAccount 和 ClusterRole（如果是由 Argo CD 自动创建的）。如果集群已不可达，删除操作会跳过清理步骤，仅移除 Argo CD 侧的记录。

4.5.4 操作对比总结

4.6 多集群注册架构图

下图展示了 Argo CD 控制平面与多个目标集群之间的注册关系，以及 Cluster Secret 在其中的核心作用。

4.7 声明式集群管理：GitOps 方式

在 GitOps 实践中，集群注册本身也应纳入版本控制。你可以将 Cluster Secret 的 YAML 文件存储在 Git 仓库中，通过 Argo CD Application 实现“集群注册的 GitOps”。

4.7.1 声明式 Cluster Secret 示例

apiVersion: v1
kind: Secret
metadata:
  name: cluster-prod-cluster
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: cluster
    env: production
    team: platform
type: Opaque
stringData:
  name: prod-cluster
  server: https://api.prod.example.com
  config: |
    {
      "bearerToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ii...",
      "tlsClientConfig": {
        "insecure": false,
        "caData": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t..."
      }
    }
  labels: |
    {"env": "production", "team": "platform"}

4.7.2 使用 ApplicationSet 自动注册集群

结合 ApplicationSet 的 Cluster Generator，可以实现“集群注册后自动创建应用”的自动化流水线：

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: guestbook-appset
spec:
  generators:
  - clusters:
      selector:
        matchLabels:
          env: production
  template:
    metadata:
      name: '{{name}}-guestbook'
    spec:
      project: default
      source:
        repoURL: https://git.example.com/applications.git
        targetRevision: HEAD
        path: 'guestbook/{{name}}'
      destination:
        server: '{{server}}'
        namespace: guestbook

当一个新的生产集群注册到 Argo CD 后，ApplicationSet 会自动检测到集群列表变化，并立即为该集群创建对应的 Application，实现“集群即代码”的 GitOps 闭环。

4.8 常见问题与排障