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。 示例

地址信息

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

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

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

地址扩展

spec.addressExtensions 定义了当前工具类型的额外命名地址。其 schema 与 spec.params 相同:

  • spec.addressExtensions[].name - 扩展名称。在一个 ConnectorClass 中必须唯一。
  • spec.addressExtensions[].type - 值类型。当前仅支持 string。
  • spec.addressExtensions[].default - 默认值(可选)。如果未设置,则该扩展在 Connector 中是必填项。
  • spec.addressExtensions[].description - 描述(可选)。

当一个 connector 需要多个后端地址时,通常会使用该机制,例如一个 Web 访问地址和一个 API 地址。

kind: ConnectorClass
metadata:
  name: github
spec:
  address:
    type: string
  addressExtensions:
    - name: api
      type: string
      description: GitHub API address, for example https://api.github.com
    - name: upload
      type: string
      default: https://uploads.github.com

Connector 的准入遵循此处定义的类契约:

  • 每个未设置 default 的扩展都必须由 Connector 提供。
  • Connector 不能提供未在 ConnectorClass.spec.addressExtensions 中定义的扩展名称。

有关 Connector 侧取值和运行时用法,请参见 Connector Address Extensions。

参数

参数用于在创建 connector 时定义额外参数。

你可以使用 connectorclass 的 spec.params 字段定义创建 connector 所需的参数。

  • spec.params[].name - 参数名称。
  • spec.params[].type - 参数类型。当前仅支持 string 类型。
  • spec.params[].default - 默认参数值(可选)。提供默认值后,用户在创建 connector 时可以省略该参数。
  • spec.params[].description - 参数描述(可选)。

例如,以下定义允许用户在创建 git 类型 connector 时提供 sslVerify 参数,并将其默认值设为 true。

kind: ConnectorClass
metadata:
  name: git
spec:
  params:
    - name: sslVerify
      type: string
      default: "true"

有关创建 Connectors 时的参数配置,请参见 Connector 文档。

结合 connectors-csi-driver 的能力,可以实现更灵活的配置。这在需要提供参数化配置时尤其有用。例如,在创建 git 类型 connector 时,用户可以提供 sslVerify 参数来控制 SSL 证书验证。更多详情请参见 ConnectorClass 配置 文档。

认证信息

认证类型

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

用户可以通过以下方式唯一命名当前认证类型:

  • 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 类型中,除 Opaque 外,其余类型都有限定字段。提供 Secret 时,用户必须确保 Secret 的字段与该类型约束一致。

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

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

认证参数

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

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

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

对于自定义认证类型,可以定义所需的认证参数,此时 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 请求或 ConnectorClass API 执行。

使用 HTTP 请求进行探测

你可以配置 spec.livenessProbe.http,通过 HTTP 请求执行存活检查。

示例

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

spec:
  livenessProbe:
    http:
      path: /

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

更多详情请参见 Authentication Probe 中的使用 HTTP 请求进行探测。其配置与此处相同,仅字段路径不同。

使用 ConnectorClass API 进行探测

你可以配置 spec.livenessProbe.api,通过 ConnectorClass API 执行存活检查。

示例

以下片段表示使用 ConnectorClass API 进行检测。

spec:
  livenessProbe:
    api:
      path: /

更多详情请参见 Authentication Probe 中的使用 ConnectorClass API 进行探测。其配置与此处相同,仅字段路径不同。

认证探测

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

  • spec.authProbes[].authName 指定正在验证的认证类型,且必须与 spec.auth.types[].name 中定义的某个名称匹配。

认证验证可以通过 HTTP 请求或 ConnectorClass API 执行。

使用 HTTP 请求进行探测

你可以配置 spec.authProbes[].probe.http,通过 HTTP 请求执行认证验证。

  • spec.authProbes[].probe.http.host 指定认证验证的目标 host。默认使用 connector 地址中的 host。
  • spec.authProbes[].probe.http.path 指定认证验证的请求路径。这是一个绝对路径,在执行探测时会追加到从 connector 的 spec.address 解析出的 host URI 后面。如果 spec.address 包含路径前缀,则在认证验证期间会忽略该路径前缀。若要包含路径前缀,请使用 Authentication Check Expressions 动态获取它。
  • spec.authProbes[].probe.http.method 指定认证验证使用的 HTTP method,支持 GET 和 POST。默认值为 GET。
  • spec.authProbes[].probe.http.disableRedirect 指定在认证验证期间是否禁用 HTTP 重定向。默认值为 false(允许自动重定向)。
  • spec.authProbes[].probe.http.httpHeaders 指定认证验证请求中要包含的 HTTP headers。
  • spec.authProbes[].probe.http.scheme 指定认证验证使用的 URI scheme。默认使用 connector 地址中的 scheme。
  • spec.authProbes[].probe.http.response.cel 指定认证验证所期望的响应。
    • 默认行为:成功时返回 200。
    • 自定义验证:配置 CEL 表达式后,若表达式求值为 true,则认证成功。

CEL 表达式可以使用以下变量:

变量类型说明
response.statusCodeintHTTP 状态码
response.bodyStringstring以字符串形式表示的响应体
response.headersmap[string][]string响应头
response.bodyobject解析为 JSON 的响应体

示例

以下 YAML 配置演示了在认证验证期间,系统将向 connector 地址发送带有 Authorization: abc header 的 GET https://example.com/ HTTP/1.1 请求。

kind: ConnectorClass
metadata:
  name: example-class
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
          response:
            cel: response.statusCode == 200  # Custom validation expression
---
kind: Connector
metadata:
  name: example
spec:
  connectorClassName: example-class
  address: https://example.com

使用 ConnectorClass API 进行探测

你可以配置 spec.authProbes[].probe.api,通过 ConnectorClass API 执行认证验证。首先必须在 ConnectorClass 规范中配置 spec.api。返回 200 表示认证成功,而返回 401 或 403 表示认证失败。更多关于 ConnectorClass API 的信息,请参见 ConnectorClass API。

  • spec.authProbes[].probe.api.path 指定认证验证的 API endpoint 路径。这是一个相对路径,在执行认证验证时会追加到从 ConnectorClass 的 spec.api 配置解析出的 API 地址后面。如果 spec.api 包含路径前缀,则在执行认证验证时会包含该路径前缀。

示例

以下 YAML 配置演示了在认证验证期间,系统将向 ConnectorClass API 发送 GET https://example-api.default.svc.cluster.local/api/auth/check HTTP/1.1 请求。

kind: ConnectorClass
metadata:
  name: example-class
spec:
  api:
    ref:
      kind: Service
      name: example-api
      namespace: default
    uri: /api
  authProbes:
    - authName: basicAuth
      probe:
        api:
          path: /auth/check # It is a relative path of the API address resolved from `spec.api` of connectorclass
---
kind: Connector
metadata:
  name: example
spec:
  connectorClassName: example-class
  address: https://example.com

自定义认证验证参数

某些认证验证场景可能需要额外参数,例如在验证对 Git repository 的访问时指定 repository 名称。这些参数可以通过 spec.authProbes[].params 定义。

kind: ConnectorClass
metadata:
  name: example-class
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
  • 表达式可用于 probe.http.httpHeaders、probe.http.path 和 probe.api.path 字段。
  • 表达式格式遵循 Go template 语法。
  • 支持的顶层字段包括:
    • .Connector:包含 Connector 资源自身的信息
    • .Secret:包含用于 Connector 认证的 Secret 数据
  • 表达式中可用的方法记录在 sprig 库中:
    • 例如:b64enc 用于对字符串进行 Base64 编码,trimPrefix 用于移除字符串前缀

示例

Basic Authentication 验证:

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 演示了基本认证验证:

  • path:使用 Connector 的 auth.params 中的 repository 值,构造路径为 /<repository>/info/refs?service=git-upload-pack
  • Authorization:当 Connector 配置了 Secret 时,username 和 password 字段会进行 Base64 编码,并包含在 Basic authentication header 中。

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

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

  • 在 proxy package 下定义规则
  • 生成一个 auth 对象,其结构如下:
    • position:注入认证的位置,例如 "header"、"query" 或 "body"
    • contentType:body 注入的 content type(可选,与 "body" 位置配合使用)
    • auth:认证键值对的 map

Rego 中可用的变量

变量类型说明
input.datamap[string]stringConnector 使用的 Secret 数据
input.request.headersmap[string][]string发送到后端工具的请求 headers
input.request.bodyobject发送到后端工具的请求 body
input.request.querymap[string][]string发送到后端工具的查询参数
input.request.methodstring发送到后端工具的 HTTP method
input.request.pathstring发送到后端工具的请求路径
input.request.hoststring发送到后端工具的请求 host

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

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

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

ConnectorClass API

ConnectorClass API 允许开发者通过额外的 HTTP API service 为 ConnectorClass 扩展 API 能力。这为 ConnectorClass 提供了一个 RESTful API,使客户端在使用 Connectors 时能够轻松访问工具中的资源。

如果不需要为工具提供自定义 API 能力,可以不定义 spec.api。

配置 API 地址

ConnectorClass API 在 spec.api 字段中配置。你可以通过三种方式指定 API service:

1. 通过 Kubernetes Service 引用:

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

2. 通过带有 URI path 前缀的 Service 引用:

如果 API 地址具有固定的 path 前缀,可以使用 spec.api.uri 指定:

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

3. 通过绝对 URI:

你也可以使用 spec.api.uri 指定 API 的绝对路径:

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

API 地址解析

无论使用哪种配置方式,最终解析得到的 API 地址都会存储在 status.api.address.url 中。例如:

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

更多信息请参见:

OpenAPI 描述

OpenAPI 描述是一个可选配置,主要有两个用途:

  • 标记 API 是自定义 API,还是使用 Connector Proxy 访问工具的原始 API
  • 提供 API 定义,以支持客户端动态表单中的 API 引用

你可以使用 spec.api.openapi 定义 OpenAPI 描述。其结构遵循 OpenAPI 3.0 规范。例如:

spec:
  api:
    openapi:
      openapi: "3.0.1"
      info:
        title: Git API
        version: "1.0.0"

你可以在 API paths 中定义 x-provider-type 扩展字段,用于标记 API 是自定义 API,还是使用 Proxy 访问工具的原始 API。有效值为 api 或 proxy。

x-provider-type 扩展的定义形式为:api.openapi.paths[<path>].<verb>[x-provider-type]

当使用 x-provider-type: proxy 时,你还可以在同一 operation 上定义 x-openapi-address 来选择后端地址:

  • 为空或省略:回退到 Connector.spec.address
  • 扩展名称:从 Connector.spec.addressExtensions[*].name 解析
  • 直接 URL:使用完整的 http/https 地址

示例:

spec:
  api:
    openapi:
      openapi: "3.0.1"
      info:
        title: Gitlab API
        version: "1.0.0"
      paths:
        /git/api:
          get:
            summary: Get Git API
            x-provider-type: api  # Use custom API
        /api/v4/projects:
          get:
            summary: Get Gitlab Projects API
            x-provider-type: proxy  # Use Proxy to access the tool's original API
            x-openapi-address: api
Info

当客户端请求 Connector API 时,Connectors 系统会根据当前 Connector 对应的 ConnectorClass 中 x-provider-type 的值,决定是使用自定义 API,还是直接使用 Connectors Proxy 访问工具的原始 API。若未提供该信息,或者没有匹配到任何 API path,系统默认使用 Connectors Proxy 访问工具的原始 API。

当你需要在动态表单中引用 API 时,需要在 spec.api.openapi 中进行额外配置。更多详情请参见 在动态表单中使用 Connectors API。

配置能力

配置能力定义了 ConnectorClass 向客户端提供的配置文件。这些文件可以通过 Connectors-CSI Driver 挂载到 Pods 中。

配置类型

  • 自定义配置:在 spec.configurations 中定义
  • 内置配置:由 Connectors-CSI Driver 自动提供(参见:内置配置)

自定义配置

配置通过 spec.configurations 指定:

kind: ConnectorClass
metadata:
  name: git
spec:
  configurations:
  - name: gitconfig
    data:
      .gitconfig: |
        [http "{{ .connector.status.proxyAddress }}"]
            extraHeader = Authorization: Basic {{ printf ":%s" .context.token | b64enc }}
        [url "{{ .connector.status.proxyAddress }}"]
            insteadOf = {{ .connector.spec.address }}

更多详情请参见:配置文件渲染

注意: spec.configurations 是可选的。未定义时,仅可使用内置配置。

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

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。更多信息

使用 Rego 从请求中提取令牌

在使用内置反向代理时,可以通过 spec.proxy.authExtractor 配置 Rego 规则,从客户端请求中提取令牌,使内置反向代理能够使用提取到的令牌验证客户端认证。

例如:

spec:
  proxy:
    authExtractor:
      rego: |
        package proxy
        auth = {
          "token": input.request.headers["Private-Token"][0]
        }

Rego 规则必须满足以下要求:

  • 规则必须定义在 proxy package 中
  • 使用 auth 变量返回令牌,令牌为 string 类型,例如:auth = { "token": "abcd1234" }
  • 如果无法提取令牌,则返回空字符串,例如:auth = { "token": "" }

Rego 中可用的变量如下:

keytypedescriptionExample
request.headersmap[string][]string发送到内置反向代理的请求 headersinput.request.headers["X-Token"][0]
request.bodyobject发送到内置反向代理的请求 bodyinput.request.body.token
request.querymap[string][]string发送到内置反向代理的请求查询参数input.request.query["token"][0]
request.methodstring发送到内置反向代理的请求 HTTP methodinput.request.method
request.pathstring发送到内置反向代理的请求路径input.request.path
request.hoststring发送到内置反向代理的请求 hostinput.request.host

注意:

  • headers 中的 Header key 使用 Canonical MIME Header Key 格式(首字母大写)
  • 实现 Rego 规则时,请确保逻辑健壮。例如,当 input.request.headers 为 null 或空时,返回空字符串。

示例

spec:
  proxy:
    authExtractor:
      rego: |
        package proxy

        default auth = {
          "token": ""
        }

        auth = {
          "token": input.request.headers["Private-Token"][0]
        } if {
          input.request.headers != null
          input.request.headers["Private-Token"] != null
          count(input.request.headers["Private-Token"]) > 0
        }

该示例通过以下方式演示了健壮的令牌提取:

  • 定义一个默认规则,返回空令牌字符串
  • 在访问 headers 之前,先检查其是否存在且不为 null
  • 验证特定 header key 是否存在且至少有一个值

更多高级 Rego 规则,请参见 Rego Policy Language 文档。 有关使用内置反向代理的更多信息,请参见 Connectors Proxy。

解析器类型

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 条件

Ready Condition 用于标记当前 ConnectorClass 的状态。它会汇总其他条件的状态。

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

APIReady 条件

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

状态原因说明
TrueNonAPI未配置 spec.api,当前 ConnectorClass 没有 API 能力
True已定义 spec.api,API service 正常
False已定义 spec.api,API 能力异常或检测本身异常
UnknownAPI 能力检测进行中

注意:

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

ProxyReady 条件

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

状态原因说明
TrueNonProxy未配置 spec.proxy,当前 ConnectorClass 没有 Proxy 能力
True已定义 spec.proxy,Proxy service 正常
False已定义 spec.proxy,Proxy 能力异常或检测本身异常
UnknownProxy 能力检测进行中

兼容性

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

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

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

建议在更新 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 }}

更多