GitLab CLI 配置与自动创建模式
本概念页面介绍 gitlab-connector-automatic-creation
Tekton Task 如何通过 gitlabconfig
CSI 挂载使用 GitLab admin Connector、两种受支持的部署模式(模式 A 与模式 B)、
Group Access Token(GAT)的三种路径生命周期,以及该 Task 在集群中落地的租户侧
表面。
有关完整的 GitLab Connector 及其其他配置
(面向客户端工作负载的 gitconfig、gitlabconfig),请参阅
GitLab Connector。本页面重点介绍自动创建 Task
如何在服务器端使用 gitlabconfig。
Task 的作用
gitlab-connector-automatic-creation Task 在单个 TaskRun 中获取一个 admin GitLab
Connector,并协调租户的 GitLab 租户配置:
- 在
tenantGroup创建或复用租户 GitLab 组,并在其下创建或复用任意 可选的每团队subgroups。 - 在租户组中配置 Group Access Token,并设置请求的
accessLevel和scopes。 - 在集群上落地一个租户
gitlabConnector,以及一个类别为connectors.cpaas.io/gitlab-pat-auth的匹配身份验证 Secret。
重新运行相同的 TaskRun 是幂等的:输入未更改时,会原地轮换 GAT;影响身份的输入发生更改时,会触发受控重新创建;已过期的 GAT 会自动恢复 (可自行修复错过的轮换)。
Admin 凭证如何保留在挂载中
Task 绝不会将原始 admin PAT 或 GAT 读入 Pod 环境。 相反,admin Connector 通过 Connectors CSI 使用:
CSI 驱动会呈现一个 glab config.yml,其
host 指向 admin Connector 的
Connectors proxy Service(例如
c-gitlab-admin.connectors-management.svc.cluster.local)。该
config.yml 中记录的令牌
材料是用于调用代理的短期 Kubernetes API
令牌,而不是原始的 admin PAT/GAT。代理负责持有 admin 凭证;它会在服务器端将真实的
PRIVATE-TOKEN 标头注入发往 GitLab API 的调用中。
这意味着:
- Pod 永远不会看到 admin PAT/GAT 值。
- Pod 日志不会意外泄露 admin 凭证。
- 控制代理的任何人都可以控制 admin 凭证——请将 admin Connector 保留在私有管理命名空间中,并限制运行 TaskRun 的 ServiceAccount。
模式 A 与模式 B
该 Task 与部署模式无关:它会发出 glab API 调用,并信任 GitLab 强制执行由此产生的权限。两种受支持的模式仅在 admin Connector 所携带的凭证类型,以及租户组在 GitLab 命名空间树中的位置上有所不同。
模式 A — 顶级组 + can_create_group 用户 PAT
- admin 用户 PAT — 创建
acme;由于该用户是创建者,因此会成为 Owner。 - 影响范围 — 该用户在整个实例范围内拥有的每个组。
模式 B — umbrella 的子组 + 在 umbrella 上拥有 Owner 权限的 admin 用户 PAT
- admin 用户 PAT — 该用户是
umbrella的直接 Owner,因此可以在其下创建子组,并在这些子组上生成每租户 GAT。创建 GAT 要求具备直接 Owner 成员资格;Group Access Token 无法满足此要求(请参阅下方侧栏)。 - 影响范围 — 仅限 umbrella 子树。
为什么不在 umbrella 上使用 Group Access Token (GAT)? GAT 属于一个组机器人用户,GitLab 会将其限制在发行该令牌的组中。 该机器人可以创建子组(具有 Maintainer 权限即可),但无法在这些子组上 生成 GAT:GAT 创建端点要求具备直接 Owner 成员资格,组机器人无法作为成员 添加到其他组(
HTTP 400 — project bots cannot be added to other groups), 组共享也无法满足直接 Owner 检查。 因此,模式 B 使用一个普通用户身份,将其一次性添加为 umbrella 的 Owner,然后由 该用户生成每租户子组 GAT。
该 Task 不会在参数解析时验证 admin 身份类型。它会调用 GitLab API,并在 admin 缺少所需权限时直接呈现 GitLab 返回的原始错误。这使 Task 保持简单——GitLab 是唯一有权决定 admin 身份能够执行哪些操作的机构。
三路径 GAT 生命周期
每个 TaskRun 都会根据现有租户 GAT 状态和输入参数,在以下三条路径中做出选择:
- 就地轮换。输入未发生变化,并且在
tenantGroup找到了健康的现有 GAT,其名称与connector-<connector-namespace>-<connector-name>匹配。Task 会调用POST /groups/:id/access_tokens/:token_id/rotate,并将expires_at设置为今天 +tokenDuration天(GitLab 16.6 或更高版本)。GitLab 会以原子方式使旧令牌值失效并返回一个新值,同时就地更新租户 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 的轮换端点会返回400 invalid_grant,因此 Task 会自动回退到重新创建路径。TaskRun 会报告Succeeded。无需操作员手动干预。how-to 中的运维手册介绍了应如何设置告警,以检测错过的轮换窗口。
下面的决策树总结了这三条路径:
租户侧资源
TaskRun 成功后,集群中会包含:
- 类型为
connectors.cpaas.io/gitlab-pat-auth的 Secret,位于 Connector 命名空间中,其中data.token携带最新的 GAT 值,data.username设置为 GAT 的名称。 - 类别为
gitlab的 Connector,位于同一命名空间中,其中spec.address指向 GitLab 实例,spec.auth.name设置为patAuth,并且spec.auth.secretRef.name指向上述 Secret。
任何命名空间中的租户工作负载都可以通过现有的 gitconfig 和 gitlabconfig 配置使用此 Connector——这与手动创建的 GitLab Connector 所公开的资源面相同。有关租户侧挂载模式,请参阅 GitLab Connector;有关租户侧示例,请参阅将 GitLab CLI (glab) 与 GitLab Connector 配合使用指南。
可选:用于跨集群应用的 kubeconfig Workspace
Task 还支持可选的 kubeconfig workspace。绑定后,应用步骤会从 workspace 导出 KUBECONFIG,并针对该集群应用租户 Connector 和 Secret,而不是使用集群内的 ServiceAccount 上下文。以下情况可以使用此功能:
- 管理命名空间运行在控制平面集群上,但租户 Connector 应部署到单独的业务集群。
- 希望对本地 SA 实施更严格的 RBAC——
kubeconfigworkspace 可以携带一个不同的身份,并将其权限范围限定为 Connector 命名空间。
workspace 可以通过包含 kubeconfig 的 Kubernetes Secret 提供,也可以通过 Connectors CSI 从 kubernetes 类 Connector 提供:
未绑定 workspace 时,应用步骤会使用集群内的 ServiceAccount 上下文;该 SA 需要具备在 Connector 命名空间中创建 Secret 和 Connector 的 RBAC 权限。
延伸阅读
- 使用 Tekton 自动创建 GitLab 租户组和 Connector — 完整操作指南,其中包含 Pattern A、Pattern B、就地轮换、重新创建以及过期回退冒烟测试的 TaskRun 示例。
gitlab-connector-automatic-creationTask 参考 — 完整的参数、workspace 和结果参考。