快速开始

本文档将帮助您快速了解如何创建 GitLab Connector，并使用它安全地克隆仓库及执行 GitLab 操作，而无需直接处理凭据。

预计阅读时间

15 分钟

前提条件

已安装 Connectors 系统（包括 ConnectorsCore 和 ConnectorsGitLab 组件）的 Kubernetes 集群。有关安装这些组件的详细信息，请参阅安装指南。
已配置 kubectl 以与您的集群通信
拥有有效的 GitLab 私有访问令牌（Private Access Token，PAT）的 GitLab 仓库
具备 Kubernetes 资源的基础知识

流程概览

序号	操作步骤	说明
1	创建 Namespace	创建一个专用的命名空间用于演示
2	创建 GitLab 凭据和 Connector	设置用于访问 GitLab 的凭据和连接器
3	创建 Clone Job	部署一个使用连接器克隆仓库的 Job
4	验证操作	检查仓库是否成功克隆

操作步骤

步骤 1：创建 Namespace

为本次演示创建一个专用的命名空间：

kubectl create ns gitlab-connector-demo

步骤 2：创建 GitLab 凭据和 Connector

创建包含 GitLab 私有访问令牌的 Secret 和 GitLab Connector 资源。有关创建和配置连接器的详细信息，请参阅Connectors 快速开始指南。

cat <<EOF | kubectl apply -f -
kind: Secret
apiVersion: v1
metadata:
  name: gitlab-secret
  namespace: gitlab-connector-demo
type: connectors.cpaas.io/gitlab-pat-auth
stringData:
  token: glpat-xxxxxxxxxxxxxxxxxxxx  # 替换为您的 GitLab 私有访问令牌
---
apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: gitlab-connector
  namespace: gitlab-connector-demo
spec:
  connectorClassName: gitlab
  address: https://gitlab.com  # 替换为您的 GitLab 服务器地址
  auth:
    name: patAuth
    secretRef:
      name: gitlab-secret
EOF

重要说明：

Secret 类型必须为 connectors.cpaas.io/gitlab-pat-auth
对于 GitLab.com，地址使用 https://gitlab.com
对于自托管 GitLab，使用您的 GitLab 服务器 URL（例如 https://gitlab.example.com）
address 应为用于仓库克隆的 GitLab 服务器 URL，而非 API 地址

验证连接器状态是否为“Ready”：

kubectl get connector gitlab-connector -n gitlab-connector-demo

输出应显示：

NAME               CLASS    ADDRESS              READY   AGE
gitlab-connector   gitlab   https://gitlab.com   True    1m

步骤 3：创建 Clone Job

创建一个 Job，使用连接器通过 Git CLI 克隆 GitLab 仓库：

cat <<EOF | kubectl apply -f -
apiVersion: batch/v1
kind: Job
metadata:
  name: gitlab-git-clone
  namespace: gitlab-connector-demo
spec:
  template:
    spec:
      restartPolicy: Never
      containers:
      - name: git
        image: bitnami/git
        imagePullPolicy: IfNotPresent
        command:
        - "sh"
        args:
        - "-c"
        - |
          set -ex
          cp /opt/git/.gitconfig /root/
          chmod 644 /root/.gitconfig

          git clone --progress https://<your-gitlab-server>/<your-group>/<your-repo>.git /tmp/demo
          echo "git clone done"
        volumeMounts:
        - name: gitconfig
          mountPath: /opt/git
      volumes:
      - name: gitconfig
        csi:
          readOnly: true
          driver: connectors-csi
          volumeAttributes:
            connector.name: "gitlab-connector"
            configuration.names: "gitconfig"
EOF

请将 https://<your-gitlab-server>/<your-group>/<your-repo>.git 替换为您实际的 GitLab 仓库 URL。

关键参数说明：

connector.name：您的 GitLab 连接器名称
configuration.names：设置为 "gitconfig" 用于挂载 Git 配置文件
mountPath：将配置挂载到 /opt/git，并复制到 /root/ 供 Git 使用

步骤 4：验证操作

查看 Job 日志，确认仓库是否成功克隆：

kubectl logs -f job/gitlab-git-clone -n gitlab-connector-demo

您应看到 Git 克隆操作成功完成且无认证错误，输出示例如下：

+ git clone --progress https://<your-gitlab-server>/<your-group>/<your-repo>.git /tmp/demo
Cloning into '/tmp/demo'...
remote: Enumerating objects: 123, done.
remote: Counting objects: 100% (123/123), done.
remote: Compressing objects: 100% (89/89), done.
remote: Total 123 (delta 34), reused 123 (delta 34), pack-reused 0
Receiving objects: 100% (123/123), 45.67 KiB | 1.23 MiB/s, done.
Resolving deltas: 100% (34/34), done.
+ echo 'git clone done'
git clone done

工作原理

GitLab Connector 的工作流程：

将原始 GitLab 仓库 URL 替换为代理服务 URL
在请求代理服务时注入认证信息（K8S API Token）
代理服务在转发请求到 GitLab 服务器时添加所需凭据（连接器的 Secret）
对于 Git 操作，.gitconfig 文件包含 URL 重写规则和认证头信息

查看生成的配置：

cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Pod
metadata:
  name: inspect-gitlab-config
  namespace: gitlab-connector-demo
spec:
  restartPolicy: Never
  containers:
  - name: inspect
    image: bitnami/git
    command: ["sleep", "3600"]
    volumeMounts:
    - name: gitconfig
      mountPath: /opt/gitlab
  volumes:
  - name: gitconfig
    csi:
      readOnly: true
      driver: connectors-csi
      volumeAttributes:
        connector.name: "gitlab-connector"
        configuration.names: "gitconfig"
EOF

查看生成的 Git 配置：

kubectl exec -it inspect-gitlab-config -n gitlab-connector-demo -- cat /opt/gitlab/.gitconfig

示例输出：

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

该配置：

添加了包含编码后的 K8S API Token 的 Authorization 头
将 GitLab URL 重写为代理服务地址

故障排查

如果克隆操作失败，请检查以下内容：

连接器状态：确保连接器处于“Ready”状态：

kubectl describe connector gitlab-connector -n gitlab-connector-demo

私有访问令牌：确认您的 GitLab PAT 拥有必要权限：
- 克隆操作需要 read_repository 权限
Job 配置：
- 确认卷挂载路径正确
- 验证仓库 URL 是否匹配您的 GitLab 仓库
- 检查 .gitconfig 文件是否正确复制到 /root/
网络连通性：确保集群能够访问 GitLab 服务器

后续步骤

成功使用 GitLab Connector 克隆第一个仓库后，您可以：

学习如何使用 GitLab CLI（glab）结合连接器与 GitLab 交互，详见使用 GitLab CLI 指南
使用 reviewdog 等自定义 CLI 工具与 GitLab 交互，详见使用 Reviewdog CLI 工具指南
将此方法集成到您的 CI/CD 流水线中，详见CI/CD 集成指南
探索GitLab ConnectorClass 概念以获取高级配置选项

#快速开始

#目录

#预计阅读时间

#前提条件

#流程概览

#操作步骤

#步骤 1：创建 Namespace

#步骤 2：创建 GitLab 凭据和 Connector

#步骤 3：创建 Clone Job

#步骤 4：验证操作

#工作原理

#故障排查

#后续步骤