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。
  • 在集群上落地一个租户 gitlab Connector,以及一个类别为 connectors.cpaas.io/gitlab-pat-auth 的匹配身份验证 Secret。

重新运行相同的 TaskRun 是幂等的:输入未更改时,会原地轮换 GAT;影响身份的输入发生更改时,会触发受控重新创建;已过期的 GAT 会自动恢复 (可自行修复错过的轮换)。

Admin 凭证如何保留在挂载中

Task 绝不会将原始 admin PAT 或 GAT 读入 Pod 环境。 相反,admin 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 指向 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 子树。
方面模式 A模式 B
admin Connector 凭证用户 PAT用户 PAT(Group Access Token 不起作用——请参阅下方说明)
tenantGroup 结构顶级路径(acme)子组路径(umbrella/acme)
GitLab 用户是否带有 elevated 标志?是 — can_create_group否(但必须是 umbrella 的直接 Owner)
推荐使用场景全新搭建的自托管 GitLab具有 umbrella 组的组织 / SaaS GitLab
泄露后的影响范围该用户拥有的每个组仅限 umbrella 子树
是否适用于 GitLab.com SaaS是(任何用户都可以创建顶级组)是

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

  1. 就地轮换。输入未发生变化,并且在 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 会记录轮换时间戳。
  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 的轮换端点会返回 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——kubeconfig workspace 可以携带一个不同的身份,并将其权限范围限定为 Connector 命名空间。

workspace 可以通过包含 kubeconfig 的 Kubernetes Secret 提供,也可以通过 Connectors CSI 从 kubernetes 类 Connector 提供:

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

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

延伸阅读