使用 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 挂载中)。本页面重点介绍运维工作流。
目录
此方案解决的问题开始之前选择部署模式前置条件 — 模式 A(顶级组 +can_create_group 用户)前置条件 — 模式 B(Umbrella 的子组 + 管理员用户 PAT)可选:用于跨集群应用的 Kubernetes ConnectorServiceAccount 权限专用的最小权限 ClusterRole平台团队模式:集群范围角色,按租户绑定将 SA 接入 TaskRun分步操作 — 模式 A:全新创建分步操作 — 模式 B:全新创建分步操作 — 原地轮换用于计划轮换的 CronJob 模式分步操作 — 身份变更时重新创建分步操作 — 过期回退(自我修复)验证结果运维运行手册令牌已过期(错过轮换窗口)令牌刷新 CronJob 已禁用或配置错误租户下线回滚Pattern-A 用户所有权审计创建新租户时的组路径冲突使用期间的轮换竞争针对实例验证作用域手动跨组权限变通方案故障排除tenantGroup 值被拒绝scopes does not have a valid valuePattern A 管理员缺少 can_create_groupPattern B 管理员在 umbrella 上缺少 owner组路径冲突集群内应用缺少 Kubernetes RBAC延伸阅读此方案解决的问题
- 租户接入。一个 TaskRun 即可创建租户 GitLab 组、可选的子组、租户 GAT,以及集群上的租户
gitlabConnector - Secret。 - 令牌轮换。按计划重新运行 TaskRun 会原位轮换租户 GAT;Secret 将以原子方式更新;正在运行的流水线会在下次启动时重新读取 Secret。
- 自动修复。如果错过某个轮换周期,且 GAT 在下一次运行前已过期,Task 会检测到令牌已过期,并自动转为重新创建。无需手动干预。
- 身份变更时重新创建。在重新运行时更改
scopes、accessLevel或subgroups[]集合,会触发对 GAT 的受控删除并重新创建。
开始之前
请确保环境满足以下要求:
- 已安装 Tekton Pipelines。
- 已安装 Connectors 系统和 GitLab Connector ConnectorClass。
- 已在运行 TaskRun 的命名空间中安装
gitlab-connector-automatic-creationTask。 请从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-kubectlConfigMap,它们位于kube-public中。
安全建议:
- 将管理员 GitLab Connector 保留在专用的管理命名空间中
(例如
connectors-management)。 - 限制可以触发 TaskRun 的人员范围——该操作会生成(并轮换)Group Access Token。
- 针对每种模式选择权限范围和影响面最小的管理员身份(请参阅下方的 选择部署模式)。
选择部署模式
Task 本身不会根据模式进行分支处理——两种模式都通过相同的代码路径执行。请根据您的 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 用户)
-
创建或选择一个专用 GitLab 用户(请勿使用人员身份)。在自托管 GitLab 上,请让 GitLab 实例管理员将此用户的
can_create_group标志设置为true。在 GitLab.com 上,任何用户都可以创建顶级组,因此无需设置标志。 -
限制该用户的所有权。该用户将成为其创建的每个组的所有者;如果该用户遭到入侵,其影响范围将覆盖这些组的并集。记录类似于“此用户不得拥有自动创建的租户集合之外的任何内容”的规则,并按计划对其进行审计(请参阅下方运行手册中的模式 A 用户所有权审计)。
-
为该用户创建 PAT,至少包含
api作用域。将 PAT 作为 Kubernetes Secret 存储在管理命名空间中: -
创建指向该 Secret 的管理员 Connector:
前置条件 — 模式 B(Umbrella 的子组 + 管理员用户 PAT)
-
在 GitLab 上创建 Umbrella 组(例如
umbrella)(如果该组尚不存在)。此操作只需执行一次——从现在开始,每个租户都将作为该组下的子组存在。 -
创建或选择一个专用 GitLab 用户作为 Umbrella 管理员。将其视为模式 A 自动化用户:使用非人员的 bot 账户,而不是现实人员的身份。此用户不需要
can_create_group(该用户创建的是子组,而不是顶级组)。 -
将该用户以 Owner 角色添加到 Umbrella,使其能够在其中创建子组,并在这些子组上创建 GAT(GAT 创建端点要求具有直接的 Owner 成员资格,而组访问令牌无法满足此要求——这就是模式 B 必须使用用户身份的原因)。
-
为该用户创建 PAT,至少包含
api作用域。将 PAT 作为 Kubernetes Secret 存储在管理命名空间中: -
创建指向 Umbrella Secret 的管理员 Connector:
可选:用于跨集群应用的 Kubernetes Connector
当管理命名空间与租户 Connector 位于不同集群时,Task 支持可选的 kubeconfig workspace。请从 kubernetes 类 Connector 挂载该 workspace:
建议:即使在同一集群中,也应从 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):
Task 还会调用 kubectl auth can-i create secrets 进行预检;该操作使用 SelfSubjectAccessReview,每个经过身份验证的用户都可以调用它,无需显式 RBAC 权限。
这些权限属于谁?
- 推荐路径 — 挂载在
kubeconfigworkspace 上的 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 的名称:
命名约定:tenant- 前缀表示绑定范围是租户命名空间(而非整个集群);-writer(相对于 -editor)表示范围更窄的仅 apply 动词集;task- 表明这是用于 Tekton-Task 驱动配置的角色。不会与 cmd/kodata/*/install.yaml 下提供的任何内容冲突。
平台团队模式:集群范围角色,按租户绑定
在平台命名空间中仅定义一次配置 SA,然后通过每个命名空间的 RoleBinding 将 ClusterRole 绑定到每个租户命名空间。这样可以将 SA 的访问范围限制在实际需要配置 Connector 的命名空间内(不会授予集群范围的 Secret 或 Connector 写入权限):
之后要加入新的租户命名空间时,平台团队只需应用 RoleBinding(重新绑定到新命名空间),无需修改 SA 或 ClusterRole。
如果需要集群范围的访问权限(例如信任每个命名空间中的该 SA),可以将每个命名空间的 RoleBinding 替换为 ClusterRoleBinding。这样会以限定范围的安全性换取每个租户少一个清单文件;请谨慎选择。
将 SA 接入 TaskRun
对于推荐的 kubernetes-Connector 路径,TaskRun 不会直接引用此 SA——应通过 kubernetes Connector 绑定它,以便将 SA 的令牌嵌入 kubeconfig。对于同集群回退路径,请在 TaskRun 上设置该 SA:
未来版本的 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。
应用它并等待完成:
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 — 请参阅模式选择器中的说明。)
结果:集群输出与模式 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 中,使其按计划执行:
将轮换 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]:
行为顺序如下:
- 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:
检查租户 Connector 和 Secret:
检查 Secret 上的轮换/重新创建注解:
使用 glab 检查 GitLab 侧是否正常:
你应看到名为 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 仅负责创建和轮换。建议的手动顺序如下:
未来的“租户拆除”Task 可作为后续工作;待租户需求出现后,将其记录为延期工单。
Pattern-A 用户所有权审计
触发条件。定期合规检查(Pattern A 用户会获得其创建的每个组的所有权,因此其影响范围会随时间扩大)。
Task 执行的操作。无 — 只读审计。按计划运行以下代码片段(或将其作为后续工作接入单独的审计 Task):
operator 操作。如果所有权组列表中包含用户不应拥有的任何组,则升级处理;否则无需操作。该审计是了解用户残余影响范围风险的工具。
监控信号。无原生信号 — 将审计输出接入 SIEM,或接入定期 CI 作业,与预期的自动创建租户组列表进行差异比较。
创建新租户时的组路径冲突
触发条件。operator 选择了 tenantGroup=acme-corp,但
acme-corp 已存在于 GitLab 中,且由其他人拥有(不是 admin 身份)。
Task 执行的操作。ensure-group GET /groups/acme-corp 返回
200,发现 admin 身份不在所有者列表中,并以以下内容退出:
两侧均不会发生变更。
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 操作。有两种方案:
- 在租户流水线空闲时安排轮换。选择一个 CronJob
窗口(例如
0 2 * * 0— 周日 02:00 ),尽量减少与业务流水线的重叠。 - 让租户流水线在收到 401 时重试。当租户工作负载检测到
401时,重新挂载或重新读取租户 Secret,然后重试。 Secret 会由轮换 TaskRun 原子更新;下一次读取将获取新令牌。
我们建议同时采用这两种缓解措施。
监控信号。在轮换窗口期间,租户侧 401 速率出现峰值。将轮换 CronJob 与监控面板图表结合,按租户显示
http_request_total{code="401"}。
针对实例验证作用域
触发条件。使用新的 scopes 重新运行时(例如添加 read_registry 或
write_registry)失败,并显示 GitLab 的原始错误:
GitLab 不会在错误正文中指出哪个作用域无效。Task 会原样呈现该错误。
原因。某些作用域受实例功能限制。例如,read_registry 和
write_registry 要求在实例上启用 GitLab 容器注册表功能;在禁用该功能的实例上,GitLab 会拒绝整个作用域数组。
operator 操作。在生产租户中更改作用域之前,先根据实例预验证作用域集合:
如果探测失败,请从租户 TaskRun 输入中移除有问题的作用域,然后重试。如果需要使用要求实例功能的作用域(例如容器注册表),请先在实例上启用该功能。
监控信号。TaskRun Failed,步骤日志中包含
"scopes does not have a valid value"。针对该短语设置告警,以便在作用域验证失败传播到多个租户之前发现问题。
手动跨组权限变通方案
自动创建 Task 会在租户组中使用一个 accessLevel 签发一个 GAT。如果您需要在一个租户身份下,为不同子组设置不同的访问级别(例如,在 team-a 上使用 developer,在 team-b 上使用 maintainer),则当前 Task 尚不支持此场景。
一流支持选项已列入延期后续事项清单。手动变通方案如下:
-
创建专用的 GitLab service-account 用户,并为其创建 PAT (Pattern A 的 user-PAT 形式)。
-
使用自动创建 TaskRun 创建租户组和子组,以及集群侧的 Connector 和 Secret(使用任意合理的
accessLevel即可——之后会手动覆盖)。 -
将 service-account 用户以成员身份添加到每个子组,并为其设置所需的
access_level: -
将租户 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 失败并显示:
设置该标志(实例管理员操作),或切换到 Pattern B。
Pattern B 管理员在 umbrella 上缺少 owner
管理员 Connector 的 PAT 属于仅是 umbrella 上 maintainer 的用户。子组创建可能成功,但 Task 会在 GAT 生成步骤失败(GitLab API 要求用户直接以 Owner 身份加入组才能创建 GAT):
将管理员用户在 umbrella 上提升为 Owner(Group → Members → 编辑角色)。
组路径冲突
请参阅 runbook 中的新创建时的组路径冲突。
集群内应用缺少 Kubernetes RBAC
如果可选的 kubeconfig workspace 未绑定,并且集群内 ServiceAccount 缺少在 Connector 命名空间中创建 Secret 和 Connector 的 RBAC 权限,则应用步骤会因 403 Forbidden 而失败。请为 SA 授予所需权限,或绑定一个包含具备这些权限的身份的 kubeconfig workspace。
延伸阅读
gitlab-connector-automatic-creationTask 参考 — 完整的参数、workspace 和结果参考。- GitLab CLI 配置和自动创建模式
— 介绍
gitlabconfigCSI 挂载、Pattern A 与 Pattern B,以及 GAT 生命周期三种路径的概念页面。 - GitLab Connector — 底层的 GitLab ConnectorClass 及其租户侧配置。