快速开始

本文档将帮助你快速了解如何创建 GitLab Connector,并将其用于安全克隆仓库以及执行 GitLab 操作,而无需直接处理凭据。

预计阅读时间

15 分钟

前提条件

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

流程概览

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

操作步骤

步骤 1:创建 Namespace

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

kubectl create ns gitlab-connector-demo

步骤 2:创建 GitLab 凭据和 Connector

同时创建包含 GitLab Private Access Token 的 Secret 和 GitLab Connector 资源。有关创建和配置 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 地址

验证 connector 处于“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

创建一个使用 Connector 通过 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 connector 的名称
  • configuration.names:设置为 "gitconfig" 以挂载 Git 配置文件
  • mountPath:将配置挂载到 /opt/git,并复制到 /root/ 供 Git 使用

步骤 4:验证操作

检查 Job 的日志,确认仓库已成功克隆:

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

你应该看到 Git clone 操作成功完成,且没有任何身份验证错误。输出应包含:

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

  1. 将原始 GitLab 仓库 URL 替换为代理服务 URL
  2. 向发送到代理服务的请求中注入身份验证信息(K8S API 令牌)
  3. 代理服务在将请求转发到 GitLab 服务器时添加所需的凭据(Connector 的 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. Connector 状态:确保 connector 处于“Ready”状态:

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

    • 克隆需要 read_repository 范围
  3. Job 配置:

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

下一步

在使用 GitLab Connector 成功克隆第一个仓库后,你可以: