Alauda DevOps Connectors Docs

Git Connector

The Git connector is a platform-agnostic connector that you can use to connect to any Git Server like GitHub, GitLab, Bitbucket.

You can use the Git Connector to securely clone private repositories in CICD pipelines, or use it in containerized workloads to perform Git operations without credentials.

Additionally, you can centralize the management of Git access configurations across namespaces, avoiding the need to repeat the configuration of Git credentials in each namespace.

This document will describe:

  • Requirements for Git servers
  • How to create a Git connector based on the Git connectorclass
  • Proxy and configuration capabilities of the Git connector

TOC

Requirements for Git Servers

The Git server to be accessed must meet the following conditions:

  1. It must support HTTP/HTTPS transport protocols and is only compatible with the Git "smart HTTP" protocol mode. This mode is the standard implementation for modern Git servers, supporting efficient data transfer and authentication mechanisms.

Creating a Git Connector Based on the Git ConnectorClass

Quick Start

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: github-demo
spec:
  connectorClassName: git
  address: https://github.com
  auth:
    name: basicAuth
    params:
    - name: repository
      value: "kubernetes/website.git"

spec.connectorClassName

Constant value git.

Description

You can add description information for the Git connector through the annotations field.

  • cpaas.io/description: Description information for the Git connector.

For example:

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: github-demo
  annotations:
    cpaas.io/description: "Connect to GitHub for accessing team public repositories"

Address

spec.address specifies the access address of the Git server, for example: https://github.com. It is important to note that this address is used for cloning Git repositories, not the API address of the Git server.

Authentication

The Git connectorclass supports the following authentication types:

  • basicAuth: Username and password-based authentication (optional), corresponding credential type: kubernetes.io/basic-auth

For example:

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: github-demo
spec:
  connectorClassName: git
  address: https://github.com
  auth:
    name: basicAuth
    secretRef:
      name: github-secret

You need to create a Secret in the same namespace, for example:

apiVersion: v1
stringData:
  password: your-password
  username: your-username
kind: Secret
metadata:
  name: github-secret
type: kubernetes.io/basic-auth

If the Git server does not require authentication, you can omit the authentication information.

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: github-demo
spec:
  connectorClassName: git
  address: https://github.com
  auth:
    name: basicAuth

Authentication Parameters

To check whether the credentials are valid, you need to specify a Git repository path. The connector will use the credentials to access that repository at runtime to determine the validity of the credentials.

This authentication parameter is specified through spec.auth.params.

  • repository: Specifies the Git repository path used for authentication checks, for example org/repo.git.

For example:

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: github-demo
spec:
  connectorClassName: git
  address: https://github.com
  auth:
    name: basicAuth
    params:
    - name: repository
      value: org/repo.git
    secretRef:
      name: github-secret

Proxy and Configuration

To provide clients with the ability to access Git repositories without credentials, the Git connectorclass provides a proxy server to automatically inject authentication information.

Clients with access to the connector can use this proxy server to access Git repositories without needing to configure credentials on the client side.

To simplify usage, the Git connectorclass provides configuration information that can be mounted into Pods via CSI. In the Pod, when executing Git operations, the proxy service can be automatically used to complete Git operations.

Proxy Address

When creating a Git connector, the system will automatically create a Service for proxying access to the Git repository.

The system will record the proxy address in the status.proxy.httpAddress field.

For example:

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: github-demo
spec:
  # . . .
status:
  conditions:
  # . . .
  proxy:
    httpAddress:
      url: http://c-github-demo.default.svc.cluster.local

Configuration

The Git connector created based on the Git connectorclass provides the following configuration:

gitconfig: Git configuration information.

  • Provides a .gitconfig configuration file, in which the Git repository address will be replaced with the proxy address. Combined with the connector-csi-driver, this configuration file will be mounted into the Pod, allowing access to the Git repository through the proxy without needing to configure credentials on the client side.

Example of the configuration file generated in the Pod:

[http]
    extraHeader = Authorization: Basic <base64 encoded token of the service account>
[url "http://c-github-demo.default.svc"]
    insteadOf = https://github.com

More usage cases can be referenced in Using Git Connector in Clone Job.

More