简体中文

ConnectorClass

Overview

ConnectorClass 是一个集群级别的资源，用于定义特定类型工具的访问模式和行为规范。它描述了：

工具访问地址的格式
支持的认证方式
工具可用性检测的方法
认证有效性验证的方法
工具的 API 地址

例如，以下定义描述了一个支持基本认证的 Git 类型连接器：

apiVersion: connectors.alauda.io/v1alpha1
kind: ConnectorClass
metadata:
  name: git
spec:
  address:
    type: string  #  地址为字符串格式
  auth:
    types:
      - name: basicAuth
        secretType: kubernetes.io/basic-auth  #  使用 Basic Auth 进行认证

Address Information

地址信息定义了访问工具的格式。目前支持字符串类型的地址配置。该地址信息限制了当前类型工具必须满足的字段类型约束。

spec:
  address:
    type: string  # 当前仅支持字符串类型

此时表示连接工具到平台的地址信息必须为 string 类型。

Authentication Information

Authentication Type

认证类型定义了工具认证所使用的凭证类型。一个工具可以支持多种认证类型，用户在使用工具时可以选择其中一种。

用户可以通过以下方式为当前认证类型命名唯一标识：

spec.auth.types[].name，必须唯一且不可重复。
spec.auth.types[].secretType，指定认证所需的 Secret 类型，对应 Kubernetes 的 secret type。

示例：

spec:
  auth:
    types:
      - name: basicAuth  # 认证类型名称
        secretType: kubernetes.io/basic-auth  # 对应的 Secret 类型
      - name: sshAuth
        secretType: kubernetes.io/ssh-auth

Authentication Parameters

认证所需凭证参数由 spec.auth.types[].params 定义。

对于标准 Kubernetes Secret 类型且数据字段明确的，可以省略参数定义。例如：

kubernetes.io/basic-auth：用户名密码认证
kubernetes.io/ssh-auth：SSH 密钥认证

对于自定义认证类型，可以定义所需的认证参数，此时 secretType 标记为 kubernetes.io/opaque。

例如，GitLab 的 Personal Access Token (PAT) 认证：

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

此时要求工具连接器中使用的凭证包含 username 和 private-token 信息。

Optional Authentication

部分工具支持无认证访问，通过 optional 字段标记认证是否可选：

例如，以下表示 basicAuth 的凭证是可选的，而 sshAuth 的凭证是必需的。

spec:
  auth:
    types:
      - name: basicAuth
        optional: true  # 标记认证为可选
        secretType: kubernetes.io/basic-auth
      - name: sshAuth
        secretType: kubernetes.io/basic-auth

此时连接该类型工具到平台时，可以省略 basicAuth 类型的认证。

Accessibility Check

可访问性检测用于验证工具是否能正常访问。该类型的检测配置通过 livenessProbe 字段完成。

例如，以下片段表示使用 HTTP 请求进行检测。

spec:
  livenessProbe:
    http:
      path: /

当工具返回 200 状态时，视为可访问。

Authentication Checking

认证检测用于验证该类型工具的认证信息有效性。

例如，以下 YAML 表示在工具认证检测时，会发起带有注入的 Authorization: abc 头的 http GET 请求。

spec:
  authProbes:
    - authName: basicAuth  # 对应认证类型
      probe:
        http:
          httpHeaders:
            Authorization: abc
          path: /
          method: GET # 默认为 GET，支持 POST 和 GET 方法
          disableRedirect: false # 默认为 false，允许自动重定向

authName 表示使用的认证类型，需要与 spec.auth.types[].name 对应。
认证检测时会直接使用连接器工具的地址信息。
spec.authProbes[].probe.http.method 指定认证使用的 HTTP 方法，支持 GET 和 POST，默认 GET。
spec.authProbes[].probe.http.disableRedirect 指定认证时是否禁用重定向，默认允许自动重定向。

Custom Authentication Check Parameters

部分认证检测可能需要额外参数，例如检测 Git 仓库访问时指定仓库名，可通过 spec.authProbes[].params 指定。

spec:
  authProbes:
    - authName: basicAuth  # 对应认证类型
      params:
        - name: repository
          type: string

Authentication Check Expressions

配置 authProbes 时，表达式可以动态获取凭证信息或 Connector 信息。

例如，

spec:
  authProbes:
    - authName: basicAuth  # 对应认证类型
      probe:
        http:
          httpHeaders:
            Authorization: {{ .Secret.StringData.token }}
          path: /
      params:
        - name: repository
          type: string

表达式可用于 httpHeaders 和 path 字段。
表达式格式为 go template
支持的顶层字段包括：
- .Connector：Connector 本身的信息
- .Secret：用于 Connector 的 Secret 信息
表达式中可用的方法参考 sprig 文档
- 例如：b64enc 用于字符串的 Base64 编码，trimPrefix 用于去除字符串前缀

Example

Basic Auth 认证检测示例

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 }}

连接器将根据 ConnectorClass 中的信息执行有效性检测。

上述 yaml 表示对 basic auth 的认证检测：

path：利用 Connector 信息中 auth.params 里设置的 repository 值，拼接为 /<repository>/info/refs?service=git-upload-pack
Authorization：如果 Connector 配置了 Secret，则返回 Secret 中的 username 和 password 字段的 base64 编码。

ConnectorClass API {connectorclass_api}

ConnectorClass 可以为当前 ConnectorClass 提供 RESTful API，方便客户端在使用 Connector 时访问工具内的资源。

ConnectorClass API 需要在 spec.api 字段配置，例如：

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

可以通过 spec.api.ref 指定 API 的 Service 信息。如果 ConnectorClass 的 API 地址有固定前缀，可以通过 spec.api.uri 指定。例如：

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

也可以直接通过 spec.api.uri 指定 API 的绝对路径。例如：

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

无论哪种形式，最终解析出的 API 地址会存储在 status.api.address.url 中。例如：

通过 Service 指定 connector class API

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

通过 URI 指定 connector class API

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

通过 Service 指定 connector class API，同时使用 spec.api.uri 指定 API 路径

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

更多详情请参考

Configurations

可以通过 spec.configurations 指定配置信息。例如：

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

通常，我们可以为某类工具指定特定的配置信息，方便使用时配置。例如：

对于 git 类型工具，提供 .gitconfig 配置
对于 oci registry 类型工具，提供 config.json 配置

这些配置内容可以通过 connectors-cs-driver 以文件形式挂载到 Pod 中。

配置内容支持使用变量，可在挂载时动态渲染。具体请参考 connectors-cs-driver 中的“配置文件渲染”说明。

Example

以下 ConnectorClass 提供了一个名为 .gitconfig 的文件，用于在 git clone 时忽略 SSL 证书校验。

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

以下 ConnectorClass 提供了一个名为 .gitconfig 的文件，用于在 git clone 时自动注入头部并替换 Git URL。

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 是标准的 k8s 资源，可以通过 labels 和 annotations 打上自定义信息。

例如：

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

条件信息存储在 status.conditions 中，类型包括：

APIReady：API 能力的状态信息
ProxyReady：Proxy 能力的状态信息
Ready：表示当前 ConnectorClass 的整体状态

Ready Condition

Ready Condition 用于表示当前 ConnectorClass 的状态。它聚合其他条件的状态。

当所有其他条件为 True 时，当前条件为 True。当任一其他条件为 False 时，当前条件为 False。当任一其他条件为 Unknown 时，当前条件为 Unknown。

APIReady Condition

表示 ConnectorClass 配置的 API 服务的状态信息。API 服务通过 ConnectorClass 的 spec.api 指定。

状态	原因	描述
True	NonAPI	API 能力检测正常，但未检测到 API 服务配置
True		API 能力正常
False		API 能力异常或检测本身异常
Unknown		API 能力检测中

注意：

API 检测仅尝试请求链接，不检查任何 HTTP 返回值。API 服务的健康检查应依赖其自身的健康检查机制。
由于外部服务可能随时变更，API 的状态信息不能代表实时信息。建议客户端仅将此状态信息作为提示，不依赖其阻断客户端操作。

ProxyReady Condition

表示 ConnectorClass 配置的 Proxy 服务的状态信息。Proxy 服务通过 ConnectorClass 的 spec.proxy 指定。

状态	原因	描述
True	NonProxy	Proxy 能力检测正常，但未检测到 Proxy 服务配置
True		Proxy 能力正常
False		Proxy 能力异常或检测本身异常
Unknown		Proxy 能力检测中

Compatibility

ConnectorClass 的更新可能影响已有的 Connector。如果 ConnectorClass 存在不兼容变更，可能导致之前创建的 Connector 失效。以下是可能导致不兼容的变更示例：

认证信息变更：如果 ConnectorClass 修改了支持的认证类型或方式，可能导致使用旧认证方式的 Connector 无法正常工作。
配置信息变更：如果 ConnectorClass 的配置信息发生变更，例如移除已有配置，可能导致依赖旧配置的 Kubernetes 工作负载无法正常运行。

建议在更新 ConnectorClass 前评估影响范围，必要时创建新的 ConnectorClass。

More Examples

支持 basic-auth 认证类型的 ConnectorClass

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

同时支持 basic-auth 和 ssh-auth 认证类型，且 basic-auth 认证信息为可选的 ConnectorClass

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

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

配置了 liveness probe 的 ConnectorClass

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: /

配置了 auth probe 的 ConnectorClass

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 }}

完整的 Git 连接器配置示例：

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 }}

Connector User Guide

Connector APIs

Operator APIs

ConnectorClass

目录

Overview

Address Information

Authentication Information

Authentication Type

Authentication Parameters

Optional Authentication

Accessibility Check

Authentication Checking

Custom Authentication Check Parameters

Authentication Check Expressions

Example

ConnectorClass API {connectorclass_api}

Configurations

Example

More Information

Metadata

Status Information

Compatibility

More Examples

More

Connector APIs

Operator APIs

#ConnectorClass

#目录

#Overview

#Address Information

#Authentication Information

#Authentication Type

#Authentication Parameters

#Optional Authentication

#Accessibility Check

#Authentication Checking

#Custom Authentication Check Parameters

#Authentication Check Expressions

#Example

#ConnectorClass API {connectorclass_api}

#Configurations

#Example

#More Information

#Metadata

#Status Information

#Compatibility

#More Examples

#More

ConnectorClass

目录

Overview

Address Information

Authentication Information

Authentication Type

Authentication Parameters

Optional Authentication

Accessibility Check

Authentication Checking

Custom Authentication Check Parameters

Authentication Check Expressions

Example

ConnectorClass API {connectorclass_api}

Configurations

Example

More Information

Metadata

Status Information

Compatibility

More Examples

More