GitLab Connector

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) Version Requirements

基于 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:

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

  • read_repository:克隆仓库所需
  • write_repository:如果您希望向仓库推送更改,则推送更改所需
  • api:执行 GitLab API 操作所需,例如列出 project、列出 branch、列出 merge request 等

安全最佳实践:

出于安全最佳实践,我们建议创建仅包含最小必要权限的令牌。当需要额外权限时,请创建具有更高权限令牌的独立 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 Built-in Configurations

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 令牌(一个用于访问 GitLab connector 代理服务的临时令牌);该 header 只会发送到代理地址,因此不会影响其他 host 的请求(例如托管在其他 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 信息、认证令牌和 API endpoint
  • 使 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. 令牌由 Kubernetes API server 提供(一个用于访问 GitLab connector 代理服务的临时令牌)
  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)

同时使用多个配置

您可以通过在 configuration.names 字段中使用逗号分隔多个配置,在同一个 Pod 中挂载多个配置:

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:代理服务地址

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

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

有关系统内置配置的更多详情,请参见:Connectors-CSI Built-in Configurations

延伸阅读