使用 Tekton 自动创建 GitLab Tenant Group 和 Connector

当新的 tenant 被接入 Alauda Container Platform 时,operator 通常需要重复执行相同的 GitLab 配置步骤:创建 tenant group(以及每个团队对应的子 group),生成 Group Access Token, 然后对 tenant 的 gitlab Connector 以及匹配的 auth Secret 执行 kubectl apply。本指南将这一流程收敛为单个 Tekton TaskRun, 并展示如何按计划定期运行同一个 TaskRun,以便在 tenant token 过期前进行轮换。

其实现机制是 gitlab-connector-automatic-creation Task。 初次开通时运行一次,之后在需要轮换时再次运行 (或者——当影响身份的输入发生变化时——重新创建)tenant GAT。

概念页面 GitLab CLI 配置与自动创建模式 介绍了底层模型(Pattern A 与 Pattern B、三路径 GAT 生命周期, 以及 admin 凭证如何保留在 CSI mount 中)。本页面重点说明 operator 工作流。

解决的问题

  • Tenant 接入。 一个 TaskRun 即可创建 tenant GitLab group、任意 可选子 group、tenant GAT,以及集群上的 tenant gitlab Connector 和 Secret。
  • Token 轮换。 按计划重新运行 TaskRun 会原地轮换 tenant GAT; Secret 会以原子方式更新;正在运行的 pipeline 会在下次启动时重新读取 Secret。
  • 自愈。 如果漏掉了某个轮换周期,导致 GAT 在下次运行前已过期, Task 会检测到过期 token,并自动切换到重新创建流程。无需人工干预。
  • 身份变更后重新创建。 当重新运行时更改 scopes、accessLevel 或 subgroups[] 集合,会触发对 GAT 的受控删除并重新创建。

开始之前

请确保环境满足以下要求:

  • 已安装 Tekton Pipelines。
  • 已安装 Connectors system 和 GitLab Connector ConnectorClass。
  • 已将 gitlab-connector-automatic-creation Task 安装到你将运行 TaskRun 的 namespace 中。请从 cmd/kodata/connectors-gitlab-tektoncd/1.0.0/install.yaml 源清单(或已发布的 catalog 形态)应用它——关于 REGISTRY + TARGET_NS + envsubst | kubectl apply 的命令, 请参见 Task reference 的 Installation 小节。 connectors-operator 只会安装框架部分(CRD、RBAC、ConnectorClass、 ResourceInterface)——Task 本身需要按 Tekton 约定由用户自行应用。
  • catalog 中的 glab 和 kubectl 工具镜像可以从你的内部 registry 访问。Task 使用 kube-public 中现有的 catalog.tekton.dev/tool-image-glab 和 catalog.tekton.dev/tool-image-kubectl ConfigMap。

安全建议:

  • 将 admin GitLab Connector 保留在一个私有的管理 namespace 中 (例如 connectors-management)。
  • 限制谁可以触发 TaskRun —— 该操作会生成(并轮换)Group Access Token。
  • 按 pattern 选择最小权限足迹的 admin 身份(参见下面的 选择部署模式)。

选择部署模式

Task 本身不会按 pattern 分支——两种模式都会走同一段代码路径。 请根据你的 GitLab tenancy 形态选择:

选择适用场景
Pattern A — 顶层 tenant group,具有 can_create_group 的 admin user PAT全新自建 GitLab;每个 tenant 一个顶层 group;你希望 tenant 之间完全隔离。
Pattern B — umbrella 的子 group,在 umbrella 上具有 Owner 的 admin user PAT你已经有一个用于汇总 tenant 的 umbrella group(SaaS GitLab 以及拥有共享 admin 工具的组织中很常见)。影响范围更小。

为什么使用 user PAT,而不是 umbrella 上的 Group Access Token(GAT)? GAT 属于 group bot user,而 GitLab 会将其限制在签发的 group 内:它无法在新创建的子 group 上生成 GAT(HTTP 400 — "User does not have permission to create group access token"), 且 group bot 不能作为其他 group 的直接成员。因此,Task 要求使用 regular user 身份——即一个你授予 umbrella Owner 权限的专用自动化用户——来为子 tenant 生成 per-tenant GAT。请参见下面的 Pattern B prerequisites。

完整对比请参见 Pattern A vs Pattern B。

前置条件 — Pattern A(顶层 + can_create_group 用户)

  1. 创建或选择一个专用 GitLab 用户(不要使用真实个人身份)。 在自建 GitLab 上,请让 GitLab 实例管理员将该用户的 can_create_group 标志设置为 true。在 GitLab.com 上,任何用户都可以创建顶层 group, 因此无需设置该标志。

  2. 限制该用户的所有权范围。 该用户会成为其创建的每个 group 的 owner, 一旦被攻破,其影响范围就是这些 group 的并集。请明确约定类似 “该用户不得拥有自动创建的 tenant 集合之外的任何对象”的规则,并按计划审计 它(见下面 runbook 中的 Pattern-A user ownership audit)。

  3. 为该用户生成一个 PAT,至少包含 api scope。将该 PAT 作为 Kubernetes Secret 存储在 management namespace 中:

    apiVersion: v1
    kind: Secret
    metadata:
      name: gitlab-admin-secret
      namespace: connectors-management
    type: connectors.cpaas.io/gitlab-pat-auth
    stringData:
      username: gitlab-admin-bot
      token: glpat-xxxxxxxxxxxxxxxxxxxx
  4. 创建指向该 Secret 的 admin Connector:

    apiVersion: connectors.alauda.io/v1alpha1
    kind: Connector
    metadata:
      name: gitlab-admin
      namespace: connectors-management
    spec:
      connectorClassName: gitlab
      address: https://gitlab.example.com
      auth:
        name: patAuth
        secretRef:
          name: gitlab-admin-secret

前置条件 — Pattern B(Umbrella 的子 group + Admin User PAT)

  1. 创建 umbrella group(例如 umbrella),如果它尚不存在于 GitLab 中。 这是一次性操作——从这里开始,所有 tenant 都将作为其下的子 group 存在。

  2. 创建或选择一个专用 GitLab 用户作为 umbrella admin。请将其视为 Pattern A 自动化用户:非人工 bot 账号,而不是某个真实个人的身份。 该用户不需要 can_create_group(它创建的是 subgroup,不是顶层 group)。

  3. 将该用户添加为 umbrella 的 Owner,这样它既可以在 umbrella 下创建 subgroup,也可以在这些 subgroup 上生成 GAT(GAT 创建接口要求直接的 Owner 成员关系,而 group access token 无法满足这一点——这也是 Pattern B 需要使用 user 身份的原因)。

  4. 为该用户生成一个 PAT,至少包含 api scope。将该 PAT 作为 Kubernetes Secret 存储在 management namespace 中:

    apiVersion: v1
    kind: Secret
    metadata:
      name: gitlab-umbrella-secret
      namespace: connectors-management
    type: connectors.cpaas.io/gitlab-pat-auth
    stringData:
      username: gitlab-umbrella-admin
      token: glpat-xxxxxxxxxxxxxxxxxxxx
  5. 创建指向 umbrella Secret 的 admin Connector:

    apiVersion: connectors.alauda.io/v1alpha1
    kind: Connector
    metadata:
      name: gitlab-umbrella
      namespace: connectors-management
    spec:
      connectorClassName: gitlab
      address: https://gitlab.example.com
      auth:
        name: patAuth
        secretRef:
          name: gitlab-umbrella-secret

可选:用于跨集群 apply 的 Kubernetes Connector

当 management namespace 和 tenant Connector 位于不同 cluster 上时,Task 支持可选的 kubeconfig workspace。可以从 kubernetes class 的 Connector 中挂载它:

- name: kubeconfig
  csi:
    driver: connectors-csi
    readOnly: true
    volumeAttributes:
      connector.name: target-cluster
      configuration.names: kubeconfig

建议: 即使在同一个 cluster 上,也从 kubernetes class 的 Connector 挂载 kubeconfig workspace。这样可以保持 Task 的有效身份显式可见 (即 Connector 所提供的、其 token 所对应的 SA),并在同集群与跨集群 场景中保持一致。关于 Connector 的配置,请参见 在 Tekton Task 中使用 Kubernetes Connector。

当 kubeconfig workspace 未绑定时,Task 会回退到 TaskRun 的集群内 ServiceAccount——这在同集群场景下可行,但平台团队通常更偏好 kubernetes-Connector 路径,这样 provisioning 身份会保留在 Connector 上,而不是 TaskRun 的 SA 上。

ServiceAccount 权限

该 Task 面向平台团队,他们代表多个应用团队创建 GitLab group 和 gitlab Connector。所需权限集较小,并且对各种 Connector 类型 (Harbor、GitLab 等)通用,最适合表达为按 tenant namespace 绑定的 cluster-scoped role。

provisioning ServiceAccount 需要在每个 tenant connector namespace 中对两类资源拥有写权限(connector 参数中的 <conn_ns> 部分——例如 connectors-management/acme-corp → connectors-management):

API groupResourceVerbs原因
""(core)secretsget, patch, create应用包含 GAT 的 Secret(server-side apply 使用 PATCH;首次运行需要 CREATE)
connectors.alauda.ioconnectorsget, patch, create应用指向该 Secret 的 tenant Connector CR

Task 还会调用 kubectl auth can-i create secrets 作为预检; 这会使用 SelfSubjectAccessReview,任何已认证用户都可以在不显式配置 RBAC 的情况下调用。

这些权限属于谁?

  • 推荐路径——挂载在 kubeconfig workspace 上的 kubernetes Connector 所提供的 kubeconfig 中嵌入的 token 对应的 SA。
  • 同集群回退——TaskRun 的 serviceAccountName。

无论哪种方式,权限形态都相同。对 Harbor 自动创建 Task 也使用相同的 SA 以及下面相同的 ClusterRole + RoleBinding 组合——这些规则并不特定于 GitLab。

一个专用的、最小权限的 ClusterRole

operator 提供了一个较宽泛的 connectors-connector-editor-role ClusterRole,它授予完整的 edit verb 集合 ({create,delete,get,list,patch,update,watch})。 Task 并不需要这么大的权限范围。 它只会对两类对象执行 kubectl apply --server-side——因此支持的做法是使用单独的 ClusterRole,并且只包含 Task 实际使用的三个 verb,名称也应清楚体现 仅用于 apply 的意图:

ClusterRoleRulesVerbs
connectors-tenant-task-writercore/secrets + connectors.alauda.io/connectorsget, patch, create

命名约定:tenant- 前缀表示绑定范围是 tenant namespace(而不是集群范围); -writer(而非 -editor)表示权限仅限于狭窄的 apply 操作;task- 则明确表明该角色用于 Tekton-Task 驱动的 provisioning。它与 cmd/kodata/*/install.yaml 中发布的任何内容都不会冲突。

平台团队模式:cluster-scoped role,按 tenant 绑定

将 provisioning SA 只定义一次,放在平台 namespace 中,然后通过按 namespace 的 RoleBinding 将 ClusterRole 绑定到每个 tenant namespace。这样可以让 SA 的作用范围仅限于你实际希望进行 Connector provisioning 的那些 namespace (不会出现集群范围的 secret 或 connector 写权限):

apiVersion: v1
kind: ServiceAccount
metadata:
  name: connectors-task-runner
  namespace: connectors-system
---
# Reusable rule template — least-privilege apply set for the Task.
# Deliberately narrower than the shipped connectors-connector-editor-role
# (no delete/list/update/watch) since the Task only ever applies.
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: connectors-tenant-task-writer
rules:
  - apiGroups: [""]
    resources: ["secrets"]
    verbs: ["get", "patch", "create"]
  - apiGroups: ["connectors.alauda.io"]
    resources: ["connectors"]
    verbs: ["get", "patch", "create"]
---
# Per-tenant binding — repeat in each tenant connector namespace the SA
# is allowed to provision into.
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: connectors-task-runner
  namespace: connectors-management   # ← tenant namespace
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: connectors-tenant-task-writer
subjects:
  - kind: ServiceAccount
    name: connectors-task-runner
    namespace: connectors-system

以后如果需要为新的 tenant namespace 接入,只需由平台团队应用对应的 RoleBinding(重新绑定到新 namespace)即可——无需变更 SA 或 ClusterRole。

如果你需要集群范围的访问能力(例如信任该 SA 在每个 namespace 中都可使用), 可以将按 namespace 的 RoleBinding 替换为 ClusterRoleBinding。 这会用更少的 tenant 级清单换来更大的作用范围;请审慎选择。

将 SA 接入 TaskRun

对于推荐的 kubernetes-Connector 路径,TaskRun 不会直接引用该 SA—— 而是通过 kubernetes Connector 进行绑定,这样 kubeconfig 中嵌入的就是 该 SA 的 token。对于同集群回退,则在 TaskRun 上设置它:

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  generateName: gitlab-pattern-a-top-level-
  namespace: connectors-management
spec:
  serviceAccountName: connectors-task-runner   # same-cluster fallback
  taskRef:
    name: gitlab-connector-automatic-creation
  # ... params + workspaces
TIP

未来的 connectors-operator 版本很可能会开箱即用地提供上面的 connectors-tenant-task-writer ClusterRole——这与 connectors-connector-editor-role / connectors-connector-viewer-role 已经使用的 role 形态约定保持一致。在此之前,它由平台团队负责维护。

分步操作 — Pattern A:全新创建

这个接入示例会创建一个顶层 GitLab group acme-corp,并包含两个按团队划分的 subgroup,为 acme-corp 生成一个 30 天过期的 owner GAT,并在 connectors-management/acme-corp 中创建 gitlab Connector + Secret。

# Pattern A -- top-level tenant group, fresh creation.
apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  generateName: gitlab-pattern-a-top-level-
  namespace: connectors-management
spec:
  taskRef:
    name: gitlab-connector-automatic-creation
  params:
    - name: connector
      value: connectors-management/acme-corp
    - name: tenantGroup
      value: acme-corp
    - name: subgroups
      value:
        - backend
        - frontend
    - name: accessLevel
      value: owner
    - name: scopes
      value:
        - api
    - name: tokenDuration
      value: "30"
  workspaces:
    - name: gitlabconfig
      csi:
        driver: connectors-csi
        readOnly: true
        volumeAttributes:
          connector.name: gitlab-admin
          configuration.names: gitlabconfig
    - name: kubeconfig
      csi:
        driver: connectors-csi
        readOnly: true
        volumeAttributes:
          connector.name: target-cluster
          configuration.names: kubeconfig

应用并等待完成:

kubectl apply -f pattern-a-top-level.yaml
kubectl get taskrun -n connectors-management --watch

TaskRun 成功后:

  • GitLab 中存在顶层 group acme-corp 以及 subgroup acme-corp/backend、acme-corp/frontend。
  • 名为 connector-connectors-management-acme-corp/<identity> 的 GAT 存在于 acme-corp 下,scopes 为 [api],access level 为 owner, 过期时间为今天 + 30 天。
  • 集群中包含 Secret/acme-corp(类型 connectors.cpaas.io/gitlab-pat-auth)以及指向它的 Connector/acme-corp, 两者都位于 connectors-management。

分步操作 — Pattern B:全新创建

同一个 tenant,不同的部署模式:umbrella umbrella 预先存在,而 admin Connector 携带的是一个 user PAT,且该 PAT 对应的用户在 umbrella 上具有 Owner。 (Group Access Token 无法在 subgroup 上为每个 tenant 生成 GAT——请参见 模式选择器 中的说明。)

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  generateName: gitlab-pattern-b-subgroup-
  namespace: connectors-management
spec:
  taskRef:
    name: gitlab-connector-automatic-creation
  params:
    - name: connector
      value: connectors-management/acme-corp
    - name: tenantGroup
      value: umbrella/acme-corp
    - name: subgroups
      value: []
    - name: accessLevel
      value: owner
    - name: scopes
      value:
        - api
    - name: tokenDuration
      value: "30"
  workspaces:
    - name: gitlabconfig
      csi:
        driver: connectors-csi
        readOnly: true
        volumeAttributes:
          connector.name: gitlab-umbrella
          configuration.names: gitlabconfig
    - name: kubeconfig
      csi:
        driver: connectors-csi
        readOnly: true
        volumeAttributes:
          connector.name: target-cluster
          configuration.names: kubeconfig

结果:集群输出与 Pattern A 完全一致;在 GitLab 侧,新 group 位于 umbrella/acme-corp(umbrella 的子 group)下,而不是顶层;GAT 则签发在 umbrella/acme-corp(而不是 umbrella)上。

分步操作 — 原地轮换

在所有参数保持不变的情况下重新运行 TaskRun,会原地轮换现有 GAT。 Task 会通过名称前缀 (connector-<connector-namespace>-<connector-name>)定位现有 GAT, 确认身份匹配,然后调用 POST /groups/:id/access_tokens/:token_id/rotate。GitLab 会以原子方式使旧 token 失效,并返回一个新的 token,其 expires_at 会按 tokenDuration 天数向前推进; tenant Secret 会原地更新。

该 TaskRun 在结构上与 Pattern A 的创建 TaskRun 故意保持一致。 因此它也适合 Cron:tokenDuration 以天为单位,所以每次轮换都会将 expires_at 刷新为今天 + N 天。

用于定期轮换的 CronJob 模式

将 rotate TaskRun 包装进 CronJob,使其按计划触发:

apiVersion: batch/v1
kind: CronJob
metadata:
  name: rotate-acme-corp-gat
  namespace: connectors-management
spec:
  # Rotate weekly. Pick a window when tenant pipelines are likely idle
  # (see "Rotation-during-use race" in the runbook below).
  schedule: "0 2 * * 0"
  concurrencyPolicy: Forbid
  successfulJobsHistoryLimit: 3
  failedJobsHistoryLimit: 3
  jobTemplate:
    spec:
      backoffLimit: 1
      template:
        spec:
          restartPolicy: OnFailure
          serviceAccountName: gitlab-connector-rotator
          containers:
            - name: rotate
              image: bitnami/kubectl:1.30
              command: [/bin/sh, -c]
              args:
                - kubectl create -f /etc/rotate/rotate.yaml
              volumeMounts:
                - name: rotate-template
                  mountPath: /etc/rotate
          volumes:
            - name: rotate-template
              configMap:
                name: rotate-acme-corp-gat-template

将 rotate TaskRun 清单存储在 rotate-acme-corp-gat-template ConfigMap 中; CronJob 会在每个周期通过 kubectl create 生成一个新的 TaskRun。建议将其与 过期 token 告警配合使用(见 runbook 中的 Token 已过期)。

提示。 请将 CronJob 调度设置为连续两次运行之间的间隔短于 tokenDuration 减去安全余量。对于 tokenDuration=30 天,建议每周执行一次。 对于 tokenDuration=7 天,建议每天执行一次。

分步操作 — 身份变更后的重新创建

当你更改 scopes、accessLevel 或 subgroups[] 集合时,Task 会检测到身份漂移, 并重新创建 tenant GAT,而不是对其进行轮换。示例:将 scope 从 [api] 变更为 [api, read_registry]:

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  generateName: gitlab-recreate-
  namespace: connectors-management
spec:
  taskRef:
    name: gitlab-connector-automatic-creation
  params:
    - name: connector
      value: connectors-management/acme-corp
    - name: tenantGroup
      value: acme-corp
    - name: subgroups
      value:
        - backend
        - frontend
    - name: accessLevel
      value: owner
    - name: scopes
      value:
        - api
        - read_registry
    - name: tokenDuration
      value: "30"
  workspaces:
    - name: gitlabconfig
      csi:
        driver: connectors-csi
        readOnly: true
        volumeAttributes:
          connector.name: gitlab-admin
          configuration.names: gitlabconfig

其行为顺序如下:

  • Task 定位现有 GAT。
  • 现有 GAT 的身份不再与目标身份匹配。
  • Task 撤销它(DELETE /groups/:id/access_tokens/:token_id), 并以请求的身份生成新的 GAT。
  • tenant Secret 使用新的 token 更新。
  • Secret 上会设置注解 connectors.cpaas.io/gat-recreated-at。

注意:只有在扩展时,subgroup 集合才不属于影响身份的变更—— 向 subgroups 添加 team-c 会原地轮换 GAT,并在 <tenantGroup>/team-c 下创建缺失的 subgroup。移除或更改规范的 subgroup 集合 会影响身份,并触发重新创建。

分步操作 — 过期后自动转入重建(自愈)

如果错过了某个轮换周期,导致 GAT 的 expires_at 在下次运行前已经过期,Task 会自我修复。恢复用的 TaskRun 与 rotate TaskRun 在结构上完全相同。在 GitLab 侧:

  • ensure-gat(Task 的第 3 步)会列出 acme-corp 下现有的 GAT,并找到带有 connector-<ns>-<name> 前缀的那个。
  • 它会检测到 expires_at < now,并记录 WARN: existing GAT <id> is expired; falling through to recreate。
  • 它会撤销过期的 GAT(尽力而为;GitLab 也会回收已过期 token), 然后生成一个新的。
  • tenant Secret 会被重写为新的 token 值。

TaskRun 会报告 Succeeded。立即恢复不需要 operator 采取任何操作—— 但你仍应调查为什么轮换 cron 会漏跑(见下面 runbook 中的 Token 已过期)。

验证结果

检查 TaskRun:

kubectl get taskrun -n connectors-management
kubectl describe taskrun <name> -n connectors-management

检查 tenant Connector 和 Secret:

kubectl get connector acme-corp -n connectors-management
kubectl get secret acme-corp -n connectors-management

检查 Secret 上的轮换/重建注解:

kubectl get secret acme-corp -n connectors-management -o jsonpath='{.metadata.annotations}'

使用 glab 对 GitLab 侧做一次 sanity check:

glab api groups/acme-corp/access_tokens?state=active

你应该能看到名为 connector-connectors-management-acme-corp/<identity> 的 GAT,其 scopes、 access_level 和 expires_at 都符合请求且指向未来。

运维 Runbook

每个场景都按以下结构组织:触发条件 → Task 的处理方式 → operator 操作 → 监控信号。

Token 已过期(错过轮换窗口)

触发条件。 operator 创建 tenant Connector 时设置了 tokenDuration=30,但下一次轮换 TaskRun 未能在 30 天内运行 (CronJob 被禁用、controller 暂停、周末值班遗漏等)。到第 31 天及之后, GitLab 已经使 GAT 过期。

Task 的处理方式。 重新运行时,ensure-gat 会从 GET /groups/<tenantGroup>/access_tokens 读取现有 GAT,并检测到 expires_at < now。它会记录 WARN: existing GAT <id> is expired; falling through to recreate, 并自动从 rotate 路径切换到 delete + recreate 路径。 否则 GitLab 的 rotate endpoint 会返回 400 invalid_grant(token 已过期);Task 不会调用它。

结果。 与正常重建后的状态相同:旧 GAT id 已消失(尽力删除;GitLab 也会回收过期 token),新的 GAT 在 tenantGroup 下签发,Secret 被重写, 并设置 Connector 注解 connectors.cpaas.io/gat-recreated-at。TaskRun 报告 Succeeded。不需要人工介入。

operator 操作。 对立即恢复无需操作。长期来看:调查为什么轮换 cron 漏跑,并将告警阈值收紧到过期窗口之前(例如,当 stale-token age 超过 tokenDuration - 7d 时发出告警)。

监控信号。 推荐的告警规则:

  • gat_age_seconds > tokenDuration_seconds - 604800(warn——过期前 7 天)。
  • gat_age_seconds > tokenDuration_seconds(page——已经过期;下次 TaskRun 会自愈, 但在此期间 tenant 正在使用过期凭证)。
  • taskrun_status == "Failed",针对轮换 CronJob 的 TaskRun(page)。

Token-refresh CronJob 被禁用或配置错误

触发条件。 有人禁用了 CronJob,或者调度静默停止触发 (Tekton Trigger 配置错误、controller 暂停等)。

Task 的处理方式。 不做任何事情——Task 只有在被调用时才会运行。 一旦到达过期时间,上面的“错过轮换”故障模式就会触发。

operator 操作。 重新启用 CronJob;确认下一次运行成功;回顾本应触发 的告警。

监控信号。 对轮换 CronJob 的 kube_cronjob_spec_suspend == 1 发出 page;如果在最近 2 × 调度间隔内轮换 CronJob 没有任何成功的 Job 运行, 也发出 page。

Tenant 下线回滚

触发条件。 tenant acme-corp 正在被停用;operator 希望干净地撤销 GitLab 访问权限。

Task 的处理方式。 超出范围——Task 只负责创建和轮换。推荐的手工步骤是:

# 1. Revoke the GAT (defensive — deleting the group below also revokes).
glab api groups/acme-corp/access_tokens \
  | jq '.[] | select(.name|startswith("connector-connectors-management-acme-corp/")) | .id' \
  | xargs -I {} glab api -X DELETE groups/acme-corp/access_tokens/{}

# 2. Remove the tenant group on GitLab.
#    Pattern A: the admin user owns the group; delete it directly.
#    Pattern B: the umbrella owner deletes the subgroup.
glab api -X DELETE groups/acme-corp

# 3. Delete the tenant Connector + Secret on the cluster.
kubectl delete connector acme-corp -n connectors-management
kubectl delete secret acme-corp -n connectors-management

# 4. Pattern A only: if no other tenants share the dedicated user,
#    consider revoking the admin PAT and deleting the user.

未来的“tenant 清理”Task 是一个候选后续项;当 tenant 需求显现后再作为延期工单处理。

Pattern A 用户所有权审计

触发条件。 定期合规检查(Pattern A 用户会累积其创建的每个 group 的所有权, 因此其影响范围会随时间增长)。

Task 的处理方式。 不做任何事情——只读审计。请按计划运行以下片段(或将其作为 后续工作的独立审计 Task):

glab api 'groups?owned=true&min_access_level=50'

operator 操作。 如果 owned-groups 列表中包含任何该用户不应拥有的对象, 则升级处理;否则无需操作。该审计用于可视化该用户残留的 blast-radius 风险。

监控信号。 无原生信号——请将审计输出接入 SIEM,或接入一个定期 CI 作业, 将其与预期的自动创建 tenant group 列表进行 diff。

全新创建时的 group-path 冲突

触发条件。 operator 选择了 tenantGroup=acme-corp,但 GitLab 中已经存在 acme-corp,且它属于其他人(不是 admin 身份)。

Task 的处理方式。 ensure-group 的 GET /groups/acme-corp 返回 200, 发现 admin 身份不在 owners 列表中,并以以下信息退出:

ERROR: tenantGroup 'acme-corp' already exists and admin identity is not an owner; rename or pick a different tenantGroup

任一侧都不会发生变更。

operator 操作。 选择一个不同的 tenantGroup (例如 acme-corp-prod,或者如果你有 umbrella,则使用 tenants/acme-corp), 或者与现有 group 的 owner 协调处理。

监控信号。 TaskRun Failed,且 step log 中包含明确的错误消息。 如果你希望快速感知,可以对该消息本身设置告警。

轮换过程中发生并发使用竞争

触发条件。 一个 rotate TaskRun 与一个长生命周期的 tenant pipeline 并发运行, 且两者读取同一个 tenant Secret/<connector-name>。运行中的 pipeline pod 在启动时读取了 旧 token 值;随后,rotate TaskRun 在执行过程中调用 POST /groups/:id/access_tokens/:token_id/rotate,原子性地使旧 token 失效;运行中的 pod 后续的 push 或 API 调用将以 401 失败。

Task 的处理方式。 Task 不会与 tenant pipeline 协调——轮换会按计划无条件执行。

operator 操作。 有两种选择:

  1. 在 tenant pipeline 空闲时安排轮换。 选择一个 CronJob 窗口 (例如 0 2 * * 0 —— 周日 02:00 ),尽量减少与业务 pipeline 的重叠。
  2. 让 tenant pipeline 在收到 401 后重试。 当 tenant workload 检测到 401 时,重新挂载或重新读取 tenant Secret 并重试。 Secret 会被 rotate TaskRun 以原子方式更新;下一次读取会拿到新 token。

我们建议同时采用这两种缓解措施。

监控信号。 在轮换窗口内,tenant 侧 401 比例上升。将轮换 CronJob 与一个 dashboard 图表配对,显示按 tenant 维度统计的 http_request_total{code="401"}。

针对你的实例验证 scopes

触发条件。 使用新的 scopes 重新运行(例如添加 read_registry 或 write_registry)时,GitLab 返回如下原始错误:

{"error":"scopes does not have a valid value"}

GitLab 不会在错误正文中指出哪个 scope 无效。Task 会原样暴露该错误。

原因。 某些 scope 受实例功能开关限制。例如 read_registry 和 write_registry 需要在实例上启用 GitLab container registry 功能; 在该功能被禁用的实例上,GitLab 会拒绝整个 scopes 数组。

operator 操作。 在生产 tenant 上修改之前,先针对你的实例预验证 scope 集合:

# Option 1: query an existing user PAT and inspect its allowed scopes.
glab api personal_access_tokens/<id>

# Option 2: mint a throwaway PAT in a non-production scope using the
# same scope set; if GitLab rejects, the production change will too.
glab api -X POST personal_access_tokens \
  -F name=scope-probe \
  -F 'scopes[]=api' \
  -F 'scopes[]=read_registry' \
  -F expires_at=$(date -u -d '+1 day' +%Y-%m-%d)

如果探测失败,请从 tenant TaskRun 输入中移除有问题的 scope 后重试。 如果你需要依赖某个实例功能的 scope(例如 container registry), 请先在实例上启用该功能。

监控信号。 TaskRun Failed,且 step log 中包含 "scopes does not have a valid value"。对该短语进行告警,以便在问题传播到多个 tenant 之前暴露 scope 校验失败。

手工跨组权限规避方案

自动创建 Task 只会在 tenant group 上签发一个具有一个 accessLevel 的 GAT。如果你需要在同一个 tenant 身份下为不同 subgroup 设置不同的访问级别(例如 team-a 使用 developer,team-b 使用 maintainer),当前 Task 不支持这一点。

一个正式方案已列入延期跟进列表。手工规避方法如下:

  1. 创建一个专用 GitLab service-account 用户,并为其生成 PAT (采用 Pattern A 的 user-PAT 形态)。

  2. 使用自动创建 TaskRun 创建 tenant group + subgroups,以及集群侧的 Connector + Secret(可使用任意合理的 accessLevel——之后会被手工覆盖)。

  3. 将 service-account 用户作为每个 subgroup 的 member 添加进去, 并赋予所需的 access_level:

    glab api -X POST groups/acme-corp%2Fteam-a/members \
      -F user_id=<service-account-user-id> \
      -F access_level=30
    glab api -X POST groups/acme-corp%2Fteam-b/members \
      -F user_id=<service-account-user-id> \
      -F access_level=40
  4. 用 service-account PAT 替换 tenant Secret 中的 GAT。后续的轮换 TaskRun 会覆盖这一设置——因此请将该规避方案记录为延期跟进,而不是推荐的稳态方案。

请跟踪对正式按组访问级别支持的需求;它最终会演变为 Task 级别的选项。

故障排查

tenantGroup 值被拒绝

tenantGroup 的值必须是 GitLab group 的完整路径。顶层路径使用简单 slug (acme-corp);subgroup 路径使用斜杠(umbrella/acme-corp)。 slug 规则遵循 GitLab 的 group-path 规则(小写字母、数字、-、_、.)。

scopes does not have a valid value

请参见 runbook 中的 针对你的实例验证 scopes。 如果任一 scope 对实例无效,GitLab 会拒绝整个 scopes 数组。

Pattern A admin 缺少 can_create_group

admin Connector 的 user PAT 属于一个没有 can_create_group 标志的用户, 而请求目标是顶层 tenantGroup。Task 会失败并输出:

ERROR: admin user lacks 'can_create_group'; cannot create top-level GitLab group '<name>'.
       Either set the user's can_create_group flag on the GitLab instance,
       or use a subgroup tenantGroup (e.g. 'tenants/<name>') under a parent the admin already owns.

请设置该标志(由实例管理员操作)或切换到 Pattern B。

Pattern B admin 在 umbrella 上缺少 owner

admin Connector 的 PAT 属于一个在 umbrella 上只是 maintainer 的用户。 Subgroup 创建可能成功,但 Task 会在 GAT 生成步骤失败(GitLab API 要求 GAT 创建必须具有直接的 Owner 成员关系):

ERROR: failed to mint GAT on '<subgroup>': HTTP 400 - User does not have permission to create group access token

请将 admin user 在 umbrella 上提升为 Owner (Group → Members → edit role)。

Group-path 冲突

请参见 runbook 中的 全新创建时的 group-path 冲突。

集群内 apply 缺少 Kubernetes RBAC

如果可选的 kubeconfig workspace 未绑定,而集群内 ServiceAccount 没有在 connector namespace 中创建 Secrets 和 Connectors 的 RBAC, 则 apply 步骤会失败并返回 403 Forbidden。请为该 SA 授予所需权限, 或者绑定一个携带这些权限身份的 kubeconfig workspace。

延伸阅读