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 connector supports the following authentication types:

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

Using Basic Authentication

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

Note: The password field is not restricted to actual user passwords. You can use other types of credentials such as Personal Access Tokens (PAT) or API keys, as long as they meet the permission requirements outlined in the Secret Permissions Required section.

If the Git server does not require authentication, you can omit the secretRef field:

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

Credential Permissions Required

The required permissions for the configured credential depend on how you intend to use it in your Pods/Pipelines. Additionally, the credential must have clone permissions for the authentication repository specified in the Authentication Parameters section.

For example:

  • If you need to perform both clone and push operations in pipelines using this connector, the credential must have both clone and push permissions for the target repository. In other words, the credential should allow you to both clone from and push to the repository.
  • If you only need to clone repositories in pipelines, the credential only requires clone permissions for the target repository.

For security best practices, we recommend creating credential with minimal required permissions. When privileges are needed, create separate Connectors with more privileged secret and use namespace isolation to control which users can access each Connector.

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