#GitLab 连接器

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

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

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

注意：

• GitLab connector 同时支持 GitLab.com 和自托管的 GitLab 实例。
• GitLab connector 支持使用 CLI tools（Git CLI、GitLab CLI 和自定义 CLI tools）与 GitLab 交互。

本文将介绍：

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

#GitLab Server 和 GitLab CLI (glab) 的要求

要访问的 GitLab server 必须满足以下条件：

1. 必须支持 HTTP/HTTPS transport protocols，并且仅兼容 Git 的 "smart HTTP" protocol mode。该模式是现代 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: "连接到 GitLab 以访问团队 repository"

#Address

spec.address 指定 GitLab server 的访问地址。

重要：此地址用于 repository cloning，而不是 GitLab server 的 API 地址。在使用 GitLab CLI (glab) 时，connector 会自动在此地址后追加 /api/v4 来构造 API 地址。

示例：

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

#Authentication

GitLab connector 支持以下认证类型：

• patAuth：Private Access Token 认证（可选），对应的 secret type：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 type 必须是 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 范围：

创建 token 时，请根据需要选择以下范围：

• read_repository：克隆 repository 所必需
• write_repository：如果你希望向 repository 推送变更，则推送变更所必需
• api：执行 GitLab API 操作所必需，例如列出项目、列出分支、列出 merge requests 等

安全最佳实践：

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

#无需认证使用

如果 GitLab server 不需要认证（例如公共 repository），可以省略 secretRef 字段：

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

#Proxy 和 Configuration

为了让客户端能够访问 GitLab server 而无需直接处理凭据，GitLab ConnectorClass 提供了一个 proxy server，它会自动注入认证信息。

有权限访问该 connector 的客户端可以使用这个 proxy server 访问 GitLab server，而无需在客户端侧配置凭据。

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

#Proxy Address

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

系统会将 proxy address 记录在 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 地址会被重写为使用 proxy address
• 与 connectors-csi-driver 结合使用时，该文件会被挂载到 Pod 中
• 使其能够通过 proxy 访问 GitLab server，而无需在客户端侧配置凭据

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

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

工作原理：

1. [http] 部分会添加一个 Authorization header，其中包含 Kubernetes API server token（用于发送到 GitLab connector proxy service 请求的临时 token）
2. [url] 部分会将 GitLab server 地址重写为使用 proxy service
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"

完整使用示例请参见：Quick Start Guide

#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 使用 proxy service
2. token 由 Kubernetes API server 提供（用于发送到 GitLab connector proxy service 请求的临时 token）
3. HTTP 和 API protocol 都会配置为使用 proxy，proxy 会将认证信息注入到后端请求中

使用方式：

要在 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 命令的完整使用示例，请参见：Using GitLab CLI (glab)

#同时使用多个配置

你可以在同一个 Pod 中挂载多个配置，只需在 configuration.names 字段中用逗号分隔即可：

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

这使你可以在同一个 Pod 中同时使用 Git CLI 和 GitLab CLI (glab) 操作。实际示例请参见：

• Using GitLab CLI (glab) - 使用 glab 克隆 repository

#使用系统内置配置

挂载 gitlab connector 时，可用以下内置配置文件：

• context.token：用于 GitLab 认证的 Private Access Token
• connector.status.proxyAddress：proxy service 地址

这些文件适用于需要直接访问认证 token 或 proxy address 的自定义集成或 CLI tools。

完整的内置配置使用示例请参见：Using Reviewdog with GitLab Connector

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

#延伸阅读

• Quick Start Guide - 快速开始使用 GitLab Connector
• Using GitLab CLI (glab) - 了解如何通过该 connector 使用 glab
• Using Reviewdog - 了解如何使用 reviewdog 等自定义 CLI tools 与 GitLab 交互
• CI/CD Integration - 在 CI/CD pipeline 中使用