GitLab CLI 配置与自动创建模式
本概念页介绍 gitlab-connector-automatic-creation
Tekton Task 如何通过 gitlabconfig
CSI 挂载读取 GitLab 管理员 Connector,介绍两种受支持的部署模式(模式 A 与模式 B)、
三种路径的 Group Access Token(GAT)生命周期,以及 Task 最终落到集群中的租户侧
表面。
有关 GitLab Connector 及其其他配置
(gitconfig、供客户端工作负载使用的 gitlabconfig),请参见
GitLab Connector。本页重点说明
自动创建 Task 如何在服务端使用 gitlabconfig。
Task 的作用
gitlab-connector-automatic-creation Task 以一个 管理员 GitLab
Connector 为输入,并在单个 TaskRun 中协调租户的 GitLab 租户配置:
- 在
tenantGroup创建或重用一个租户 GitLab group,并在其下创建任意 可选的按团队划分的subgroups。 - 在租户 group 上按请求的
accessLevel和scopes配置一个 Group Access Token。 - 在集群中生成一个租户
gitlabConnector + 匹配的认证 Secret,类型为connectors.cpaas.io/gitlab-pat-auth。
重新运行同一个 TaskRun 是幂等的:未变化的输入会就地轮换 GAT;影响身份的输入变更会触发受控的重新创建;已过期的 GAT 会自动恢复(在错过轮换时实现自愈)。
管理员凭证如何保留在挂载中
Task 从不会将原始管理员 PAT 或 GAT 读取到 Pod 环境变量中。 相反,管理员 Connector 通过 Connectors CSI 被消费:
CSI 驱动会渲染一个 glab config.yml,其中 host 指向管理员 Connector 的
Connectors proxy Service(例如
c-gitlab-admin.connectors-management.svc.cluster.local)。记录在该 config.yml 中的 token
材料是一个短期有效的 Kubernetes API token,用于调用 proxy,而不是原始的管理员 PAT/GAT。
真正持有管理员凭证的是 proxy;它会在服务端的出站 GitLab API 调用中注入真实的
PRIVATE-TOKEN 请求头。
这意味着:
- Pod 永远看不到管理员 PAT/GAT 的值。
- Pod 日志不会意外泄露管理员凭证。
- 谁控制 proxy,谁就控制管理员凭证——请将管理员 Connector 保持在私有的管理命名空间中,并对运行 TaskRun 的 ServiceAccount 进行限制。
模式 A 与模式 B
该 Task 与部署模式无关:它只是发起 glab API 调用,并信任 GitLab 去强制执行相应权限。两种受支持的模式仅在管理员 Connector 携带的凭证类型以及租户 group 位于 GitLab 命名空间树中的位置上有所不同。
模式 A — 顶层 + can_create_group 用户 PAT
- 管理员用户 PAT — 创建
acme;由于该用户是创建者,因此会成为 Owner。 - 影响范围 — 该用户在实例范围内拥有的所有 group。
模式 B — umbrella 的 subgroup + 在 umbrella 上拥有 Owner 的管理员用户 PAT
- 管理员用户 PAT — 该用户是
umbrella的直接 Owner,这使其既可以在其下创建 subgroup,也可以在这些 subgroup 上为每个租户签发 GAT。GAT 创建要求直接 Owner 成员资格;Group Access Token 无法满足这一要求(参见下方说明)。 - 影响范围 — 仅限 umbrella 子树。
为什么 umbrella 上不能使用 Group Access Token(GAT)? GAT 属于一个 group bot user,而 GitLab 将该 bot 限制在其签发所在的 group 内。该 bot 可以创建 subgroup(对此而言 Maintainer 权限已足够),但不能在这些 subgroup 上签发 GAT:GAT 创建端点要求 直接 Owner 成员资格,group bot 不能被添加为其他 group 的成员(
HTTP 400 — project bots cannot be added to other groups),而 group-share 也无法满足 direct-Owner 检查。因此,模式 B 使用的是一个普通用户身份:先将其一次性添加为 umbrella 的 Owner,然后由该用户为每个租户 subgroup 签发 GAT。
Task 在参数解析阶段不会验证管理员身份类型。它会调用 GitLab API,并在管理员缺少所需权限时直接透出 GitLab 原样返回的错误。这使 Task 保持简洁——只有 GitLab 才是管理员身份可执行操作的权威来源。
三路径 GAT 生命周期
每个 TaskRun 都会根据现有租户 GAT 状态和输入参数,在三条路径中选择其一:
- 就地轮换。 输入未变化,并且在
tenantGroup找到了一个健康的现有 GAT,其名称与connector-<connector-namespace>-<connector-name>匹配。Task 调用POST /groups/:id/access_tokens/:token_id/rotate,GitLab 会原子性地使旧 token 值失效并返回一个新的 token,同时租户 Secret 会就地更新。Connector 资源保持不变。注解connectors.cpaas.io/gat-rotated-at会记录轮换时间戳。 - 重新创建。 影响身份的输入发生了变化(
scopes、accessLevel或subgroups[]集合)。Task 会撤销现有 GAT(DELETE /groups/:id/access_tokens/:token_id),并按请求属性签发一个新的 GAT;租户 Secret 会被重写;注解connectors.cpaas.io/gat-recreated-at会记录重新创建时间戳。 - 过期后回退。 GAT 仍然存在,但其
expires_at已经早于当前时间(上一次轮换的 cron 错过了窗口)。GitLab 的 rotate 端点会返回400 invalid_grant,因此 Task 会自动回退到重新创建路径。TaskRun 报告Succeeded。无需人工运维介入。 操作指南中的 Operations runbook 说明了应如何通过告警发现错过轮换窗口。
下面的决策树总结了这三条路径:
租户侧表面
TaskRun 成功后,集群中会包含:
- Secret:位于 connector 命名空间,类型为
connectors.cpaas.io/gitlab-pat-auth,其中data.token保存最新的 GAT 值,data.username设置为 GAT 的名称。 - Connector:位于同一命名空间,class 为
gitlab,其中spec.address指向 GitLab 实例,spec.auth.name设置为patAuth,spec.auth.secretRef.name指向上面的 Secret。
任意命名空间中的租户工作负载都可以通过现有的 gitconfig 和 gitlabconfig 配置来消费该 Connector——这与手工创建的 GitLab Connectors 暴露的表面一致。有关租户侧挂载模式,请参见
GitLab Connector,有关租户侧示例,请参见
Using GitLab CLI (glab) with GitLab Connector
指南。
可选:用于跨集群 apply 的 kubeconfig Workspace
该 Task 还支持一个可选的 kubeconfig workspace。绑定后,apply 步骤会从该 workspace 导出 KUBECONFIG,并将租户 Connector + Secret 应用到目标集群,而不是应用到集群内的 ServiceAccount 上下文。以下场景下使用它:
- 管理命名空间运行在控制平面集群上,但租户 Connector 应落到单独的业务集群。
- 你希望对本地 SA 实施更严格的 RBAC——
kubeconfigworkspace 可以携带一个不同的身份,仅作用于 connector 命名空间。
该 workspace 可以通过包含 kubeconfig 的 Kubernetes Secret 提供,也可以通过来自 kubernetes class Connector 的 Connectors CSI 提供:
当 workspace 未绑定时,apply 步骤使用集群内的 ServiceAccount 上下文;该 SA 需要具备在 connector 命名空间中创建 Secret 和 Connector 的 RBAC 权限。
延伸阅读
- 通过 Tekton 自动创建 GitLab 租户 group + Connector — 包含 Pattern A、Pattern B、就地轮换、重新创建以及过期后回退的完整操作指南与 TaskRun 示例。
gitlab-connector-automatic-creationTask 参考 — 完整的参数、workspace 和结果参考。