4. Argo CD 多租户配置：Projects、RBAC、多集群管理（Cluster Secrets）的配置与常见错误

多租户是 Argo CD 在生产环境中落地的核心能力。本章聚焦于 Projects（项目）、RBAC（基于角色的访问控制） 以及 多集群管理（Cluster Secrets） 的配置方法，并剖析高频故障场景。理解这三者的协同关系，是构建安全、隔离、可运维的多租户 GitOps 平台的基础。

4.1 Argo CD Projects：租户隔离的边界

Project 是 Argo CD 中逻辑隔离的基本单元。它定义了应用可以部署到哪些目标集群/命名空间、允许从哪些 Git 仓库同步、以及可以访问哪些资源类型。

4.1.1 Project 核心配置字段

4.1.2 Project 配置示例

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: tenant-alpha
  namespace: argocd
spec:
  sourceRepos:
  - 'https://gitlab.example.com/tenant-alpha/*'
  destinations:
  - namespace: 'tenant-alpha-*'
    serverURL: 'https://kubernetes.default.svc'
  - namespace: 'tenant-alpha-*'
    serverURL: 'https://cluster-prod.example.com:6443'
  clusterResourceWhitelist:
  - group: ''
    kind: 'Namespace'
  namespaceResourceBlacklist:
  - group: 'rbac.authorization.k8s.io'
    kind: 'ClusterRoleBinding'
  roles:
  - name: project-admin
    policies:
    - p, proj:tenant-alpha:project-admin, applications, *, tenant-alpha/*, allow
    groups:
    - tenant-alpha-admins

4.2 RBAC：精细化权限控制

Argo CD 的 RBAC 基于 Policy（策略） 文件实现，通常存储在 argocd-rbac-cm ConfigMap 中。策略遵循 p, subject, resource, action, object, effect 的 Casbin 格式。

4.2.1 RBAC 策略模型

# 格式：p, 主体, 资源, 操作, 对象, 效果
p, role:admin, applications, *, */*, allow
p, role:developer, applications, sync, tenant-alpha/*, allow
p, role:viewer, applications, get, */*, allow

# 组绑定
g, alice, role:admin
g, bob, role:developer
g, team-alpha, role:developer

4.2.2 RBAC 常见故障模式

• 策略未生效： 修改 argocd-rbac-cm 后未执行 argocd admin settings rbac 重新加载，或 Argo CD 服务端未重启。
• 对象范围错误： 使用 */* 表示所有 Project 下的所有应用，但误写成 */ 导致匹配失败。
• Project 角色冲突： 用户在 Project 级别有 admin 角色，但在全局 RBAC 中被限制为 viewer，导致权限异常。
• SSO 组映射缺失： 配置了 OIDC/LDAP 但未在 argocd-cm 中正确映射组到 RBAC 角色。

4.3 多集群管理：Cluster Secrets 的配置与故障

Argo CD 通过 Cluster Secrets 管理目标集群的连接信息。每个集群对应一个 Kubernetes Secret，存储在 Argo CD 所在的集群（通常是 argocd 命名空间）。

4.3.1 Cluster Secret 结构

apiVersion: v1
kind: Secret
metadata:
  name: cluster-prod
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: cluster
type: Opaque
stringData:
  name: "production-cluster"
  server: "https://api.prod.example.com:6443"
  config: |
    {
      "bearerToken": "<service-account->",
      "tlsClientConfig": {
        "insecure": false,
        "caData": "<base64-ca-cert>"
      }
    }
  namespaces: "default,production,monitoring"
  project: "tenant-alpha"

4.3.2 多集群连接故障排查流程

1. 验证集群状态： argocd cluster list 查看集群连接状态，Successful 表示正常，Failed 表示连接失败。
2. 检查网络连通性： 从 Argo CD 服务端 Pod 直接 curl -k https://<server>/version 测试 API Server 可达性。
3. 验证认证凭据： 确认 Service Account 未过期，且具有必要的 RBAC 权限（至少 get、list、watch 资源）。
4. 检查 TLS 配置： 自签名证书需要正确配置 caData，或设置 insecure: true（不推荐生产）。
5. 确认命名空间白名单： 应用部署的目标命名空间必须在 Cluster Secret 的 namespaces 列表中，或在 Project 的 destinations 中允许。

4.4 多租户配置全景图

下图展示了 Project、RBAC 和 Cluster Secret 在多租户场景下的协同关系：

4.5 多租户故障排查清单

4.6 多集群注册与 Cluster Secret 生成

除了手动创建 Secret，Argo CD 提供了 argocd cluster add 命令自动生成 Cluster Secret。该命令会使用当前 kubectl 上下文中的 Service Account 或 kubeconfig 文件。

# 使用 kubeconfig 添加集群
argocd cluster add --kubeconfig /path/to/kubeconfig --name prod-cluster

# 使用 Service Account 令牌添加集群
argocd cluster add --service-account argocd-manager --name dev-cluster

# 指定 Project 限制
argocd cluster add --project tenant-alpha --name tenant-alpha-cluster

4.7 多租户配置的常见错误模式总结

• Project 与 Cluster Secret 的绑定缺失： Cluster Secret 未设置 project 字段，导致所有 Project 都能使用该集群，破坏了租户隔离。
• RBAC 策略过于宽泛： 使用 p, role:developer, applications, *, */*, allow 允许开发者操作所有 Project 的应用。
• 命名空间白名单不一致： Project 的 destinations 允许了命名空间，但 Cluster Secret 的 namespaces 未包含，导致应用部署失败。
• 集群凭证未轮换： Service Account 长期未更新，导致集群连接突然中断。
• Project 角色与全局 RBAC 冲突： 用户在 Project 级别有 admin 权限，但全局 RBAC 限制了其对 projects 资源的 update 操作，导致无法修改 Project 配置。