📚 课程目录第3章多集群管理基础

3. 多集群管理基础：Argo CD 添加集群的方式（kubeconfig / Service Account）、集群标签与选择器

在多集群部署场景中，Argo CD 作为控制平面，需要与多个目标 Kubernetes 集群建立信任连接。本章节将深入剖析两种主流的集群添加方式——kubeconfig 与 Service Account，并讲解如何通过集群标签与选择器实现精细化的多集群资源调度。

3.1 添加集群的两种核心方式

Argo CD 支持通过 argocd cluster add 命令或直接在 ConfigMap 中声明集群信息。底层认证机制分为两种：

对比维度	kubeconfig 方式	Service Account 方式
认证主体	本地 kubeconfig 中的用户凭证（证书/）	目标集群中创建的 Service Account 及其 Secret
权限范围	继承 kubeconfig 上下文中的 RBAC 权限	由 Service Account 绑定的 Role/ClusterRole 决定
生命周期	依赖本地文件，凭证轮转需手动更新	独立于客户端，适合 CI/CD 自动化
适用场景	开发调试、临时接入、管理员操作	生产环境、GitOps 流水线、多租户隔离
安全风险	kubeconfig 文件泄露风险较高	可绑定最小权限，可定期轮转

3.1.1 使用 kubeconfig 添加集群

这是最直接的接入方式，Argo CD 会读取本地 kubeconfig 中的 current-context 或指定上下文来连接目标集群。

# 添加当前 kubeconfig 上下文中的集群
argocd cluster add $(kubectl config current-context)

# 指定上下文名称添加
argocd cluster add my-production-cluster

# 查看已添加的集群列表
argocd cluster list

⚠️ 安全警告：kubeconfig 方式会将凭证明文存储在 Argo CD 的 Secret 中。建议仅在非生产环境或临时调试时使用，生产环境优先采用 Service Account 方式。

3.1.2 使用 Service Account 添加集群

Argo CD 提供了自动化脚本，可在目标集群中创建专用的 Service Account 并绑定必要的 RBAC 权限。

# 在目标集群上执行（需要目标集群的 kubectl 访问权限）
argocd cluster add --service-account=argocd-manager \
  --namespace=argocd \
  --system-namespace=kube-system \
  my-target-cluster

该命令会自动完成以下操作：

在目标集群的 kube-system 命名空间创建 argocd-manager Service Account
创建 cluster-admin 级别的 ClusterRoleBinding（默认权限较高，建议后续收紧）
将 Service Account 的 Secret 导入 Argo CD 的集群 Secret 中

💡 最佳实践：生产环境中，建议手动创建 Service Account 并绑定最小权限的 ClusterRole，然后通过 argocd cluster add --kubeconfig 配合手动生成的 kubeconfig 文件（使用该 SA 的）来添加集群，实现权限的精细控制。

3.2 集群标签与选择器

当管理的集群数量超过 5 个时，手动为每个 Application 指定目标集群将变得难以维护。Argo CD 通过 集群标签（Cluster Labels） 和 选择器（Selectors） 实现了声明式的集群分组与动态调度。

3.2.1 为集群添加标签

集群标签以 Annotation 的形式存储在 Argo CD 的集群 Secret 中：

# 通过命令行添加标签
argocd cluster add my-cluster \
  --label env=production \
  --label region=us-east-1 \
  --label team=platform

# 或直接编辑集群 Secret
kubectl edit secret my-cluster-secret -n argocd

# Secret 中的 labels 字段示例
metadata:
  labels:
    argocd.argoproj.io/secret-type: cluster
data:
  labels: |
    {
      "env": "production",
      "region": "us-east-1",
      "team": "platform"
    }

3.2.2 在 Application 中使用选择器

在 Application 的 spec 中，通过 destination 字段的 selector 替代固定的 server URL，实现动态集群匹配：

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app-production
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/example/gitops-repo.git
    targetRevision: HEAD
    path: manifests/production
  destination:
    # 使用选择器替代 server URL
    selector:
      matchLabels:
        env: production
        region: us-east-1
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

  📌 关键行为：当使用 selector 时，Argo CD 会实时匹配所有满足标签条件的集群。如果新增一个带有 env: production 和 region: us-east-1 标签的集群，该 Application 会自动将资源同步到新集群，无需修改 Application 配置。

3.3 多集群架构与标签策略

下图展示了 Argo CD 控制平面与多个目标集群之间的连接关系，以及标签如何驱动 Application 的调度决策：

3.4 标签选择器的进阶用法

除了简单的 matchLabels 精确匹配，Argo CD 还支持 matchExpressions 进行集合运算：

destination:
  selector:
    matchExpressions:
      - key: env
        operator: In
        values:
          - production
          - staging
      - key: region
        operator: NotIn
        values:
          - cn-north-1  # 排除特定区域

💡 运维技巧：利用标签选择器可以实现“金丝雀发布”场景——先为少数集群打上 canary: enabled 标签，Application 选择器匹配该标签，验证通过后再将标签扩展到更多集群。

3.5 集群健康状态与标签联动

Argo CD 会持续监控已添加集群的健康状态。当集群不可达时，可以通过标签选择器实现自动故障转移：

集群状态	标签建议	选择器行为
健康	`status: active`	正常匹配，Application 持续同步
不可达	`status: unreachable`	选择器排除该标签，Application 暂停同步
维护中	`maintenance: true`	选择器排除，避免同步干扰

# 标记集群为维护模式
argocd cluster update my-cluster \
  --label status=maintenance

# Application 选择器自动排除维护中的集群
destination:
  selector:
    matchExpressions:
      - key: status
        operator: NotIn
        values:
          - maintenance
          - unreachable

通过这种标签驱动的动态调度机制，Argo CD 能够在不修改 Application 定义的前提下，灵活应对集群扩缩容、故障转移和运维窗口等场景，为多集群版本漂移检测与修复奠定坚实的集群管理基础。