#Connector

#Overview

Connector is a namespace-level resource used to define the connection configuration between tools and platforms. It includes:

• Access address of the tool
• Authentication information of the tool
• Status information of the tool

For example, the following definition illustrates a Git type connector:

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: git-github
  namespace: default
spec:
  connectorClassName: git  ##  Specify the connector type as git, this ConnectorClass must exist
  address: "https://github.com"  ##  Access address of the tool
  auth:
    name: basicAuth
    secretRef:  ##  Reference to authentication information
      name: github-secret

#Connector Address

The address field specifies the target tool's URL endpoint that the Connector will integrate with. It accepts both root URLs and URLs with path prefixes.

#Basic URL Format

For tools accessible at the root domain:

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

#URL with Path Prefix

For tools deployed behind reverse proxies or accessible via specific paths:

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: git-gitlab
spec:
  connectorClassName: git
  address: "https://internal-tool.com/gitlab"
  # ...

Note

The http based authentication probe and liveness probe will not be performed against the path prefix. If you want to perform the probe against the path prefix, you can use authentication check expressions and liveness check expressions.

More about it please refer to liveness probe and authentication probe.

#Connector Parameters

Connector parameters enable you to pass additional configuration information to a Connector instance. These parameters are first defined in the ConnectorClass specification and can then be configured when creating individual Connector resources.

You can specify parameter values in the Connector using the spec.params field.

• spec.params[].name: The parameter name, which must match a parameter name defined in the corresponding ConnectorClass.
• spec.params[].value: The parameter value. The value type must match the parameter type defined in the ConnectorClass. Currently, only string type is supported.

If a parameter has a default value defined in the ConnectorClass, you can omit the parameter when creating the Connector, and the default value will be used.

For more information about defining parameters in ConnectorClass, refer to ConnectorClass Parameters.

Example

The following example demonstrates a Connector configured with an sslVerify parameter:

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: git-gitlab
spec:
  connectorClassName: git-example
  address: "https://private-gitlab.example.com"
  params:
    - name: sslVerify
      value: "false"
---
apiVersion: connectors.alauda.io/v1alpha1
kind: ConnectorClass
metadata:
  name: git-example
spec:
  # ...
  params:
    - name: sslVerify
      type: string
      default: "true"

#Authentication Information

The authentication information defines the credentials for accessing the tool. Depending on the type of tool, different authentication methods can be configured. This authentication method is defined in the ConnectorClass. For more details, refer to the description of authentication information in ConnectorClass.

#Configuring Authentication Information

Authentication information is configured in the following way:

1. Specify the name of the authentication type used according to the ConnectorClass definition.
2. Create a Secret that contains the credentials.
3. Reference the Secret in the Connector via spec.auth.secretRef.
4. Specify the parameter information required during authentication check.

For example, to configure basic authentication:

##  Create a Secret containing username and password
apiVersion: v1
kind: Secret
metadata:
  name: github-secret
  namespace: default
type: kubernetes.io/basic-auth
data:
  username: dXNlcm5hbWU=  ##  Base64 encoded username
  password: cGFzc3dvcmQ=  ##  Base64 encoded password
---
##  Reference the Secret in the Connector
apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: git-github
spec:
  connectorClassName: git
  address: "https://github.com"
  auth:
    name: basic-auth
    secretRef:
      name: github-secret
      namespace: default

#Optional Authentication

Some tools support access without authentication. In this case, spec.auth.secretRef can be omitted.

For example, accessing a public Git repository:

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: git-public
spec:
  connectorClassName: git
  address: "https://github.com"
  auth:
    name: basic-auth ##  Authentication for git connectorclass basic-auth is optional

#Authentication Check

The Connector supports verifying the validity of authentication information. The configuration for the check is set via spec.auth.params which includes the parameters required for the authentication check.

For example, to check access permissions to a Git repository:

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: git-github
spec:
  connectorClassName: git
  address: "https://github.com"
  auth:
    name: basic-auth
    secretRef:
      name: github-secret
      namespace: default
    params:
    - name: repository  ##  Specify the repository to be checked
      value: "org/repo.git"

Note that once the ConnectorClass specifies authentication detection params, parameters in connector must be provided, even if the Connector is created without specifying secret information, spec.auth.params must be passed.

#Proxy Address

If the Connector points to a ConnectorClass that has configured proxy capability, the system will allocate a proxy address for each Connector.

Clients can use this proxy address to access the tool in a secretless manner.

The default format of the proxy address is http://c-{connector-name}.{namespace}.svc.cluster.local, which can be obtained from status.proxy.

For example, the following example describes a connector with a proxy address:

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: harbor
  namespace: default
spec:
  address: https://example.com
status:
 proxy:
    httpAddress:
      url: http://c-harbor.default.svc.cluster.local

When the ConnectorClass has configured proxy resolver type is path, the format of the proxy address is http://c-{connector-name}.{namespace}.svc.cluster.local/namespaces/{namespace}/connectors/{connector-name}, where {path} is the path of the Connector.

For example, the following example describes a connector with a proxy address:

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: harbor
  namespace: default
spec:
  address: https://example.com
status:
 proxy:
    httpAddress:
      url: http://c-harbor.default.svc.cluster.local/namespaces/default/connectors/harbor

#Status Information

The status information of the Connector is recorded in the status field, containing proxy address, API address, and conditions:

• status.conditions: Conditions of the Connector.
• status.proxy: Proxy address of the Connector.
• status.api: API address of the Connector.

Proxy Address

The proxy field contains the proxy address of the Connector.

• status.proxy.httpAddress.url: The HTTP address of the proxy for the current Connector.

You can use this address with existing tool clients to access the tool in a secretless manner within the cluster. For more information, refer to Connector Proxy.

If the ConnectorClass has no proxy capability, the status.proxy field will be empty.

API Address

The api field contains the API address of the Connector.

• status.api.path: The API relative path for the current Connector (relative to the cluster ingress access entrypoint).

You can use this path outside the cluster to access the tool's original API through the current Connector. For more information, refer to Connector API.

Conditions

The conditions type includes:

• ConnectorClassReady: Indicates whether the connector type is correct.
• SecretReady: Indicates whether the authentication information is correctly configured.
• LivenessReady: Indicates whether the tool is accessible.
• AuthReady: Indicates whether the authentication information is valid.
• ProxyServiceReady: Indicates whether the proxy address for the current Connector is successfully allocated.
• Ready: Indicates the overall status.

SecretReady Condition

Indicates the status information of the secret for the Connector.

AuthReady Condition

Indicates the status information of the authentication for the Connector.

LivenessReady Condition

Indicates the status information of the liveness for the Connector.

ProxyServiceReady Condition

Indicates the status information of the proxy service for the Connector.

For example:

status:
  conditions:
  - type: ConnectorClassReady
    status: "True"
    message: ""
  - type: SecretReady
    status: "True"
    message: ""
  - type: LivenessReady
    status: "True"
    lastProbeTime: "2024-10-16T02:27:44Z"
    message: ""
  - type: AuthReady
    status: "True"
    lastProbeTime: "2024-10-16T02:27:44Z"
    message: ""
  - type: ProxyServiceReady
    status: "True"
    lastProbeTime: "2024-10-16T02:27:44Z"
    message: ""
  - type: Ready
    status: "True"
    message: ""

#Examples

#Git Connector with Basic Authentication

##  Create authentication information
apiVersion: v1
kind: Secret
metadata:
  name: git-auth
  namespace: default
type: kubernetes.io/basic-auth
data:
  username: dXNlcm5hbWU=
  password: cGFzc3dvcmQ=
---
##  Create Connector
apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: git-github
  namespace: default
spec:
  connectorClassName: git
  address: "https://github.com"
  auth:
    name: basic-auth
    secretRef:
      name: git-auth
      namespace: default
    params:
    - name: repository
      value: "org/repo.git"

#Git Connector without Authentication

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: git-public
  namespace: default
spec:
  connectorClassName: git
  address: "https://github.com"
  auth:
    name: basic-auth
  params:
    - name: repository
      value: "org/repo.git"