GitLab 连接器

GitLab connector 是一种专用连接器,可用于连接到 GitLab Server(包括 GitLab.com 和自托管实例)。

你可以使用 GitLab Connector 在 CI/CD pipeline 中安全地克隆私有仓库,使用 GitLab CLI(glab)执行高级操作,或者在容器化 workload 中使用自定义 CLI 工具与 GitLab 交互,而无需直接处理凭据。

此外,你还可以跨 namespace 集中管理 GitLab 访问配置,避免在每个 namespace 中重复配置 GitLab 凭据。

注意:

  • GitLab connector 同时支持 GitLab.com 和自托管 GitLab 实例。
  • GitLab connector 支持使用 CLI 工具(Git CLI、GitLab CLI 和自定义 CLI 工具)与 GitLab 交互。

本文将介绍:

  • GitLab Server 的要求
  • 如何基于 GitLab connectorClass 创建 GitLab connector
  • GitLab connector 的代理和配置能力

GitLab Server 和 GitLab CLI(glab)的要求

要访问的 GitLab Server 必须满足以下条件:

  1. 它必须支持 HTTP/HTTPS 传输协议,并且仅兼容 Git 的“smart HTTP”协议模式。该模式是现代 Git Server 的标准实现,支持高效的数据传输和认证机制。

  2. 对于使用 GitLab CLI(glab)时的 GitLab API 操作,GitLab Server 必须满足 glab CLI 的版本要求。更多详情:GitLab CLI(glab)版本要求

基于 GitLab ConnectorClass 创建 GitLab Connector

快速开始

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: gitlab-demo
spec:
  connectorClassName: gitlab
  address: https://gitlab.com
  auth:
    name: patAuth
    secretRef:
      name: gitlab-secret

spec.connectorClassName

固定值 gitlab。

说明

你可以通过 annotations 字段为 GitLab connector 添加描述信息。

  • cpaas.io/description:GitLab connector 的描述信息。

例如:

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: gitlab-demo
  annotations:
    cpaas.io/description: "Connect to GitLab for accessing team repositories"

地址

spec.address 用于指定 GitLab Server 的访问地址。

重要:该地址用于仓库克隆,而不是 GitLab Server 的 API 地址。使用 GitLab CLI(glab)时,connector 会自动在该地址后追加 /api/v4 来构造 API 地址。

示例:

  • 对于 GitLab.com:https://gitlab.com
  • 对于自托管实例:https://gitlab.example.com

认证

GitLab connector 支持以下认证类型:

  • patAuth:Private Access Token 认证(可选),对应的 secret 类型为:connectors.cpaas.io/gitlab-pat-auth

使用 Private Access Token 认证

Private Access Token(PAT)是 GitLab 推荐的认证方式。它提供细粒度访问控制,并且无需更改密码即可轻松撤销。

例如:

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: gitlab-demo
spec:
  connectorClassName: gitlab
  address: https://gitlab.com
  auth:
    name: patAuth
    secretRef:
      name: gitlab-secret

你需要在相同 namespace 中创建一个 Secret,例如:

apiVersion: v1
kind: Secret
metadata:
  name: gitlab-secret
type: connectors.cpaas.io/gitlab-pat-auth
stringData:
  token: glpat-xxxxxxxxxxxxxxxxxxxx  # Your GitLab Private Access Token

注意:secret 类型必须是 connectors.cpaas.io/gitlab-pat-auth。

创建 GitLab Private Access Token

有关如何在 GitLab 中创建 Personal Access Token 的详细说明,请参阅官方文档:{your-gitlab-server}/help/user/profile/personal_access_tokens.md#create-a-personal-access-token

必需的 Token Scope:

创建 token 时,请根据需要选择以下 scope:

  • read_repository:克隆仓库所必需
  • write_repository:如果你希望向仓库推送更改,则推送更改所必需
  • api:GitLab API 操作所必需,例如列出 projects、branches、merge requests 等

安全最佳实践:

出于安全最佳实践的考虑,我们建议使用最小所需权限创建 token。当需要额外权限时,请创建具有更高权限 token 的独立 Connector,并使用 namespace 隔离来控制哪些用户可以访问每个 Connector。

无需认证使用

如果 GitLab Server 不需要认证(例如公共仓库),你可以省略 secretRef 字段:

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: gitlab-demo
spec:
  connectorClassName: gitlab
  address: https://gitlab.com
  auth:
    name: patAuth

代理和配置

为了让客户端能够访问 GitLab Server 而无需直接处理凭据,GitLab ConnectorClass 提供了一个会自动注入认证信息的代理服务。

具有该 connector 访问权限的客户端可以使用此代理服务访问 GitLab Server,而无需在客户端侧配置凭据。

为了简化使用,GitLab ConnectorClass 提供了可通过 CSI Driver 挂载到 Pod 中的配置文件。当在 Pod 中执行 Git CLI、GitLab CLI(glab)或自定义 CLI 操作时,这些配置会自动将请求路由到代理服务。

代理地址

创建 GitLab connector 时,系统会自动创建一个用于代理访问 GitLab repository 的 Service。

系统会将代理地址记录在 status.proxy.httpAddress 字段中。

例如:

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: gitlab-demo
spec:
  # . . .
status:
  conditions:
  # . . .
  proxy:
    httpAddress:
      url: http://c-gitlab-demo.default.svc.cluster.local

配置

GitLab connector 提供以下配置:

  • gitconfig:用于 Git CLI 操作的 Git 配置文件
  • gitlabconfig:用于 GitLab CLI(glab)操作的配置文件

该 connector 还会继承 connectors-csi 提供的系统内置配置。更多详情请参阅:Connectors System 内置配置

gitconfig

用于 Git CLI 操作的 Git 配置文件。

  • 提供一个 .gitconfig 文件,其中 GitLab Server 地址会被重写为使用代理地址
  • 与 connectors-csi-driver 结合使用时,此文件会被挂载到 Pod 中
  • 允许通过代理访问 GitLab Server,而无需在客户端侧配置凭据

Pod 中生成的 .gitconfig 文件示例:

[http "http://c-gitlab-demo.default.svc"]
    extraHeader = Authorization: Basic OmV5Smhixxxxxxxxx==
[url "http://c-gitlab-demo.default.svc"]
    insteadOf = https://gitlab.com

工作原理:

  1. 作用域为 URL 的 [http "<proxy address>"] 部分会添加一个 Authorization header,使用 Kubernetes API server token(用于请求 GitLab connector 代理服务的临时 token);该 header 仅发送到代理地址,因此不会影响其他主机上的请求(例如托管在不同 git server 上的 submodule)
  2. [url] 部分会将 GitLab Server 地址重写为使用代理服务
  3. 当 Git CLI 执行操作时,会自动使用这些设置

使用方式:

要在 Pod 中使用 gitconfig 配置:

  1. 使用 CSI driver 挂载配置,并设置 configuration.names: "gitconfig"
  2. 将 .gitconfig 文件复制到用户的 home directory(通常为 /root/)
  3. 将 .gitconfig 文件权限设置为 644
  4. Git CLI 将自动在所有操作中使用此配置

CSI volume 配置示例:

volumes:
- name: gitconfig
  csi:
    readOnly: true
    driver: connectors-csi
    volumeAttributes:
      connector.name: "gitlab-demo"
      configuration.names: "gitconfig"

完整使用示例请参阅:快速开始指南

gitlabconfig

用于 GitLab CLI(glab)操作的配置文件。

  • 提供一个供 GitLab CLI(glab)使用的 config.yml 配置文件
  • 包含 GitLab Server 信息、认证 token 和 API endpoints
  • 使 glab 命令无需手动配置即可工作

Pod 中生成的配置文件示例:

git_protocol: http
host: c-gitlab-demo.default.svc.cluster.local
no_prompt: true
telemetry: false
hosts:
  c-gitlab-demo.default.svc.cluster.local:
    token: k8s-api-token-xxxxxxxx
    container_registry_domains: c-gitlab-demo.default.svc.cluster.local,c-gitlab-demo.default.svc.cluster.local:443,registry.c-gitlab-demo.default.svc.cluster.local
    api_host: c-gitlab-demo.default.svc.cluster.local
    git_protocol: http
    api_protocol: http
    user: any-user

工作原理:

  1. 该配置指示 glab 使用代理服务
  2. token 由 Kubernetes API server 提供(用于请求 GitLab connector 代理服务的临时 token)
  3. HTTP 和 API 协议都配置为使用代理,由代理将认证信息注入到后端请求中

使用方式:

要在 Pod 中使用 gitlabconfig 配置:

  1. 使用 CSI driver 挂载配置,并设置 configuration.names: "gitlabconfig"
  2. 将 config.yml 文件复制到 ~/.config/glab-cli/
  3. 为安全起见,将文件权限设置为 600
  4. GitLab CLI(glab)将自动在所有操作中使用此配置

CSI volume 配置示例:

volumes:
- name: gitlab-config
  csi:
    driver: connectors-csi
    readOnly: true
    volumeAttributes:
      connector.name: "gitlab-demo"
      configuration.names: "gitlabconfig"

有关使用 glab 命令的完整示例,请参阅:使用 GitLab CLI(glab)

同时使用多个配置

你可以在同一个 Pod 中挂载多个配置,只需在 configuration.names 字段中用逗号分隔它们:

volumeAttributes:
  connector.name: "gitlab-demo"
  configuration.names: "gitlabconfig,gitconfig"

这使你能够在同一个 Pod 中同时使用 Git CLI 和 GitLab CLI(glab)操作。有关实际示例,请参阅:

使用系统内置配置

挂载 gitlab connector 时,可以使用以下内置配置文件:

  • context.token:用于 GitLab 认证的 Private Access Token
  • connector.status.proxyAddress:代理服务地址

这些文件适用于需要直接访问认证 token 或代理地址的自定义集成或 CLI 工具。

有关使用内置配置的完整示例,请参阅:在 GitLab Connector 中使用 Reviewdog

有关系统内置配置的更多详情,请参阅:Connectors-CSI 内置配置

延伸阅读