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。
  • 在集群中生成一个租户 gitlab Connector + 匹配的认证 Secret,类型为 connectors.cpaas.io/gitlab-pat-auth。

重新运行同一个 TaskRun 是幂等的:未变化的输入会就地轮换 GAT;影响身份的输入变更会触发受控的重新创建;已过期的 GAT 会自动恢复(在错过轮换时实现自愈)。

管理员凭证如何保留在挂载中

Task 从不会将原始管理员 PAT 或 GAT 读取到 Pod 环境变量中。 相反,管理员 Connector 通过 Connectors CSI 被消费:

workspaces:
  - name: gitlabconfig
    csi:
      driver: connectors-csi
      readOnly: true
      volumeAttributes:
        connector.name: gitlab-admin
        configuration.names: gitlabconfig

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 子树。
方面模式 A模式 B
管理员 Connector 凭证User PATUser PAT(Group Access Token 无法工作——见下方说明)
tenantGroup 形状顶层路径(acme)Subgroup 路径(umbrella/acme)
具有提升标志的 GitLab 用户?是 — can_create_group否(但必须是 umbrella 的直接 Owner)
推荐用于新建自建 GitLab具有 umbrella group 的组织 / GitLab SaaS
一旦泄露的影响范围该用户拥有的每个 group仅 umbrella 子树
在 GitLab.com SaaS 上可用是(任何用户都可以创建顶层 group)是

为什么 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 状态和输入参数,在三条路径中选择其一:

  1. 就地轮换。 输入未变化,并且在 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 会记录轮换时间戳。
  2. 重新创建。 影响身份的输入发生了变化(scopes、accessLevel 或 subgroups[] 集合)。Task 会撤销现有 GAT(DELETE /groups/:id/access_tokens/:token_id),并按请求属性签发一个新的 GAT;租户 Secret 会被重写;注解 connectors.cpaas.io/gat-recreated-at 会记录重新创建时间戳。
  3. 过期后回退。 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——kubeconfig workspace 可以携带一个不同的身份,仅作用于 connector 命名空间。

该 workspace 可以通过包含 kubeconfig 的 Kubernetes Secret 提供,也可以通过来自 kubernetes class Connector 的 Connectors CSI 提供:

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

当 workspace 未绑定时,apply 步骤使用集群内的 ServiceAccount 上下文;该 SA 需要具备在 connector 命名空间中创建 Secret 和 Connector 的 RBAC 权限。

延伸阅读