ConnectorClass

概述

ConnectorClass 是一个集群级资源,用于定义特定类型工具的访问模式和行为规范。

以下示例定义了一个支持基本认证的 hello-git 类型 connector:

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

在 ConnectorClass 中,通过描述以下信息来定义连接工具到平台的访问模式和行为规范:

  • 工具访问地址的格式
  • 支持的认证方法
  • 如何检查工具的可访问性
  • 如何验证认证的有效性
  • 工具如何提供 API 能力
  • 工具提供哪些配置能力
  • 用于可读性展示的元数据

本文档还提供了示例,帮助读者更好地理解如何自定义 ConnectorClass。示例

地址信息

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

spec:
  address:
    type: string  # Currently supports only string type

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

认证信息

认证类型

认证类型定义了用于工具认证的凭证类型。一个工具可以支持多种认证类型,允许用户在使用工具时进行选择。

用户可以通过以下方式为当前认证类型指定唯一名称:

  • spec.auth.types[].name,该名称必须唯一且不能重复。
  • spec.auth.types[].secretType,指定认证所需的 Secret 类型,对应 Kubernetes Secret Type。

示例:

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

在内置的 K8S Secret Type 中,除 Opaque 外的所有类型都带有字段约束。提供 Secret 时,用户必须确保 Secret 的字段符合该类型约束。

使用 Opaque 类型时,必须声明 认证参数。

与 k8s 一样,你也可以使用自定义 Secret Type。此时,必须声明 认证参数。

认证参数

认证过程中凭证所需的参数通过 spec.auth.types[].params 定义。

对于数据字段定义明确的标准 Kubernetes secret types,可以省略参数。例如:

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

对于自定义认证类型,可以定义所需的认证参数,此时 secretType 标记为 Opaque 或自定义名称。

例如,GitLab 的 Personal Access Token(PAT)认证:

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

此定义要求工具 connector 中使用的凭证包含 params 中指定的字段。

可选认证

某些工具支持无需认证即可访问,通过 optional 字段标记认证是否可选:

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

spec:
  auth:
    types:
      - name: basicAuth
        optional: true  # Marking authentication as optional
        secretType: kubernetes.io/basic-auth
      - name: sshAuth
        secretType: kubernetes.io/basic-auth

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

可访问性检查

可访问性检查用于验证工具是否可以正常访问。此类检查的配置通过 livenessProbe 字段完成。

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

spec:
  livenessProbe:
    http:
      path: /

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

认证检查

认证检查用于验证此类工具的认证信息是否有效。如果不需要认证检查,可以省略 authProbes。

例如,以下 YAML 表示在工具的认证检查期间,将发起一个带有注入 Authorization: abc 请求头的 http GET 请求。

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 表示正在使用的认证类型,需要与 spec.auth.types[].name 保持一致。
  • 在认证检查期间,将直接使用 connector 工具的地址信息。
  • spec.authProbes[].probe.http.method 指定用于认证的 HTTP 方法,支持 GET 和 POST。默认值为 GET。
  • spec.authProbes[].probe.http.disableRedirect 指定在认证期间是否禁用重定向。默认允许自动重定向。

自定义认证检查参数

某些认证检查可能需要额外参数,例如在检查对 Git 仓库的访问时指定仓库名称。可通过 spec.authProbes[].params 指定这些参数。

spec:
  authProbes:
    - authName: basicAuth  # Corresponding authentication type
      params:
        - name: repository
          type: string

认证检查表达式

配置 authProbes 时,可通过表达式动态获取凭证信息或 Connector 信息。

例如,

spec:
  authProbes:
    - authName: basicAuth  # Corresponding authentication type
      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:移除字符串前缀

示例

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

connector 将根据 ConnectorClass 中的信息执行有效性检查。

上面的 yaml 表示 basic auth 的认证检查:

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

基于 Rego 的认证逻辑配置

当工具 connector 需要更复杂的认证逻辑时,可以使用基于 Rego 的认证逻辑配置。

Rego 是一种声明式策略语言,允许你定义认证逻辑。在 ConnectorClass 中,Rego 策略通过 auth.types[].generator.rego 字段指定:

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.token])
            }
          }

Rego 策略必须遵循以下规则:

  • 在 proxy package 下定义规则
  • 生成一个 auth 对象,结构如下:
    • position:注入认证的位置,例如 "header"、"query" 或 "body"
    • contentType:body 注入的内容类型(可选,与 "body" 位置一起使用)
    • auth:认证键值对的映射

Rego 策略示例

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

高级 Rego 技巧

你可以使用 Rego 的条件逻辑来处理不同的认证方法:

条件认证
spec:
  auth:
    types:
    - name: conditional-auth
      secretType: Opaque
      generator:
        rego: |
          package proxy

          # Default uses API key
          auth = {
            "position": "header",
            "auth": {
              "X-API-Key": input.apikey
            }
          }

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

更多 Rego 语言细节,请参阅:

ConnectorClass API

为当前 ConnectorClass 提供一个 RESTful API,使客户端在使用 Connectors 时能够轻松访问工具内的资源。

如果不需要为工具提供 API 能力,可以将 spec.api 留空。

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 指定 connectorclass API:

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

通过 uri 指定 connectorclass API:

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

通过 svc 指定 connectorclass 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

更多信息请参阅:

配置能力

配置能力用于定义此类工具的配置信息。这些配置信息可以与 connectors-csi-driver 结合挂载到 Pods 中。

如果客户端在访问工具时不需要依赖配置信息,则可以将 spec.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-csi-driver 中关于“Configuration File Rendering”的说明。

示例

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

更多信息

用于可读性展示的元数据信息

ConnectorClass 是一个标准 k8s 资源,可以通过 labels 和 annotations 添加自定义信息。

例如:

键描述
ui.cpaas.io/iconConnectorClass 的图标,可选。格式:data:image/svg+xml;base64,PD94bWwgdmVyc2...
cpaas.io/display-nameConnectorClass 的显示名称,可选。
cpaas.io/descriptionConnectorClass 的描述,可选。
connectors.cpaas.io/readmeConnectorClass 的使用说明,可选。通常用于无法提供 docs-link 的自定义场景。支持 Markdown 格式。
connectors.cpaas.io/docs-linkConnectorClass 的文档链接,可选。相对路径或绝对路径。

例如:

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

ConnectorClass Proxy 用于配置 ConnectorClass 的代理地址。

ConnectorClass Proxy 通过 spec.proxy 进行配置。例如:

spec:
  proxy:
    ref:
      kind: Service
      name: proxy
      namespace: default
    uri: https://proxy.example.com

Connector 将使用代理地址将请求代理到 ConnectorClass。更多信息

解析类型

ConnectorClass 的代理地址将根据指定的 resolver 类型进行解析。

resolver 类型通过注解 connectors.cpaas.io/proxy-resolver 进行配置。例如:

apiVersion: connectors.alauda.io/v1alpha1
kind: ConnectorClass
metadata:
  name: oci
  annotations:
    connectors.cpaas.io/proxy-resolver: "path"

此字段是 ConnectorClass-Proxy 与 Connector 之间的一项约定。可选。

支持的值:host、path。默认值为 host。

  • host 格式:http://{.ConnectorClass.Status.ProxyAddress.URL}
  • path 格式:http://{.ConnectorClass.Status.ProxyAddress.URL}/namespaces/{namespace}/connectors/{connector-name}

状态信息

定义完 ConnectorClass 资源后,该资源的状态信息会存储在 status 中。

status.conditions 类型包括:

  • APIReady:API 能力的状态信息
  • ProxyReady:Proxy 能力的状态信息
  • Ready:标记当前 ConnectorClass 的整体状态

Ready Condition

Ready Condition 用于标记当前 ConnectorClass 的状态,它会聚合其他条件的状态。

  • 当其他 Conditions 都为 True 时,当前 Condition 为 True。
  • 当任一其他 Condition 为 False 时,当前 Condition 为 False。
  • 当任一其他 Condition 为 Unknown 时,当前 Condition 为 Unknown。

APIReady Condition

表示为 ConnectorClass 配置的 API 服务的状态信息。API 服务通过 ConnectorClass 的 spec.api 进行配置。

状态原因描述
TrueNonAPI未配置 spec.api,当前 ConnectorClass 没有 API 能力
True已定义 spec.api,API 服务正常
False已定义 spec.api,API 能力异常或检测本身异常
UnknownAPI 能力检测中

注意:

  • API 检测只会尝试请求链接,不会对 HTTP 返回值进行判断。API 服务的健康检查应依赖 API 服务自身的健康检查机制。
  • 由于 API 服务可能随时变化,API 的状态信息无法反映实时情况。建议客户端将此状态信息视为提示,而不是依赖它来阻止客户端行为。

ProxyReady Condition

表示为 ConnectorClass 配置的 Proxy 服务的状态信息。Proxy 服务通过 ConnectorClass 的 spec.proxy 进行配置。

状态原因描述
TrueNonProxy未配置 spec.proxy,当前 ConnectorClass 没有 Proxy 能力
True已定义 spec.proxy,Proxy 服务正常
False已定义 spec.proxy,Proxy 能力异常或检测本身异常
UnknownProxy 能力检测中

兼容性

对 ConnectorClass 的更新可能会影响现有 Connectors。如果 ConnectorClass 存在不兼容变更,可能会导致先前创建的 Connectors 失效。以下是一些可能导致不兼容的变更:

  1. 认证信息变更:如果 ConnectorClass 修改了支持的认证类型或认证方式,可能会导致使用旧认证方式的 Connectors 无法正常工作。

  2. 配置信息变更:如果 ConnectorClass 的配置信息发生变化,例如移除了某个已有配置,可能会导致依赖旧配置的 Kubernetes 工作负载无法正常工作。

建议在更新 ConnectorClass 时确认影响范围,或在必要时创建新的 ConnectorClass。

更多示例

  • 支持 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
            optional: true
  • 自定义认证类型的 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
  • 配置了 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 connector 配置示例:

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

更多