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 ConnectorClass 创建 GitLab Connector快速开始spec.connectorClassName描述地址认证使用 Private Access Token 认证创建 GitLab Private Access Token无需认证使用代理和配置代理地址配置gitconfiggitlabconfig同时使用多个配置使用系统内置配置延伸阅读GitLab Server 和 GitLab CLI (glab) 的要求
要访问的 GitLab server 必须满足以下条件:
-
必须支持 HTTP/HTTPS 传输协议,并且仅兼容 Git 的 "smart HTTP" 协议模式。该模式是现代 Git server 的标准实现,支持高效的数据传输和认证机制。
-
在使用 GitLab CLI(glab)执行 GitLab API 操作时,GitLab server 必须满足 glab CLI 的版本要求。更多详情请参见:GitLab CLI (glab) Version Requirements
基于 GitLab ConnectorClass 创建 GitLab Connector
快速开始
spec.connectorClassName
固定值 gitlab。
描述
您可以通过 annotations 字段为 GitLab connector 添加描述信息。
cpaas.io/description:GitLab connector 的描述信息。
例如:
地址
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 推荐的认证方式。它提供细粒度的访问控制,并且可以在不更改密码的情况下轻松吊销。
例如:
您需要在同一 namespace 中创建一个 Secret,例如:
注意: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 字段:
代理和配置
为了让客户端能够访问 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 字段中。
例如:
配置
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 文件示例:
工作原理:
- URL 作用域的
[http "<proxy address>"]段会添加一个 Authorization header,其中包含 Kubernetes API server 令牌(一个用于访问 GitLab connector 代理服务的临时令牌);该 header 只会发送到代理地址,因此不会影响其他 host 的请求(例如托管在其他 git server 上的 submodule) [url]段会将 GitLab server 地址重写为使用代理服务- 当 Git CLI 执行操作时,会自动使用这些设置
使用方法:
要在 Pod 中使用 gitconfig 配置:
- 使用 CSI driver 挂载配置,并设置
configuration.names: "gitconfig" - 将
.gitconfig文件复制到用户的 home directory(通常为/root/) - 将
.gitconfig文件权限设置为644 - Git CLI 将自动对所有操作使用此配置
CSI volume 配置示例:
完整用法示例请参见:快速开始指南
gitlabconfig
用于 GitLab CLI(glab)操作的配置文件。
- 提供一个供 GitLab CLI(glab)使用的
config.yml配置文件 - 包含 GitLab server 信息、认证令牌和 API endpoint
- 使 glab 命令无需手动配置即可工作
Pod 中生成的配置文件示例:
工作原理:
- 该配置指示 glab 使用代理服务
- 令牌由 Kubernetes API server 提供(一个用于访问 GitLab connector 代理服务的临时令牌)
- HTTP 和 API 协议都配置为使用代理,代理会向后端请求中注入认证信息
使用方法:
要在 Pod 中使用 gitlabconfig 配置:
- 使用 CSI driver 挂载配置,并设置
configuration.names: "gitlabconfig" - 将
config.yml文件复制到~/.config/glab-cli/ - 为安全起见,将文件权限设置为
600 - GitLab CLI(glab)将自动对所有操作使用此配置
CSI volume 配置示例:
有关使用 glab 命令的完整示例,请参见:使用 GitLab CLI(glab)
同时使用多个配置
您可以通过在 configuration.names 字段中使用逗号分隔多个配置,在同一个 Pod 中挂载多个配置:
这使您可以在同一个 Pod 中同时使用 Git CLI 和 GitLab CLI(glab)操作。实际示例请参见:
- 使用 GitLab CLI(glab) - 使用 glab 克隆仓库
使用系统内置配置
挂载 gitlab connector 时,可使用以下内置配置文件:
context.token:用于 GitLab 认证的 Private Access Tokenconnector.status.proxyAddress:代理服务地址
这些文件适用于需要直接访问认证令牌或代理地址的自定义集成或 CLI 工具。
有关使用内置配置的完整示例,请参见:在 GitLab Connector 中使用 Reviewdog
有关系统内置配置的更多详情,请参见:Connectors-CSI Built-in Configurations
延伸阅读
- 快速开始指南 - 开始使用 GitLab Connector
- 使用 GitLab CLI(glab) - 了解如何通过该 connector 使用 glab
- 使用 Reviewdog - 了解如何使用 reviewdog 等自定义 CLI 工具与 GitLab 交互
- CI/CD 集成 - 在 CI/CD pipeline 中使用