使用 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 配置和自动创建模式 介绍了底层模型(模式 A 与模式 B、GAT 的三路径生命周期,以及管理员凭证如何保留在 CSI 挂载中)。本页面重点介绍管理员工作流程。

此流程解决的问题

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

开始之前

确保环境满足以下要求:

  • 目标 GitLab 实例运行 GitLab 16.6 或更高版本。不支持更早版本:
    • GitLab 16.0 至 16.5 在 Task 轮换令牌时会忽略 expires_at,因此轮换后的令牌有效期为一周,而不是 tokenDuration 天。发生这种情况时,ensure-gat 步骤会记录一行 WARN: 日志。
    • GitLab 16.0 之前的版本没有轮换端点,因此在令牌过期前重新运行会失败。
    • GitLab 14.7 之前的版本没有 Group Access Token API,因此任何运行都会失败。
  • 已安装 Tekton Pipelines。
  • 已安装 Connectors 系统和 GitLab Connector ConnectorClass。
  • 已在运行 TaskRun 的命名空间中安装 gitlab-connector-automatic-creation Task。从 cmd/kodata/connectors-gitlab-tektoncd/1.0.0/install.yaml 源清单(或已发布的目录格式)应用该 Task — 有关 REGISTRY + TARGET_NS + envsubst | kubectl apply 配方,请参阅 Task 参考的安装部分。 connectors-operator 仅安装框架(CRD、RBAC、ConnectorClass、ResourceInterface)——Task 需要按照 Tekton 约定由用户应用。
  • 目录中的 glab 和 kubectl 工具镜像可从内部 registry 访问。Task 使用位于 kube-public 中的现有 catalog.tekton.dev/tool-image-glab 和 catalog.tekton.dev/tool-image-kubectl ConfigMap。

安全建议:

  • 将管理员 GitLab Connector 保存在私有管理命名空间中 (例如 connectors-management)。
  • 限制可触发 TaskRun 的人员范围——该操作会生成(并轮换)Group Access Token。
  • 根据模式选择占用权限范围最小的管理员身份(请参阅下方的 选择部署模式)。

选择部署模式

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

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

为什么使用用户 PAT,而不是 umbrella 上的 Group Access Token(GAT)? GAT 属于一个 GitLab 限制其只能用于签发组的组 bot 用户:它无法在新创建的子组上签发 GAT(HTTP 400 — “User does not have permission to create group access token”),并且组 bot 不能作为其他组的直接成员添加。因此,Task 需要使用普通用户身份——为其授予 umbrella 所有者权限的专用自动化用户——以便在子组上签发每个租户对应的 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(伞形组的子组 + 管理员用户 PAT)

  1. 在 GitLab 上创建伞形组(例如 umbrella),如果该组尚不存在。这是一次性操作——从现在开始,每个租户都将作为其下的子组存在。

  2. 创建或选择一个专用 GitLab 用户作为伞形组管理员。像对待模式 A 自动化用户一样对待该用户:使用非人员身份的 bot 账户,而不是真实人员的身份。该用户不需要 can_create_group(它创建的是子组,而非顶级组)。

  3. 将该用户以 Owner 身份添加到伞形组中,使其能够在伞形组下创建子组,并在这些子组上创建 GAT(GAT 创建端点要求用户具有直接的 Owner 成员资格,而 group access token 无法满足此要求——这就是模式 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. 创建指向伞形组 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),可以用 ClusterRoleBinding 替代按命名空间配置的 RoleBinding。这样会牺牲范围限定带来的安全性,以减少每个租户一个清单的配置;请谨慎选择。

将 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:全新创建

此接入示例会创建一个顶级 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 已预先存在,并且管理员 Connector 携带一个 user 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,并将 expires_at 设置为今天起 tokenDuration 天后。GitLab 会以原子方式使旧令牌失效,并返回一个在该日期过期的新令牌;租户 Secret 会原地更新。GitLab 实例策略会限制 expires_at 可以提前的时长(最长为轮换日期起一年;如果实例管理员设置了更短的最长生命周期,则以该限制为准);如果 tokenDuration 过长,GitLab 会返回 HTTP 400 并拒绝该请求。

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 会在每个调度周期 kubectl create 一个新的 TaskRun。请将其与令牌过期告警结合使用(请参阅运行手册中的令牌已过期)。

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

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

当您更改 scopes、accessLevel 或 subgroups[] 集合时,Task 会检测到身份漂移,并重新创建租户 GAT,而不是轮换现有 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 也会对过期令牌执行垃圾回收),在 tenantGroup 处签发新的 GAT,重写 Secret,并设置 Connector 注释 connectors.cpaas.io/gat-recreated-at。TaskRun 报告 Succeeded。无需 operator 手动干预。

operator 操作。立即恢复无需执行任何操作。长期来看:调查轮换 CronJob 未运行的原因,并将告警阈值收紧到过期窗口以内(例如,当陈旧令牌的年龄超过 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 中存在,且由其他人(而非管理员身份)拥有。

Task 执行内容。ensure-group GET /groups/acme-corp 返回 200,发现管理员身份不在所有者列表中,并退出,同时显示:

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

任一侧均不会发生变更。

operator 操作。选择其他 tenantGroup(例如,如果有 umbrella,则选择 acme-corp-prod 或 tenants/acme-corp),或与现有组的所有者协调。

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

使用期间的轮换竞争

触发条件。rotate TaskRun 与读取同一租户 Secret/<connector-name> 的长时间运行租户流水线并发运行。正在运行的流水线 pod 在启动时读取了旧令牌值;在运行期间,rotate 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 会由 rotate 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 container registry 功能;在禁用该功能的实例上,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 输入中删除有问题的作用域,然后重试。如果需要使用依赖实例功能的作用域(例如 container registry),请先在实例上启用该功能。

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

手动跨组权限变通方案

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

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

  1. 创建专用的 GitLab 服务账户用户,并为其创建 PAT (Pattern A 的用户-PAT 形式)。

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

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

跟踪对一等 per-group 访问级别支持的需求;该功能最终将成为 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 工作区未绑定,并且集群内 ServiceAccount 缺少在 Connector 命名空间中创建 Secret 和 Connector 的 RBAC 权限,则应用步骤会因 403 Forbidden 失败。请为 SA 授予所需权限,或绑定携带具有这些权限的身份的 kubeconfig 工作区。

延伸阅读