#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.

#Parameters

Parameters are used to defines additional parameters when creating a connector.

You can define required parameters for connector creation using the connectorclass spec.params field.

• spec.params[].name - Parameter name.
• spec.params[].type - Parameter type. Currently only supports string type.
• spec.params[].default - Default parameter value (optional). When a default value is provided, users can omit this parameter when creating a connector.
• spec.params[].description - Parameter description (optional).

For example, the following definition allows users to provide an sslVerify parameter when creating a git-type connector, with a default value of true.

kind: ConnectorClass
metadata:
  name: git
spec:
  params:
    - name: sslVerify
      type: string
      default: "true"

For parameter configuration when creating Connectors, refer to the Connector documentation.

Combined with connectors-csi-driver capabilities, this enables more flexible configuration. This is particularly useful when you need to provide parameterized configurations. For example, when creating a git-type connector, users can provide the sslVerify parameter to control SSL certificate verification. For more details, refer to the ConnectorClass Configuration documentation.

#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.

#Liveness Probe

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.

A liveness check can be performed using either HTTP requests or the ConnectorClass API.

#Probe using HTTP Requests

you can configure spec.livenessProbe.http to perform a liveness check using HTTP requests.

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.

For more details, refer to Probe using HTTP Requests in Authentication Probe. The configuration is identical, except for the field paths.

#Probe using ConnectorClass API

you can configure spec.livenessProbe.api to perform a liveness check using the ConnectorClass API.

Example

the following snippet indicates that detection is performed using the ConnectorClass API.

spec:
  livenessProbe:
    api:
      path: /

For more details, refer to Probe using ConnectorClass API in Authentication Probe. The configuration is identical, except for the field paths.

#Authentication Probe

Authentication validation is used to verify the validity of authentication credentials for tools of this type. If authentication validation is not required, the authProbes field can be omitted.

• spec.authProbes[].authName specifies the authentication type being validated and must match one of the names defined in spec.auth.types[].name.

Authentication validation can be performed using either HTTP requests or the ConnectorClass API.

#Probe using HTTP Requests

You can configure spec.authProbes[].probe.http to perform authentication validation using HTTP requests.

• spec.authProbes[].probe.http.host specifies the target host for authentication validation. Defaults to the host from the connector address.
• spec.authProbes[].probe.http.path specifies the request path for authentication validation. This is an absolute path that will be appended to the host URI resolved from the connector's spec.address when executing the probe. If spec.address contains a path prefix, the path prefix will be ignored during authentication validation. To include the path prefix, use Authentication Check Expressions to dynamically retrieve it.
• spec.authProbes[].probe.http.method specifies the HTTP method for authentication validation, supporting GET and POST. Defaults to GET.
• spec.authProbes[].probe.http.disableRedirect specifies whether to disable HTTP redirects during authentication validation. Defaults to false (automatic redirection is allowed).
• spec.authProbes[].probe.http.httpHeaders specifies the HTTP headers to include in authentication validation requests.
• spec.authProbes[].probe.http.scheme specifies the URI scheme for authentication validation. Defaults to the scheme from the connector address.

Example

The following YAML configuration demonstrates that during authentication validation, the system will send a GET https://example.com/ HTTP/1.1 request to the connector address with an Authorization: abc header.

kind: ConnectorClass
metadata:
  name: example-class
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
---
kind: Connector
metadata:
  name: example
spec:
  connectorClassName: example-class
  address: https://example.com

#Probe using ConnectorClass API

You can configure spec.authProbes[].probe.api to perform authentication validation using the ConnectorClass API. You must first configure spec.api in the ConnectorClass specification. A 200 response indicates successful authentication, while a 401 or 403 response indicates authentication failure. More about ConnectorClass API.

• spec.authProbes[].probe.api.path specifies the API endpoint path for authentication validation. This is a relative path that will be appended to the API address resolved from the ConnectorClass's spec.api configuration. If spec.api contains a path prefix, the path prefix will be included when performing authentication validation.

Example

The following YAML configuration demonstrates that during authentication validation, the system will send a GET https://example-api.default.svc.cluster.local/api/auth/check HTTP/1.1 request to the ConnectorClass API.

kind: ConnectorClass
metadata:
  name: example-class
spec:
  api:
    ref:
      kind: Service
      name: example-api
      namespace: default
    uri: /api
  authProbes:
    - authName: basicAuth
      probe:
        api:
          path: /auth/check # It is a relative path of the API address resolved from `spec.api` of connectorclass
---
kind: Connector
metadata:
  name: example
spec:
  connectorClassName: example-class
  address: https://example.com

#Custom Authentication Validation Parameters

Some authentication validation scenarios may require additional parameters, such as specifying the repository name when validating access to a Git repository. These parameters can be defined using spec.authProbes[].params.

kind: ConnectorClass
metadata:
  name: example-class
spec:
  authProbes:
    - authName: basicAuth  # Corresponding authentication type
      params:
        - name: repository
          type: string

#Authentication Validation Expressions

When configuring authProbes, expressions can be used to dynamically retrieve credential information or Connector metadata.

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 the probe.http.httpHeaders, probe.http.path, and probe.api.path fields.
• The expression format follows Go template syntax.
• Supported top-level fields include:
  • .Connector: Contains information about the Connector resource itself
  • .Secret: Contains the Secret data used for Connector authentication
• Available methods within expressions are documented in the sprig library:
  • For example: b64enc for Base64 encoding strings, trimPrefix for removing string prefixes

Example

Basic Authentication validation:

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 authentication validation based on the configuration defined in the ConnectorClass.

The above YAML demonstrates basic authentication validation:

• path: Uses the repository value from the Connector's auth.params, constructing the path as /<repository>/info/refs?service=git-upload-pack
• Authorization: When the Connector is configured with a Secret, the username and password fields are Base64-encoded and included in the Basic authentication header.

#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.data.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

#Variables Available in Rego

#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.data.username, input.data.password]))])
            }
          }

#API Key Authentication

spec:
  auth:
    types:
    - name: apikey-rego-auth
      secretType: Opaque
      generator:
        rego: |
          package proxy
          auth = {
            "position": "query",
            "auth": {
              "api_key": input.data.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.data.username,
              "password": input.data.password,
              "client_id": input.data.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.data.apikey
            }
          }

          # Use OAuth token if available
          auth = {
            "position": "header",
            "auth": {
              "Authorization": concat(" ", ["Bearer", input.data.oauth_token])
            }
          } {
            input.data.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.data.api_secret, sprintf("%d", [current_time]))
            }
          }

For more Rego language details, refer to:

• Rego Policy Language

#ConnectorClass API

The ConnectorClass API allows developers to extend API capabilities for a ConnectorClass through an additional HTTP API service. This provides a RESTful API for the ConnectorClass, enabling clients to easily access resources within the tools when using Connectors.

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

#Configuring API Address

The ConnectorClass API is configured in the spec.api field. You can specify the API service in three ways:

1. Through a Kubernetes Service reference:

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

2. Through a Service reference with a URI path prefix:

If the API address has a fixed path prefix, you can specify it using spec.api.uri:

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

3. Through an absolute URI:

You can also use spec.api.uri to specify the absolute path of the API:

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

#API Address Resolution

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

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

For more information, refer to:

• Connector API
• ConnectorClass API Definition Specification

#OpenAPI Description

The OpenAPI description is an optional configuration that serves two main purposes:

• Mark whether the API is a custom API or uses the Connector Proxy to access the tool's original API
• Provide API definitions to support API references in client dynamic forms

You can define the OpenAPI description using spec.api.openapi. The structure follows the OpenAPI 3.0 specification. For example:

spec:
  api:
    openapi:
      openapi: "3.0.1"
      info:
        title: Git API
        version: "1.0.0"

You can define the x-provider-type extension field in the API paths to mark whether the API is a custom API or uses the Proxy to access the tool's original API. Valid values are api or proxy.

The x-provider-type extension is defined as: api.openapi.paths[<path>].<verb>[x-provider-type]

Example:

spec:
  api:
    openapi:
      openapi: "3.0.1"
      info:
        title: Gitlab API
        version: "1.0.0"
      paths:
        /git/api:
          get:
            summary: Get Git API
            x-provider-type: api  # Use custom API
        /api/v4/projects:
          get:
            summary: Get Gitlab Projects API
            x-provider-type: proxy  # Use Proxy to access the tool's original API

When you need to reference the API in dynamic forms, additional configuration is required in spec.api.openapi. For more details, refer to Using Connectors API in Dynamic Forms.

#Configuration Capabilities

Configuration capabilities define the configuration files that a ConnectorClass provides to clients. These files can be mounted into Pods using the Connectors-CSI Driver.

#Configuration Types

• Custom Configurations: Defined in spec.configurations
• Built-in Configurations: Automatically provided by Connectors-CSI Driver (see: Built-in Configurations)

#Custom Configurations

Configurations are specified through spec.configurations:

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

For more details, see: Configuration File Rendering

Note: spec.configurations is optional. When undefined, only built-in configurations are available.

#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

#Using Rego to extract token from request

When using the built-in reverse proxy, you can configure Rego rules using spec.proxy.authExtractor to extract tokens from client requests, enabling the built-in reverse proxy to validate client authentication using the extracted token.

For example:

spec:
  proxy:
    authExtractor:
      rego: |
        package proxy
        auth = {
          "token": input.request.headers["Private-Token"][0]
        }

Rego rules must follow these requirements:

• Rules must be defined in the proxy package
• Use the auth variable to return the token, where the token is a string type, for example: auth = { "token": "abcd1234" }
• If the token cannot be extracted, return an empty string, for example: auth = { "token": "" }

The following variables are available in Rego:

Notes:

• Header keys in headers use Canonical MIME Header Key format (capitalized first letter)
• When implementing Rego rules, ensure robust logic. For example, return an empty string when input.request.headers is null or empty.

Example

spec:
  proxy:
    authExtractor:
      rego: |
        package proxy

        default auth = {
          "token": ""
        }

        auth = {
          "token": input.request.headers["Private-Token"][0]
        } if {
          input.request.headers != null
          input.request.headers["Private-Token"] != null
          count(input.request.headers["Private-Token"]) > 0
        }

This example demonstrates robust token extraction by:

• Defining a default rule that returns an empty token string
• Checking that headers exist and are not null before accessing them
• Verifying that the specific header key exists and has at least one value

For more advanced Rego rules, see the Rego Policy Language documentation. For more information about using the built-in reverse proxy, see Connectors Proxy.

#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