使用 Tekton 自动创建 GitLab 租户组和 Connector

在新租户接入 Alauda Container Platform 时,运维人员通常需要重复执行相同的 GitLab 设置步骤:创建租户组(以及各团队的子组)、生成 Group Access Token,然后 kubectl apply 租户的 gitlab Connector 和匹配的身份验证 Secret。本指南将这一流程整合为单个 Tekton TaskRun,并演示如何按计划运行同一个 TaskRun,以便在租户令牌过期前轮换该令牌。

实现机制是 gitlab-connector-automatic-creation Task。 首次运行可完成初始配置,之后再次运行即可轮换租户 GAT(或者在身份相关输入发生变化时,重新创建租户 GAT)。

概念页面 GitLab CLI Configuration and Auto-Creation Patterns 介绍了底层模型(Pattern A 与 Pattern B、GAT 的三路径生命周期,以及管理员凭证如何保留在 CSI 挂载中)。本页面重点介绍运维工作流。

此方案解决的问题

  • 租户接入。一个 TaskRun 即可创建租户 GitLab 组、可选的子组、租户 GAT,以及集群上的租户 gitlab Connector - Secret。
  • 令牌轮换。按计划重新运行 TaskRun 会原位轮换租户 GAT;Secret 将以原子方式更新;正在运行的流水线会在下次启动时重新读取 Secret。
  • 自动修复。如果错过某个轮换周期,且 GAT 在下一次运行前已过期,Task 会检测到令牌已过期,并自动转为重新创建。无需手动干预。
  • 身份变更时重新创建。在重新运行时更改 scopes、accessLevel 或 subgroups[] 集合,会触发对 GAT 的受控删除并重新创建。

开始之前

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

  • 已安装 Tekton Pipelines。
  • 已安装 Connectors 系统和 GitLab Connector ConnectorClass。
  • 已在运行 TaskRun 的命名空间中安装 gitlab-connector-automatic-creation Task。 请从 cmd/kodata/connectors-gitlab-tektoncd/1.0.0/install.yaml 源清单(或已发布的 catalog 结构)应用该 Task——有关 REGISTRY + TARGET_NS + envsubst | kubectl apply 配置步骤,请参阅 Task 参考文档的安装部分。 connectors-operator 仅安装框架(CRD、RBAC、ConnectorClass、ResourceInterface)——Task 本身按照 Tekton 约定由用户应用。
  • 内部 registry 可以访问 catalog 中的 glab 和 kubectl 工具镜像。Task 使用现有的 catalog.tekton.dev/tool-image-glab 和 catalog.tekton.dev/tool-image-kubectl ConfigMap,它们位于 kube-public 中。

安全建议:

  • 将管理员 GitLab Connector 保留在专用的管理命名空间中 (例如 connectors-management)。
  • 限制可以触发 TaskRun 的人员范围——该操作会生成(并轮换)Group Access Token。
  • 针对每种模式选择权限范围和影响面最小的管理员身份(请参阅下方的 选择部署模式)。

选择部署模式

Task 本身不会根据模式进行分支处理——两种模式都通过相同的代码路径执行。请根据您的 GitLab 租户结构进行选择:

选择适用场景
模式 A — 顶级租户组,具有 can_create_group 的管理员用户 PAT全新部署的自托管 GitLab;每个顶级组对应一个租户;您希望租户之间实现完全隔离。
模式 B — umbrella 的子组,在 umbrella 上具有 Owner 权限的管理员用户 PAT您已经有一个用于整合租户的 umbrella 组(SaaS GitLab 以及使用共享管理工具的组织通常采用此方式)。影响范围更小。

为什么使用用户 PAT,而不是 umbrella 上的 Group Access Token(GAT)? GAT 属于一个组 bot 用户,而 GitLab 会将该用户限制在签发该令牌的组中:它无法在新创建的子组上创建 GAT(HTTP 400 — "User does not have permission to create group access token"),并且组 bot 无法作为直接成员添加到其他组中。因此,Task 需要使用普通用户身份——一个授予其 umbrella Owner 权限的专用自动化用户——来在子组上为每个租户创建 GAT。请参阅下方的模式 B 前置条件。

有关完整比较,请参阅 模式 A 与模式 B。

前置条件 — 模式 A(顶级组 + can_create_group 用户)

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

  2. 限制该用户的所有权。该用户将成为其创建的每个组的所有者;如果该用户遭到入侵,其影响范围将覆盖这些组的并集。记录类似于“此用户不得拥有自动创建的租户集合之外的任何内容”的规则,并按计划对其进行审计(请参阅下方运行手册中的模式 A 用户所有权审计)。

  3. 为该用户创建 PAT,至少包含 api 作用域。将 PAT 作为 Kubernetes Secret 存储在管理命名空间中:

    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 的管理员 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

前置条件 — 模式 B(Umbrella 的子组 + 管理员用户 PAT)

  1. 在 GitLab 上创建 Umbrella 组(例如 umbrella)(如果该组尚不存在)。此操作只需执行一次——从现在开始,每个租户都将作为该组下的子组存在。

  2. 创建或选择一个专用 GitLab 用户作为 Umbrella 管理员。将其视为模式 A 自动化用户:使用非人员的 bot 账户,而不是现实人员的身份。此用户不需要 can_create_group(该用户创建的是子组,而不是顶级组)。

  3. 将该用户以 Owner 角色添加到 Umbrella,使其能够在其中创建子组,并在这些子组上创建 GAT(GAT 创建端点要求具有直接的 Owner 成员资格,而组访问令牌无法满足此要求——这就是模式 B 必须使用用户身份的原因)。

  4. 为该用户创建 PAT,至少包含 api 作用域。将 PAT 作为 Kubernetes Secret 存储在管理命名空间中:

    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 的管理员 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

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

当管理命名空间与租户 Connector 位于不同集群时,Task 支持可选的 kubeconfig workspace。请从 kubernetes 类 Connector 挂载该 workspace:

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

建议:即使在同一集群中,也应从 kubernetes 类 Connector 挂载 kubeconfig workspace。这样可以明确 Task 的有效身份(即 Connector 提供其令牌的 SA),并使同集群和跨集群设置保持一致。有关 Connector 设置,请参阅 在 Tekton Task 中使用 Kubernetes Connector。

当未绑定 kubeconfig workspace 时,Task 将回退到 TaskRun 的集群内 ServiceAccount——这对于同集群使用是可行的,但平台团队通常更倾向于使用 kubernetes-Connector 路径,以便将配置身份放在 Connector 上,而不是 TaskRun 的 SA 上。

ServiceAccount 权限

此 Task 面向平台团队,由平台团队代表众多应用团队配置 GitLab 组和 gitlab Connector。权限集较小,并且适用于各种 Connector 类型(Harbor、GitLab、…),最好表示为一个集群范围的角色,并按租户进行绑定。

配置 ServiceAccount 需要在每个租户Connector 命名空间中对两种资源类型具有写入权限(即 connector 参数的 <conn_ns> 部分——例如 connectors-management/acme-corp → connectors-management):

API 组资源动词原因
""(核心)secretsget、patch、create应用包含 GAT 的 Secret(服务器端 apply 使用 PATCH;首次运行时需要 CREATE)
connectors.alauda.ioconnectorsget、patch、create应用指向该 Secret 的租户 Connector CR

Task 还会调用 kubectl auth can-i create secrets 进行预检;该操作使用 SelfSubjectAccessReview,每个经过身份验证的用户都可以调用它,无需显式 RBAC 权限。

这些权限属于谁?

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

无论采用哪种方式,权限结构都相同。Harbor 自动创建 Task 也应使用同一个 SA(以及下方相同的 ClusterRole + RoleBinding 对)——这些规则并非 GitLab 专用。

专用的最小权限 ClusterRole

operator 提供了一个宽泛的 connectors-connector-editor-role ClusterRole,授予完整的 edit 动词集({create,delete,get,list,patch,update,watch})。Task 不需要这些权限。它只会针对两种对象执行 kubectl apply --server-side,因此受支持的配置方式是使用一个专用 ClusterRole,仅包含 Task 使用的三个动词,并采用能够明确表明仅用于 apply 的名称:

ClusterRole规则动词
connectors-tenant-task-writercore/secrets + connectors.alauda.io/connectorsget、patch、create

命名约定:tenant- 前缀表示绑定范围是租户命名空间(而非整个集群);-writer(相对于 -editor)表示范围更窄的仅 apply 动词集;task- 表明这是用于 Tekton-Task 驱动配置的角色。不会与 cmd/kodata/*/install.yaml 下提供的任何内容冲突。

平台团队模式:集群范围角色,按租户绑定

在平台命名空间中仅定义一次配置 SA,然后通过每个命名空间的 RoleBinding 将 ClusterRole 绑定到每个租户命名空间。这样可以将 SA 的访问范围限制在实际需要配置 Connector 的命名空间内(不会授予集群范围的 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

之后要加入新的租户命名空间时,平台团队只需应用 RoleBinding(重新绑定到新命名空间),无需修改 SA 或 ClusterRole。

如果需要集群范围的访问权限(例如信任每个命名空间中的该 SA),可以将每个命名空间的 RoleBinding 替换为 ClusterRoleBinding。这样会以限定范围的安全性换取每个租户少一个清单文件;请谨慎选择。

将 SA 接入 TaskRun

对于推荐的 kubernetes-Connector 路径,TaskRun 不会直接引用此 SA——应通过 kubernetes Connector 绑定它,以便将 SA 的令牌嵌入 kubeconfig。对于同集群回退路径,请在 TaskRun 上设置该 SA:

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 已采用的角色结构约定保持一致。 在此之前,由平台团队负责维护。

分步操作 — 模式 A:全新创建

此 onboarding 示例会创建顶级 GitLab 组 acme-corp 及两个按团队划分的子组,在 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: gitlabUrl
      value: https://gitlab.example.com
    - name: tenantGroup
      value: acme-corp
    - name: subgroups
      value:
        - backend
        - frontend
    - name: accessLevel
      value: owner
    - name: scopes
      value:
        - api
    - name: tokenDuration
      value: "30"
    - name: basicAuthSecrets
      value:
        - connectors-management/acme-corp-basic-auth
  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 中包含顶级组 acme-corp 以及子组 acme-corp/backend、acme-corp/frontend。
  • 名为 connector-connectors-management-acme-corp/<identity> 的 GAT 存在于 acme-corp,其作用域为 [api],访问级别为 owner,过期时间为今天 + 30 天。
  • 集群中包含 Secret/acme-corp(类型为 connectors.cpaas.io/gitlab-pat-auth)以及指向它的 Connector/acme-corp,二者均位于 connectors-management 中。

分步操作 — 模式 B:全新创建

同一租户采用不同的部署模式:umbrella umbrella 已预先存在,admin Connector 携带的是一个用户 PAT,其用户在 umbrella 上拥有 Owner 权限。(Group Access Token 无法在子组上签发每个租户的 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: gitlabUrl
      value: https://gitlab.example.com
    - name: tenantGroup
      value: umbrella/acme-corp
    - name: subgroups
      value: []
    - name: accessLevel
      value: owner
    - name: scopes
      value:
        - api
    - name: tokenDuration
      value: "30"
    - name: basicAuthSecrets
      value: []
  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

结果:集群输出与模式 A 完全相同;在 GitLab 侧,新组位于 umbrella/acme-corp(umbrella 的子组),而不是顶级位置,并且 GAT 在 umbrella/acme-corp 处签发(不是在 umbrella 处)。

分步操作 — 原地轮换

使用完全不变的所有参数重新运行 TaskRun,会原地轮换现有 GAT。Task 会根据名称前缀(connector-<connector-namespace>-<connector-name>)定位现有 GAT,确认其身份匹配,然后调用 POST /groups/:id/access_tokens/:token_id/rotate。GitLab 会以原子方式使旧令牌失效,并返回一个新的令牌,其 expires_at 在 tokenDuration 天数的基础上延长;租户 Secret 会原地更新。

TaskRun 的结构特意与模式 A 的创建 TaskRun 保持一致。适合 Cron:tokenDuration 表示天数,因此每次轮换都会将 expires_at 更新为今天 + N 天。

用于计划轮换的 CronJob 模式

将轮换 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

将轮换 TaskRun 清单存储在 rotate-acme-corp-gat-template ConfigMap 中;CronJob 会在每个时间点对新的 TaskRun 执行 kubectl create。将其与过期令牌告警结合使用(请参阅运行手册中的令牌已过期)。

提示:设置 CronJob 计划,使连续运行之间的间隔短于 tokenDuration 减去安全余量。对于 tokenDuration=30 天的有效期,按周调度。对于 tokenDuration=7 天的有效期,按天调度。

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

当你更改 scopes、accessLevel 或 subgroups[] 集时,Task 会检测到身份漂移,并重新创建租户 GAT,而不是轮换它。例如,将范围从 [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: gitlabUrl
      value: https://gitlab.example.com
    - name: tenantGroup
      value: acme-corp
    - name: subgroups
      value:
        - backend
        - frontend
    - name: accessLevel
      value: owner
    - name: scopes
      value:
        - api
        - read_registry
    - name: tokenDuration
      value: "30"
    - name: basicAuthSecrets
      value:
        - connectors-management/acme-corp-basic-auth
  workspaces:
    - name: gitlabconfig
      csi:
        driver: connectors-csi
        readOnly: true
        volumeAttributes:
          connector.name: gitlab-admin
          configuration.names: gitlabconfig

行为顺序如下:

  • Task 定位现有 GAT。
  • 现有 GAT 的身份不再与所需身份匹配。
  • Task 撤销该 GAT(DELETE /groups/:id/access_tokens/:token_id), 并根据请求的身份签发一个新的 GAT。
  • 租户 Secret 更新为新令牌。
  • 在 Secret 上设置注解 connectors.cpaas.io/gat-recreated-at。

注意:仅在扩展时,子组集不会影响身份——将 team-c 添加到 subgroups 会原地轮换 GAT,并在 <tenantGroup>/team-c 下创建缺失的子组。移除或更改规范子组集会影响身份,并触发重新创建。

分步操作 — 过期回退(自我修复)

如果错过了轮换周期,并且 GAT 的 expires_at 在下一次运行前已到期,Task 会自动修复。恢复 TaskRun 的结构与轮换 TaskRun 相同。在 GitLab 侧:

  • ensure-gat(Task 的第 3 步)会在 acme-corp 列出现有 GAT,并找到带有 connector-<ns>-<name> 前缀的 GAT。
  • 它会检测到 expires_at < now,并记录日志 WARN: existing GAT <id> is expired; falling through to recreate。
  • 它会撤销过期的 GAT(尽力而为;GitLab 也会回收过期令牌),并签发一个新的 GAT。
  • 租户 Secret 会使用新的令牌值重写。

TaskRun 会报告 Succeeded。无需 operator 采取任何操作即可立即恢复——但你仍应调查轮换 Cron 为何错过执行(请参阅下方运行手册中的令牌已过期)。

验证结果

检查 TaskRun:

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

检查租户 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 侧是否正常:

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

你应看到名为 connector-connectors-management-acme-corp/<identity> 的 GAT,其具有请求的 scopes、access_level,以及一个未来到期的 expires_at。

运维运行手册

每个场景的结构均为:触发条件 → Task 执行的操作 → operator 操作 → 监控信号。

令牌已过期(错过轮换窗口)

触发条件。operator 使用 tokenDuration=30 创建了租户 Connector,但下一次轮换 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,并自动从轮换路径切换到删除 + 重新创建路径。 否则,GitLab 的轮换端点会返回 400 invalid_grant(令牌已过期);Task 不会调用该端点。

结果。最终状态与正常重新创建相同:旧 GAT ID 已消失(尽力删除;GitLab 也会对过期令牌执行垃圾回收), 新 GAT 在 tenantGroup 处签发,Secret 被重写,并且 Connector 注解 connectors.cpaas.io/gat-recreated-at 被设置。TaskRun 报告 Succeeded。无需 operator 手动干预。

operator 操作。立即恢复无需执行任何操作。长期来看: 调查轮换 Cron 未执行的原因,并将告警阈值收紧到过期窗口以内(例如,当陈旧令牌年龄超过 tokenDuration - 7d 时发出告警)。

监控信号。建议的告警规则:

  • gat_age_seconds > tokenDuration_seconds - 604800(警告 — 过期前 7 天)。
  • gat_age_seconds > tokenDuration_seconds(页面告警 — 已过期; 下一次 TaskRun 会自动修复,但在此期间租户仍在读取过期的凭证)。
  • 轮换 CronJob 的 TaskRun 的 taskrun_status == "Failed"(页面告警)。

令牌刷新 CronJob 已禁用或配置错误

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

Task 执行的操作。无 — Task 仅在被调用时运行。上述“错过轮换”的故障模式会在到达过期时间后开始生效。

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

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

租户下线回滚

触发条件。租户 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.

未来的“租户拆除”Task 可作为后续工作;待租户需求出现后,将其记录为延期工单。

Pattern-A 用户所有权审计

触发条件。定期合规检查(Pattern A 用户会获得其创建的每个组的所有权,因此其影响范围会随时间扩大)。

Task 执行的操作。无 — 只读审计。按计划运行以下代码片段(或将其作为后续工作接入单独的审计 Task):

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

operator 操作。如果所有权组列表中包含用户不应拥有的任何组,则升级处理;否则无需操作。该审计是了解用户残余影响范围风险的工具。

监控信号。无原生信号 — 将审计输出接入 SIEM,或接入定期 CI 作业,与预期的自动创建租户组列表进行差异比较。

创建新租户时的组路径冲突

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

Task 执行的操作。ensure-group GET /groups/acme-corp 返回 200,发现 admin 身份不在所有者列表中,并以以下内容退出:

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),或与现有组的所有者协调。

监控信号。TaskRun Failed,步骤日志中包含明确的错误消息。如需快速获取信号,可针对该消息本身设置告警。

使用期间的轮换竞争

触发条件。轮换 TaskRun 与正在运行的长期租户流水线并发执行,而该流水线读取相同的租户 Secret/<connector-name>。正在运行的流水线 pod 在启动时读取了旧令牌值; 执行期间,轮换 TaskRun 调用 POST /groups/:id/access_tokens/:token_id/rotate,原子地使旧令牌失效;正在运行的 pod 后续推送或 API 调用因 401 而失败。

Task 执行的操作。Task 不会与租户流水线协调 — 轮换会按计划无条件执行。

operator 操作。有两种方案:

  1. 在租户流水线空闲时安排轮换。选择一个 CronJob 窗口(例如 0 2 * * 0 — 周日 02:00 ),尽量减少与业务流水线的重叠。
  2. 让租户流水线在收到 401 时重试。当租户工作负载检测到 401 时,重新挂载或重新读取租户 Secret,然后重试。 Secret 会由轮换 TaskRun 原子更新;下一次读取将获取新令牌。

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

监控信号。在轮换窗口期间,租户侧 401 速率出现峰值。将轮换 CronJob 与监控面板图表结合,按租户显示 http_request_total{code="401"}。

针对实例验证作用域

触发条件。使用新的 scopes 重新运行时(例如添加 read_registry 或 write_registry)失败,并显示 GitLab 的原始错误:

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

GitLab 不会在错误正文中指出哪个作用域无效。Task 会原样呈现该错误。

原因。某些作用域受实例功能限制。例如,read_registry 和 write_registry 要求在实例上启用 GitLab 容器注册表功能;在禁用该功能的实例上,GitLab 会拒绝整个作用域数组。

operator 操作。在生产租户中更改作用域之前,先根据实例预验证作用域集合:

# 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)

如果探测失败,请从租户 TaskRun 输入中移除有问题的作用域,然后重试。如果需要使用要求实例功能的作用域(例如容器注册表),请先在实例上启用该功能。

监控信号。TaskRun Failed,步骤日志中包含 "scopes does not have a valid value"。针对该短语设置告警,以便在作用域验证失败传播到多个租户之前发现问题。

手动跨组权限变通方案

自动创建 Task 会在租户组中使用一个 accessLevel 签发一个 GAT。如果您需要在一个租户身份下,为不同子组设置不同的访问级别(例如,在 team-a 上使用 developer,在 team-b 上使用 maintainer),则当前 Task 尚不支持此场景。

一流支持选项已列入延期后续事项清单。手动变通方案如下:

  1. 创建专用的 GitLab service-account 用户,并为其创建 PAT (Pattern A 的 user-PAT 形式)。

  2. 使用自动创建 TaskRun 创建租户组和子组,以及集群侧的 Connector 和 Secret(使用任意合理的 accessLevel 即可——之后会手动覆盖)。

  3. 将 service-account 用户以成员身份添加到每个子组,并为其设置所需的 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. 将租户 Secret 中的 GAT 替换为 service-account PAT。 后续的轮换 TaskRun 会覆盖此设置——因此请将此变通方案记录为延期后续事项,而不是推荐的稳定状态。

跟踪对一流的按组访问级别支持的需求;该功能最终会成为 Task 级别的选项。

故障排除

tenantGroup 值被拒绝

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

scopes does not have a valid value

请参阅 runbook 中的根据实例验证作用域。 如果作用域数组中有任何一个作用域对该实例无效,GitLab 会拒绝整个作用域数组。

Pattern A 管理员缺少 can_create_group

管理员 Connector 的用户 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 管理员在 umbrella 上缺少 owner

管理员 Connector 的 PAT 属于仅是 umbrella 上 maintainer 的用户。子组创建可能成功,但 Task 会在 GAT 生成步骤失败(GitLab API 要求用户直接以 Owner 身份加入组才能创建 GAT):

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

将管理员用户在 umbrella 上提升为 Owner(Group → Members → 编辑角色)。

组路径冲突

请参阅 runbook 中的新创建时的组路径冲突。

集群内应用缺少 Kubernetes RBAC

如果可选的 kubeconfig workspace 未绑定,并且集群内 ServiceAccount 缺少在 Connector 命名空间中创建 Secret 和 Connector 的 RBAC 权限,则应用步骤会因 403 Forbidden 而失败。请为 SA 授予所需权限,或绑定一个包含具备这些权限的身份的 kubeconfig workspace。

延伸阅读