#ConnectorClass

#Overview

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

• The format of the tool's access address
• Supported authentication methods
• The method for checking tool availability
• The method for verifying authentication validity
• The API address of the tool

For example, the following definition describes a Git type connector that supports basic authentication:

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

#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

#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, the required authentication parameters can be defined, and at this point, the secretType is marked as kubernetes.io/opaque.

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

spec:
  auth:
    types:
      - name: privateToken
        secretType: kubernetes.io/opaque
        params:
          - name: username
            type: string
          - name: private-token
            type: string

At this point, it will require that the credentials used in the tool connector include username and private-token information.

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

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.

#ConnectorClass API {connectorclass_api}

The ConnectorClass can provide a RESTful API for the current ConnectorClass, making it easier for clients to access the resources within tools when using Connectors.

ConnectorClass API needs to be configured in the spec.api field, such as:

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

You can specify the Service information of the API via spec.api.ref. If the API address of ConnectorClass has a fixed prefix, you can specify it using spec.api.uri. For example:

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

Alternatively, you can specify the absolute path of the API using spec.api.uri. 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 instance:

To specify the connector class API through a service

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

To specify the connector class API via URI

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

To specify the connector class API through service 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 details, refer to

• connector-api
• connectorclass-api definition specification

#Configurations

You can specify configuration information 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 configuration information for a type of tool to facilitate configuration during use. For example:

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

These configuration pieces can be mounted to Pods in file form through the connectors-cs-driver.

The configuration contents support using variables, which can be dynamically rendered during mounting. For specifics, refer to the description of "Configuration file rendering" in connectors-cs-driver.

#Example

The following ConnectorClass provides a file named .gitconfig, used to ignore SSL certificate 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 that 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

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

For example:

apiVersion: connectors.alauda.io/v1alpha1
kind: ConnectorClass
metadata:
  name: git
  labels:
    connectors.cpaas.io/git: "true"
  annotations:
    cpaas.io/icon: ""
    cpaas.io/displayName: Git
    cpaas.io/description: "Connect to any Git tool"
    cpaas.io/readme: "this is readme..."

#Status Information

Condition information will be stored in status.conditions. The types include:

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

Ready Condition

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

When all 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 specified through spec.api of the ConnectorClass.

Note:

• The API detection only attempts to request the link without checking any HTTP return value. Health checks for the API service should rely on the API service's own health check mechanism.
• Due to the potential for external services to change at any time, the API's status information cannot represent real-time information. It is recommended that clients use this status information merely as a prompt and not rely on it to block client actions.

ProxyReady Condition

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

#Compatibility

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

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

2. Changes to configuration information: If there are changes to the configuration information of the ConnectorClass, such as removing an existing configuration, it may lead to Kubernetes workloads relying on the old configuration failing to work.

It is recommended to assess the scope of impact before 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

• ConnectorClass simultaneously supporting both basic-auth and ssh-auth authentication types, with basic-auth having optional authentication information.

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
      - name: sshAuth
        secretType: kubernetes.io/ssh-auth

• ConnectorClass for a custom authentication type

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

• ConnectorClass configured with a 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 an 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
      - name: sshAuth
        secretType: kubernetes.io/ssh-auth
  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