#ConnectorClass

#Overview

ConnectorClass is a cluster-level resource that defines the access modes and behavior specifications for specific types of tools.

The following example defines a hello-git type connector that supports basic authentication:

apiVersion: connectors.alauda.io/v1alpha1
kind: ConnectorClass
metadata:
  name: hello-git
spec:
  address:
    type: string  # Address in string format
  auth:
    types:
      - name: basicAuth
        secretType: kubernetes.io/basic-auth  # Using Basic Auth for authentication

In the ConnectorClass, the access modes and behavior specifications for connecting tools to the platform are defined by describing the following information:

• The format of the tool's access address
• Supported authentication methods
• How to check the tool's accessibility
• How to verify the validity of authentication
• How the tool provides API capabilities
• What configuration capabilities the tool offers
• Metadata for readability display

This document also provides examples to help readers better understand how to customize ConnectorClass. Examples

#Address Information

Address information defines the format for accessing the tool. Currently, string-type address configurations are supported. This address information restricts the field type constraints that the current type of tool must meet.

spec:
  address:
    type: string  # Currently supports only string type

At this point, it indicates that the address information for connecting the tool to the platform must be of string type.

#Authentication Information

#Authentication Type

The authentication type defines the type of credentials used for tool authentication. A tool can support multiple authentication types, allowing users to choose one when using the tool.

Users can uniquely name the current authentication type via

• spec.auth.types[].name, which must be unique and cannot be repeated.
• spec.auth.types[].secretType, which specifies the type of Secret needed for authentication, corresponding to a Kubernetes Secret Type.

Example:

spec:
  auth:
    types:
      - name: basicAuth  # Name of the authentication type
        secretType: kubernetes.io/basic-auth  # Corresponding Secret type
      - name: sshAuth
        secretType: kubernetes.io/ssh-auth

In the built-in K8S Secret Type, all types except Opaque have field constraints. When providing a Secret, the user must ensure that the Secret's fields match the type constraints.

When using the Opaque type, you must declare authentication parameters.

Like k8s, you can also use your own Secret Type. At this point, you must declare authentication parameters.

#Authentication Parameters

Parameters required for credentials during authentication are defined by spec.auth.types[].params.

For standard Kubernetes secret types with clearly defined data fields, parameters can be omitted. For example:

• kubernetes.io/basic-auth: username and password authentication
• kubernetes.io/ssh-auth: SSH key authentication

For custom authentication types, you can define the required authentication parameters, at this point secretType is marked as Opaque or a custom name.

For example, for GitLab's Personal Access Token (PAT) authentication:

spec:
  auth:
    types:
      - name: privateToken
        secretType: Opaque
        params:
          - name: username
            type: string
          - name: private-token
            type: string
      - name: oauth2
        secretType: example.com/oauth2
        params:
          - name: clientID
            type: string
          - name: clientSecret
            type: string

This definition requires that the credentials used in the tool connector include the fields specified in params.

#Optional Authentication

Some tools support access without authentication, marked by the optional field indicating whether authentication is optional:

For example, the following indicates that credentials for basicAuth are optional while sshAuth credentials are mandatory.

spec:
  auth:
    types:
      - name: basicAuth
        optional: true  # Marking authentication as optional
        secretType: kubernetes.io/basic-auth
      - name: sshAuth
        secretType: kubernetes.io/basic-auth

At this point, when connecting this type of tool to the platform, the basicAuth type of authentication can be omitted.

#Accessibility Check

Accessibility checks are used to verify if the tool can be accessed normally. The configuration of how this type is conducted is done through the livenessProbe field.

For example, the following snippet indicates that detection is performed using HTTP requests.

spec:
  livenessProbe:
    http:
      path: /

When the tool returns a 200 status, it is considered accessible.

#Authentication Checking

Authentication checking is used to verify how the validity of the authentication information for tools of this type is checked. If authentication checking is not needed, authProbes can be omitted.

For example, the following YAML indicates that during the authentication check of the tool, an http GET request will be initiated with the injected Authorization: abc header.

spec:
  authProbes:
    - authName: basicAuth  # Corresponding authentication type
      probe:
        http:
          httpHeaders:
            Authorization: abc
          path: /
          method: GET # Defaults to GET, supports both POST and GET methods
          disableRedirect: false # Defaults to false, allowing automatic redirection

• authName indicates the authentication type being used, needing to align with spec.auth.types[].name.
• During the authentication check, the address information of the connector tool will be directly used.
• spec.authProbes[].probe.http.method specifies the HTTP method used for authentication, supporting GET and POST. Defaults to GET.
• spec.authProbes[].probe.http.disableRedirect specifies whether to disable redirection during authentication. Defaults to allow automatic redirection.

#Custom Authentication Check Parameters

Some authentication checks may require additional parameters, such as specifying the repository name when checking access to a Git repository. These can be specified via spec.authProbes[].params.

spec:
  authProbes:
    - authName: basicAuth  # Corresponding authentication type
      params:
        - name: repository
          type: string

#Authentication Check Expressions

When configuring authProbes, expressions can dynamically obtain credential information or Connector information.

For example,

spec:
  authProbes:
    - authName: basicAuth  # Corresponding authentication type
      probe:
        http:
          httpHeaders:
            Authorization: {{ .Secret.StringData.token }}
          path: /
      params:
        - name: repository
          type: string

• Expressions can be used in httpHeaders and path fields.
• The expression format is go template
• Supported top-level fields are:
  • .Connector: The information of the Connector itself
  • .Secret: The Secret information used for Connector data.
• The methods available within expressions can be referenced in the sprig documentation
  • For example: b64enc: Base64 encoding for strings, trimPrefix to remove string prefixes

#Example

Basic Auth authentication checking

spec:
  authProbes:
    - authName: basicAuth
      params:
        - name: repository
          type: string
      probe:
        http:
          path: /{{- range .Connector.Spec.Auth.Params }}{{- if eq .Name "repository" }}{{ .Value.StringVal }}{{ end }}{{- end }}/info/refs?service=git-upload-pack
          httpHeaders:
          - name: Authorization
            value: >-
              {{- if .Secret }}Basic {{ printf "%s:%s" .Secret.StringData.username .Secret.StringData.password | b64enc }} {{- end }}

The connector will perform validity checks based on the information in the ConnectorClass.

The above yaml indicates the authentication checking for basic auth:

• path: Utilizes the repository value set in auth.params within the Connector information, concatenated as /<repository>/info/refs?service=git-upload-pack
• Authorization: If the Connector is configured with a Secret, the username and password fields from the Secret will be returned in base64.

#Rego-based Authentication Logic Configuration

When tool connectors require more complex authentication logic, you can use Rego-based authentication logic configuration.

Rego is a declarative policy language that allows you to define authentication logic. In ConnectorClass, Rego policies are specified in the auth.types[].generator.rego field:

apiVersion: connectors.alauda.io/v1alpha1
kind: ConnectorClass
metadata:
  name: example
spec:
  address:
    name: address
    type: string
  auth:
    types:
    - name: rego-auth
      secretType: Opaque
      generator:
        rego: |
          package proxy
          auth = {
            "position": "header",
            "auth": {
              "Authorization": concat(" ", ["Bearer", input.token])
            }
          }

The Rego policy must follow these rules:

• Define rules under the proxy package
• Produce an auth object with the following structure:
  • position: Where to inject authentication, such as "header", "query", or "body"
  • contentType: Content type for body injection (optional, used with "body" position)
  • auth: Map of authentication key-value pairs

#Example Rego Policies

#Basic Authentication

spec:
  auth:
    types:
    - name: basic-rego-auth
      secretType: Opaque
      generator:
        rego: |
          package proxy
          auth = {
            "position": "header",
            "auth": {
              "Authorization": concat(" ", ["Basic", base64.encode(concat(":", [input.username, input.password]))])
            }
          }

#API Key Authentication

spec:
  auth:
    types:
    - name: apikey-rego-auth
      secretType: Opaque
      generator:
        rego: |
          package proxy
          auth = {
            "position": "query",
            "auth": {
              "api_key": input.apikey
            }
          }

#JSON Body Authentication

spec:
  auth:
    types:
    - name: body-rego-auth
      secretType: Opaque
      generator:
        rego: |
          package proxy
          auth = {
            "position": "body",
            "contentType": "application/json",
            "auth": {
              "username": input.username,
              "password": input.password,
              "client_id": input.client_id
            }
          }

#Advanced Rego Techniques

You can use Rego's conditional logic for different authentication methods:

#Conditional Authentication

spec:
  auth:
    types:
    - name: conditional-auth
      secretType: Opaque
      generator:
        rego: |
          package proxy

          # Default uses API key
          auth = {
            "position": "header",
            "auth": {
              "X-API-Key": input.apikey
            }
          }

          # Use OAuth token if available
          auth = {
            "position": "header",
            "auth": {
              "Authorization": concat(" ", ["Bearer", input.oauth_token])
            }
          } {
            input.oauth_token != ""
          }

#Time-based Authentication

spec:
  auth:
    types:
    - name: time-based-auth
      secretType: Opaque
      generator:
        rego: |
          package proxy

          import time

          # Get current time
          current_time := time.now_ns() / 1000000000

          auth = {
            "position": "header",
            "auth": {
              "X-Timestamp": sprintf("%d", [current_time]),
              "X-Signature": hmac.sha256(input.api_secret, sprintf("%d", [current_time]))
            }
          }

For more Rego language details, refer to:

• Rego Policy Language

#ConnectorClass API

Provides a RESTful API for the current ConnectorClass, allowing clients to easily access resources within the tools when using Connectors.

If there is no need to provide API capabilities for the tool, spec.api can be left undefined.

The ConnectorClass API needs to be configured in the spec.api field, for example:

spec:
  api:
    ref:
      kind: Service
      name: git
      namespace: default

You can specify the API's Service information through spec.api.ref. If the API address of the ConnectorClass has a fixed prefix, it can be specified using spec.api.uri. For example:

spec:
  api:
    ref:
      kind: Service
      name: git
      namespace: default
    uri: /api

Additionally, you can use spec.api.uri to specify the absolute path of the API. For example:

spec:
  api:
    uri: https://git.example.com/api

Regardless of the form, the final resolved API address will be stored in status.api.address.url. For example:

Specifying the connectorclass API through service:

spec:
  api:
    ref:
      kind: Service
      name: git
      namespace: default
status:
  api:
    address:
      url: https://git.default.svc

Specifying the connectorclass API through uri:

spec:
  api:
    uri: https://git.default.svc/api
status:
  api:
    address:
      url: https://git.default.svc/api

Specifying the connectorclass API through svc while using spec.api.uri to specify the API path:

spec:
  api:
    ref:
      kind: Service
      name: git
      namespace: default
    uri: /api
status:
  api:
    address:
      url: https://git.default.svc/api

For more information, refer to:

• connector-api
• connectorclass-api definition specification

#Configuration Capabilities

Configuration capabilities are used to define the configuration information for this type of tool. This configuration information can be mounted into Pods in conjunction with connectors-csi-driver.

If the client does not need to rely on configuration information when accessing the tool, spec.configurations can be left undefined.

Configuration information is specified through spec.configurations. For example:

kind: ConnectorClass
metadata:
  name: git
spec:
  configurations:
  - name: config
    data:
      .gitconfig: |
        this is git config

Typically, we can specify a certain type of configuration information for a class of tools to facilitate configuration during use. For example:

• For git type tools, provide configuration for .gitconfig
• For oci registry type tools, provide configuration for config.json

The configuration content supports the use of variables, which can be dynamically rendered during mounting. For details, refer to the description of "Configuration File Rendering" in connectors-csi-driver.

#Example

The following ConnectorClass provides a file named .gitconfig, which is used to ignore SSL verification during git clone.

kind: ConnectorClass
metadata:
  name: git
spec:
  configurations:
  - name: config
    data:
      .gitconfig: |
        [http]
          sslVerify = false

The following ConnectorClass provides a file named .gitconfig, which automatically injects headers and replaces the git URL during git clone.

kind: ConnectorClass
metadata:
  name: git
spec:
  configurations:
  - name: config
    data:
      .gitconfig: |
        [http]
            extraHeader = Authorization: Basic {{ printf ":%s" .context.token | b64enc }}
        [url "{{ .connector.status.proxyAddress }}"]
            insteadOf = {{.connector.spec.address}}

#More Information

• connectors csi driver

#Metadata Information for Readability Display

ConnectorClass is a standard k8s resource that can be tagged with custom information using labels and annotations.

For example:

For example:

apiVersion: connectors.alauda.io/v1alpha1
kind: ConnectorClass
metadata:
  name: git
  labels:
    connectors.cpaas.io/git: "true"
  annotations:
    ui.cpaas.io/icon: "data:image/svg+xml;base64,PD94bWwgdmVyc2..."
    cpaas.io/display-name: Git
    cpaas.io/description: "Connect to any Git tool"
    connectors.cpaas.io/readme: "this is readme..."
    connectors.cpaas.io/docs-link: "/alauda-devops-connectors/concepts/connectorclass/git"

#ConnectorClass Proxy

The ConnectorClass Proxy is used to configure the proxy address for the ConnectorClass.

The ConnectorClass Proxy is configured through spec.proxy. For example:

spec:
  proxy:
    ref:
      kind: Service
      name: proxy
      namespace: default
    uri: https://proxy.example.com

The Connector will use the proxy address to proxy the request to the ConnectorClass. More information

#Resolver Type

The proxy address of the ConnectorClass will be resolved according to the specified resolver type.

The resolver type is configured through annotations connectors.cpaas.io/proxy-resolver. For example:

apiVersion: connectors.alauda.io/v1alpha1
kind: ConnectorClass
metadata:
  name: oci
  annotations:
    connectors.cpaas.io/proxy-resolver: "path"

This field is a convention between ConnectorClass-Proxy and Connector. Optional.

Supported values: host, path. Default is host.

• host format: http://{.ConnectorClass.Status.ProxyAddress.URL}
• path format: http://{.ConnectorClass.Status.ProxyAddress.URL}/namespaces/{namespace}/connectors/{connector-name}

#Status Information

Once you have defined the ConnectorClass resource, the status information of the resource will be stored in status.

The status.conditions type includes:

• APIReady: Status information of the API capability
• ProxyReady: Status information of the Proxy capability
• Ready: Marks the overall status of the current ConnectorClass

Ready Condition

The Ready Condition is used to mark the status of the current ConnectorClass. It aggregates the status of other conditions.

• When other Conditions are True, the current Condition is True.
• When any other Condition is False, the current Condition is False.
• When any other Condition is Unknown, the current Condition is Unknown.

APIReady Condition

Indicates the status information of the API service configured for the ConnectorClass. The API service is configured through ConnectorClass's spec.api.

Note:

• The API detection will only attempt to request the link and will not make any HTTP return value judgments. The health check of the API service should rely on the health check mechanism of the API service itself.
• Since the API service may change at any time, the status information of the API cannot reflect real-time information. It is recommended that clients use this status information as a hint rather than relying on it to block client behavior.

ProxyReady Condition

Indicates the status information of the Proxy service configured for the ConnectorClass. The Proxy service is configured through ConnectorClass's spec.proxy.

#Compatibility

Updates to the ConnectorClass may affect existing Connectors. If there are incompatible changes to the ConnectorClass, it may cause previously created Connectors to become invalid. Here are some possible changes that may lead to incompatibility:

1. Changes in authentication information: If the ConnectorClass modifies the supported authentication types or methods, it may cause Connectors using the old authentication method to malfunction.

2. Changes in configuration information: If the configuration information of the ConnectorClass changes, such as removing an existing configuration, it may cause Kubernetes workloads that depend on the old configuration to malfunction.

It is recommended to confirm the scope of impact when updating the ConnectorClass, or if necessary, create a new ConnectorClass.

#More Examples

• ConnectorClass supporting basic-auth authentication type

  apiVersion: connectors.alauda.io/v1alpha1
  kind: ConnectorClass
  metadata:
    name: git
  spec:
    address:
      type: string
    auth:
      types:
        - name: basicAuth
          secretType: kubernetes.io/basic-auth
          optional: true

• Custom authentication type ConnectorClass

  apiVersion: connectors.alauda.io/v1alpha1
  kind: ConnectorClass
  metadata:
    name: sample
  spec:
    address:
      type: string
    auth:
      types:
        - name: patAuth
          optional: true
          secretType: Opaque
          params:
          - name: username
          - name: privateToken

• ConnectorClass configured with liveness probe

  apiVersion: connectors.alauda.io/v1alpha1
  kind: ConnectorClass
  metadata:
    name: git
  spec:
    address:
      type: string
    auth:
      types:
        - name: basicAuth
          optional: true
          secretType: kubernetes.io/basic-auth
    livenessProbe:
      http:
        path: /

• ConnectorClass configured with auth probe

  apiVersion: connectors.alauda.io/v1alpha1
  kind: ConnectorClass
  metadata:
    name: git
    labels:
      connectors.cpaas.io/git: "true"
  spec:
    address:
      type: string
    auth:
      types:
        - name: basicAuth
          secretType: kubernetes.io/basic-auth
          optional: true
    livenessProbe:
      http:
        path: /
    authProbes:
      - authName: basicAuth
        params:
          - name: repository
            type: string
        probe:
          http:
            path: /{{- range .Connector.Spec.Auth.Params }}{{- if eq .Name "repository" }}{{ .Value.StringVal }}{{ end }}{{- end }}/info/refs?service=git-upload-pack
            httpHeaders:
            - name: Authorization
              value: >-
                {{- if .Secret }}Basic {{ printf "%s:%s" .Secret.StringData.username .Secret.StringData.password | b64enc }} {{- end }}

• Complete Git connector configuration example:

  apiVersion: connectors.alauda.io/v1alpha1
  kind: ConnectorClass
  metadata:
    name: git
  spec:
    address:
      name: address
      type: string
    auth:
      types:
        - name: basicAuth
          secretType: kubernetes.io/basic-auth
          optional: true
    livenessProbe:
      http:
        path: /
    authProbes:
      - authName: basicAuth
        params:
          - name: repository
            type: string
        probe:
          http:
            path: /{{- range .Connector.Spec.Auth.Params }}{{- if eq .Name "repository" }}{{ .Value.StringVal }}{{ end }}{{- end }}/info/refs?service=git-upload-pack
            httpHeaders:
            - name: Authorization
              value: >-
                {{- if .Secret }}Basic {{ printf "%s:%s" .Secret.StringData.username .Secret.StringData.password | b64enc }} {{- end }}

#More

• Connector User Guide