#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 Address Extensions

spec.addressExtensions defines additional named addresses on a Connector instance. The available names come from ConnectorClass Address Extensions.

• spec.addressExtensions[].name: Extension name. Must be unique in one Connector.
• spec.addressExtensions[].value: Extension value. Must be a non-empty http/https URL.

Admission validation enforces both syntax and class constraints:

1. Extensions required by ConnectorClass (no default) must be provided.
2. Connector cannot provide extension names that are not declared in ConnectorClass.
3. Extension names must be unique in Connector.
4. Extension values must not duplicate spec.address.

Runtime behavior:

• Connectors API can select backend address by extension name or direct URL through x-openapi-address.
• Connectors Proxy can treat spec.address and spec.addressExtensions[*].value as credential-injection target addresses.

Example

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: github-demo
spec:
  connectorClassName: github
  address: "https://github.com"
  addressExtensions:
    - name: api
      value: "https://api.github.com"

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

#Custom CA Certificates

When a tool's TLS certificate is signed by an internal or private Certificate Authority (CA), the Connector platform can be configured to trust those CAs without disabling certificate verification.

Custom CA certificate support is gated behind the enable-custom-ca-certs feature flag, which is disabled by default to preserve backward compatibility with existing deployments.

When the flag is enabled, the platform constructs a CA pool composed of three additive layers:

1. System default CA pool — the OS-level trust store baked into the container image.
2. Global custom CA certificates — Secrets in the connectors-system namespace labeled connectors.cpaas.io/ca-cert: "true". Multiple Secrets are aggregated.
3. Per-Connector CA certificates — an optional Secret referenced by spec.caCertSecretRef.name on the Connector. The Secret MUST reside in the same namespace as the Connector.

The constructed CA pool is used for:

• Liveness and authentication probes from the controller against the tool
• Proxy connectors to the tool from the proxy components
• ConnectorClass accessibility checks from the controller
• Extension proxies (OCI, Harbor, Git HTTPS, etc.) where applicable

#Per-Connector CA Certificate Reference

To trust a specific CA for a single Connector, set spec.caCertSecretRef.name:

apiVersion: connectors.alauda.io/v1alpha1
kind: Connector
metadata:
  name: internal-tool
  namespace: my-namespace
spec:
  connectorClassName: my-tool
  address: https://internal-tool.example.com
  auth:
    name: bearerToken
    secretRef:
      name: my-tool-credentials
  caCertSecretRef:
    name: my-tool-ca       ##  Secret in the same namespace

The referenced Secret MUST contain at least one PEM-encoded CA certificate. Only keys ending in .crt or .pem, or values containing a PEM header, are loaded into the pool — other keys (such as tokens or passwords accidentally placed in the same Secret) are ignored.

apiVersion: v1
kind: Secret
metadata:
  name: my-tool-ca
  namespace: my-namespace
type: Opaque
stringData:
  ca.crt: |
    -----BEGIN CERTIFICATE-----
    MIIDazCCAlOgAwIBAgIUF+...
    -----END CERTIFICATE-----

#Global CA Certificates

Cluster administrators can configure CA certificates that apply to all connectors by creating Secrets in the connectors-system namespace with the label connectors.cpaas.io/ca-cert: "true". The platform automatically discovers all matching Secrets and aggregates their certificates into the global CA pool.

Adding or removing labeled Secrets triggers automatic re-reconciliation of affected Connectors — no component restart is needed for global CA changes after the feature flag has been enabled.

For step-by-step instructions, see How to Configure Custom CA Certificates.

#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.
• CACertReady: Informational — indicates the status of the custom CA certificate configuration. This condition does not affect the top-level Ready condition.
• 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.

CACertReady Condition

Informational — indicates the status of the custom CA certificate configuration. This condition is not part of the standard readiness set, has severity: Info, and does not affect the top-level Ready condition. It is only present when the enable-custom-ca-certs feature flag is enabled.

When the condition is False, the controller also emits a Kubernetes Warning Event on the Connector object with reason CACertSecretNotFound or InvalidCACert, which can be seen with kubectl describe connector <name>.

When the feature flag is disabled, the CACertReady condition is not present at all.

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: CACertReady           ##  Only present when enable-custom-ca-certs feature flag is enabled
    status: "True"
    severity: Info              ##  Informational — does not affect Ready
    reason: Valid
    message: 'CA certificate loaded from secret "my-tool-ca"'
  - 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"