快速开始

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

预计阅读时间

15 分钟

先决条件

  • 已安装 Connectors 系统(ConnectorsCore 和 ConnectorsGitLab 组件)的 Kubernetes 集群。有关安装这些组件的详细信息,请参阅 安装指南。
  • 已配置可与您的集群通信的 kubectl
  • 具有有效 Private Access Token (PAT) 的 GitLab 仓库
  • 具备 Kubernetes 资源的基础知识

流程概览

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

操作步骤

步骤 1:创建命名空间

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

kubectl create ns gitlab-connector-demo

步骤 2:创建 GitLab 凭据和连接器

创建包含 GitLab Private Access Token 的 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  # Replace with your GitLab Private Access Token
---
apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: gitlab-connector
  namespace: gitlab-connector-demo
spec:
  connectorClassName: gitlab
  address: https://gitlab.com  # Replace with your GitLab server address
  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:创建克隆 Job

创建一个使用该连接器并通过 Git CLI 克隆 GitLab 仓库的 Job:

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 连接器的工作方式如下:

  1. 将原始 GitLab 仓库 URL 替换为代理服务 URL
  2. 向发送到代理服务的请求中注入认证信息(K8S API 令牌)
  3. 代理服务在将请求转发到 GitLab 服务器时添加所需的凭据(连接器的 Secret)
  4. 对于 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 "http://c-gitlab-connector.gitlab-connector-demo.svc"]
    extraHeader = Authorization: Basic OmV5Smhixxxxxxxxx==
[url "http://c-gitlab-connector.gitlab-connector-demo.svc"]
    insteadOf = https://gitlab.com

此配置:

  • 添加一个带有编码后的 K8S API 令牌的 Authorization 请求头,并且仅应用于发送到代理服务地址的请求
  • 重写 GitLab URL 以使用代理服务

故障排查

如果克隆操作失败,请检查以下内容:

  1. 连接器状态:确保连接器处于 "Ready" 状态:

    kubectl describe connector gitlab-connector -n gitlab-connector-demo
  2. Private Access Token:验证您的 GitLab PAT 是否具有必要的权限:

    • 克隆操作需要 read_repository scope
  3. Job 配置:

    • 确保卷挂载路径正确
    • 验证仓库 URL 与您的 GitLab 仓库匹配
    • 检查 .gitconfig 文件是否已正确复制到 /root/
  4. 网络连通性:确保您的集群可以访问 GitLab 服务器

后续步骤

成功使用 GitLab 连接器克隆第一个仓库后,您可以: