GitLab Connector

Коннектор GitLab — это специализированный коннектор, который можно использовать для подключения к GitLab Server (как к GitLab.com, так и к self-hosted экземплярам).

С помощью GitLab Connector можно безопасно клонировать private repositories в CI/CD pipelines, использовать GitLab CLI (glab) для выполнения расширенных операций, а также применять custom CLI tools в containerized workloads для взаимодействия с GitLab без непосредственной обработки учетных данных.

Кроме того, можно централизовать управление конфигурациями доступа к GitLab в разных namespaces, избегая необходимости повторять настройку GitLab credentials в каждом namespace.

Примечания:

GitLab connector поддерживает как GitLab.com, так и self-hosted GitLab instances.
GitLab connector поддерживает использование CLI tools (Git CLI, GitLab CLI и custom CLI tools) для взаимодействия с GitLab.

В этом документе рассматриваются:

Требования к GitLab servers
Как создать GitLab connector на основе GitLab connectorclass
Возможности proxy и configuration для GitLab connector

Содержание

Требования к GitLab Servers и GitLab CLI (glab)Создание GitLab Connector на основе GitLab ConnectorClass Quick Start spec.connectorClassName Description Address Аутентификация Использование аутентификации с Private Access Token Создание GitLab Private Access Token Использование без аутентификации Proxy и Configuration Proxy Address Configuration gitconfig gitlabconfig Использование нескольких конфигураций вместе Использование встроенных системных конфигураций Дополнительные материалы

Требования к GitLab Servers и GitLab CLI (glab)

GitLab server, к которому выполняется доступ, должен соответствовать следующим условиям:

Он должен поддерживать транспортные протоколы HTTP/HTTPS и быть совместим только с режимом Git "smart HTTP". Этот режим является стандартной реализацией для современных Git servers и поддерживает эффективную передачу данных и механизмы аутентификации.
Для операций GitLab API при использовании GitLab CLI (glab) GitLab server должен соответствовать требованиям к версии glab CLI. Подробнее: GitLab CLI (glab) Version Requirements

Создание GitLab Connector на основе GitLab ConnectorClass

Quick Start

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.

Description

Добавить информацию с описанием для GitLab connector можно через поле annotations.

cpaas.io/description: Информация с описанием для GitLab connector.

Например:

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: gitlab-demo
  annotations:
    cpaas.io/description: "Подключение к GitLab для доступа к репозиториям команды"

Address

spec.address задает адрес доступа к GitLab server.

Важно: Этот адрес используется для клонирования репозитория, а не как API address GitLab server. При использовании GitLab CLI (glab) connector автоматически сформирует API address, добавив /api/v4 к этому адресу.

Примеры:

Для GitLab.com: https://gitlab.com
Для self-hosted экземпляров: 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. Он предоставляет детализированный контроль доступа и может быть легко отозван без смены паролей.

Например:

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

Необходимо создать Secret в том же namespace, например:

apiVersion: v1
kind: Secret
metadata:
  name: gitlab-secret
type: connectors.cpaas.io/gitlab-pat-auth
stringData:
  token: glpat-xxxxxxxxxxxxxxxxxxxx  # Ваш GitLab Private Access Token

Примечание: Тип Secret должен быть connectors.cpaas.io/gitlab-pat-auth.

Создание GitLab Private Access Token

Подробные инструкции по созданию Personal Access Token в GitLab см. в официальной документации: {your-gitlab-server}/help/user/profile/personal_access_tokens.md#create-a-personal-access-token

Требуемые scopes токена:

При создании токена выберите следующие scopes в зависимости от ваших потребностей:

read_repository: требуется для клонирования репозиториев
write_repository: требуется для отправки изменений, если вы хотите выполнять push в репозиторий
api: требуется для операций GitLab API, например, для получения списка проектов, веток, merge requests и т. д.

Рекомендации по безопасности:

Для обеспечения безопасности рекомендуется создавать токены с минимально необходимыми правами. Если требуются дополнительные привилегии, создавайте отдельные Connectors с более привилегированными токенами и используйте изоляцию namespace, чтобы контролировать, какие пользователи могут обращаться к каждому Connector.

Использование без аутентификации

Если GitLab server не требует аутентификации (например, для public repositories), поле 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 servers без непосредственной обработки учетных данных, GitLab ConnectorClass предоставляет proxy server, который автоматически подставляет информацию аутентификации.

Клиенты, имеющие доступ к connector, могут использовать этот proxy server для доступа к GitLab servers без необходимости настраивать учетные данные на стороне клиента.

Для упрощения использования GitLab ConnectorClass предоставляет configuration files, которые можно смонтировать в Pods через CSI Driver. При выполнении Git CLI, GitLab CLI (glab) или custom CLI операций в Pod эти конфигурации автоматически направляют запросы через proxy service.

Proxy Address

При создании GitLab connector система автоматически создаст Service для проксирования доступа к GitLab repository.

Система запишет 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

Configuration

GitLab connector предоставляет следующие configuration:

gitconfig: файл конфигурации Git для операций Git CLI
gitlabconfig: файл конфигурации для операций GitLab CLI (glab)

Connector также наследует встроенные системные конфигурации из connectors-csi. Подробнее см.: Connectors System Built-in Configurations

gitconfig

Файл конфигурации Git для операций Git CLI.

Предоставляет файл .gitconfig, в котором адрес GitLab server переписывается для использования proxy address
При использовании вместе с connectors-csi-driver этот файл монтируется в Pod
Позволяет обращаться к GitLab server через proxy без необходимости настраивать учетные данные на стороне клиента

Пример файла .gitconfig, сгенерированного в Pod:

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

Как это работает:

Раздел [http] добавляет заголовок Authorization с токеном Kubernetes API server (временный токен, используемый для запросов к proxy service GitLab connector)
Раздел [url] переписывает адрес GitLab server для использования proxy service
Когда Git CLI выполняет операции, он автоматически использует эти настройки

Использование:

Чтобы использовать конфигурацию gitconfig в Pod:

Смонтируйте конфигурацию с помощью CSI driver, указав configuration.names: "gitconfig"
Скопируйте файл .gitconfig в домашний каталог пользователя (обычно /root/)
Установите права доступа к файлу .gitconfig 644
Git CLI будет автоматически использовать эту конфигурацию для всех операций

Пример конфигурации тома CSI:

volumes:
- name: gitconfig
  csi:
    readOnly: true
    driver: connectors-csi
    volumeAttributes:
      connector.name: "gitlab-demo"
      configuration.names: "gitconfig"

Полные примеры использования см.: Quick Start Guide

gitlabconfig

Файл конфигурации для операций GitLab CLI (glab).

Предоставляет файл config.yml для GitLab CLI (glab)
Содержит сведения о GitLab server, токен аутентификации и 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

Как это работает:

Конфигурация направляет glab на использование proxy service
Токен предоставляется Kubernetes API server (временный токен, используемый для запросов к proxy service GitLab connector)
Для протоколов HTTP и API настроено использование proxy, который подставляет информацию аутентификации во backend requests

Использование:

Чтобы использовать конфигурацию gitlabconfig в Pod:

Смонтируйте конфигурацию с помощью CSI driver, указав configuration.names: "gitlabconfig"
Скопируйте файл config.yml в ~/.config/glab-cli/
Установите права доступа к файлу 600 в целях безопасности
GitLab CLI (glab) будет автоматически использовать эту конфигурацию для всех операций

Пример конфигурации тома CSI:

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"

Это позволяет использовать операции Git CLI и GitLab CLI (glab) в одном Pod. Практические примеры см.:

Using GitLab CLI (glab) - Clone Repositories with glab

Использование встроенных системных конфигураций

При монтировании gitlab connector доступны следующие встроенные файлы конфигурации:

context.token: Private Access Token для аутентификации GitLab
connector.status.proxyAddress: адрес proxy service

Эти файлы полезны для custom integrations или CLI tools, которым требуется прямой доступ к токену аутентификации или адресу proxy.

Полный пример использования встроенных конфигураций см.: Using Reviewdog with GitLab Connector

Подробнее о встроенных системных конфигурациях см.: Connectors-CSI Built-in Configurations

Дополнительные материалы

Quick Start Guide - Начало работы с GitLab Connector
Using GitLab CLI (glab) - Узнайте, как использовать glab с connector
Using Reviewdog - Узнайте, как использовать custom CLI tools, например reviewdog, для взаимодействия с GitLab
CI/CD Integration - Использование в CI/CD pipelines

#GitLab Connector

#Содержание

#Требования к GitLab Servers и GitLab CLI (glab)

#Создание GitLab Connector на основе GitLab ConnectorClass

#Quick Start

#spec.connectorClassName

#Description

#Address

#Аутентификация

#Использование аутентификации с Private Access Token

#Создание GitLab Private Access Token

#Использование без аутентификации

#Proxy и Configuration

#Proxy Address

#Configuration

#gitconfig

#gitlabconfig

#Использование нескольких конфигураций вместе

#Использование встроенных системных конфигураций

#Дополнительные материалы

GitLab Connector

Содержание

Требования к GitLab Servers и GitLab CLI (glab)

Создание GitLab Connector на основе GitLab ConnectorClass

Quick Start

spec.connectorClassName

Description

Address

Аутентификация

Использование аутентификации с Private Access Token

Создание GitLab Private Access Token

Использование без аутентификации

Proxy и Configuration

Proxy Address

Configuration

gitconfig

gitlabconfig

Использование нескольких конфигураций вместе

Использование встроенных системных конфигураций

Дополнительные материалы