Alauda DevOps Connectors Docs
  • 简体中文

    • 连接器类

    目录

    概述地址信息地址扩展参数认证信息认证类型认证参数可选认证存活探针使用 HTTP 请求进行探测使用 ConnectorClass API 进行探测认证探针使用 HTTP 请求进行探测使用 ConnectorClass API 进行探测自定义认证验证参数认证验证表达式基于 Rego 的认证逻辑配置Rego 中可用的变量Rego 策略示例高级 Rego 技巧ConnectorClass API配置 API 地址API 地址解析OpenAPI 描述配置能力配置类型自定义配置用于可读性展示的元数据信息ConnectorClass Proxy使用 Rego 从请求中提取 token解析器类型状态信息兼容性更多示例更多

    概述

    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。Examples

    地址信息

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

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

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

    地址扩展

    spec.addressExtensions 定义了当前工具类型的附加命名地址。其使用与 spec.params 相同的 schema：

    • 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 Configuration文档。

    认证信息

    认证类型

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

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

    • 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 type，可以省略参数。例如：

    • 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 中的 Probe using HTTP Requests。除字段路径外，其配置是相同的。

    使用 ConnectorClass API 进行探测

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

    示例

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

    spec:
  livenessProbe:
    api:
      path: /

    更多详情请参阅Authentication Probe 中的 Probe using ConnectorClass API。除字段路径外，其配置是相同的。

    认证探针

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

    • spec.authProbes[].authName 指定要验证的认证类型，且必须与 spec.auth.types[].name 中定义的名称之一匹配。

    认证验证可以使用 HTTP 请求或 ConnectorClass API 执行。

    使用 HTTP 请求进行探测

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

    • spec.authProbes[].probe.http.host 指定认证验证的目标主机。默认使用 connector 地址中的主机。
    • spec.authProbes[].probe.http.path 指定认证验证的请求路径。这是一个绝对路径，在执行探针时会追加到从 connector 的 spec.address 解析出的主机 URI 后面。如果 spec.address 包含路径前缀，则在认证验证时会忽略该前缀。若要包含路径前缀，请使用 Authentication Check Expressions 动态获取它。
    • spec.authProbes[].probe.http.method 指定认证验证使用的 HTTP 方法，支持 GET 和 POST。默认值为 GET。
    • spec.authProbes[].probe.http.disableRedirect 指定在认证验证期间是否禁用 HTTP 重定向。默认值为 false（允许自动重定向）。
    • spec.authProbes[].probe.http.httpHeaders 指定认证验证请求中包含的 HTTP 头。
    • 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 头的 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 表示认证失败。More about ConnectorClass API。

    • spec.authProbes[].probe.api.path 指定认证验证的 API 端点路径。这是一个相对路径，在执行认证验证时会追加到从 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 仓库的访问权限时指定仓库名称。这些参数可以使用 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 用于移除字符串前缀

    示例

    基本认证验证：

    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 认证头中。

    基于 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 包下定义规则
    • 生成一个 auth 对象，结构如下：
      • position：认证注入位置，例如 "header"、"query" 或 "body"
      • contentType：用于 body 注入的内容类型（可选，仅在 "body" 位置下使用）
      • auth：认证键值对的 Map

    Rego 中可用的变量

    变量类型描述
    input.datamap[string]string用于 Connector 的 Secret 数据
    input.request.headersmap[string][]string发送到后端工具的请求头
    input.request.bodyobject发送到后端工具的请求正文
    input.request.querymap[string][]string发送到后端工具的查询参数
    input.request.methodstring发送到后端工具的 HTTP 方法
    input.request.pathstring发送到后端工具的请求路径
    input.request.hoststring发送到后端工具的请求主机

    Rego 策略示例

    基本认证
    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 认证
    spec:
  auth:
    types:
    - name: apikey-rego-auth
      secretType: Opaque
      generator:
        rego: |
          package proxy
          auth = {
            "position": "query",
            "auth": {
              "api_key": input.data.apikey
            }
          }
    JSON Body 认证
    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 服务扩展 ConnectorClass 的 API 能力。这为 ConnectorClass 提供了一个 RESTful API，使客户端在使用 Connectors 时能够轻松访问工具内部资源。

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

    配置 API 地址

    ConnectorClass API 在 spec.api 字段中进行配置。你可以通过三种方式指定 API 服务：

    1. 通过 Kubernetes Service 引用：

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

    2. 通过带有 URI 路径前缀的 Service 引用：

    如果 API 地址有固定的路径前缀，可以通过 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 路径中定义 x-provider-type 扩展字段，以标记 API 是自定义 API 还是使用 Proxy 访问工具的原始 API。有效值为 api 或 proxy。

    x-provider-type 扩展字段的定义为：api.openapi.paths[<path>].<verb>[x-provider-type]

    当使用 x-provider-type: proxy 时，你还可以在同一操作上定义 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 路径时，系统默认使用 Connectors Proxy 访问工具的原始 API。

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

    配置能力

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

    配置类型

    • 自定义配置：在 spec.configurations 中定义
    • 内置配置：由 Connectors-CSI Driver 自动提供（参见：Built-in Configurations）

    自定义配置

    配置通过 spec.configurations 指定：

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

    更多详情请参见：Configuration File Rendering

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

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

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

    例如：

    KeyDescription
    ui.cpaas.io/iconThe icon for ConnectorClass, optional. Format: data:image/svg+xml;base64,PD94bWwgdmVyc2...
    cpaas.io/display-nameThe display name for ConnectorClass, optional.
    cpaas.io/descriptionThe description for ConnectorClass, optional.
    connectors.cpaas.io/readmeUsage instructions for ConnectorClass, optional. Typically used for custom scenarios when docs-link cannot be provided. Supports Markdown format.
    connectors.cpaas.io/docs-linkDocumentation link for ConnectorClass, optional. Relative or absolute path.

    例如：

    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。More information

    使用 Rego 从请求中提取 token

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

    例如：

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

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

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

    Rego 中可用的变量如下：

    keytypedescriptionExample
    request.headersmap[string][]string发送到内置反向代理的请求头input.request.headers["X-Token"][0]
    request.bodyobject发送到内置反向代理的请求正文input.request.body.token
    request.querymap[string][]string发送到内置反向代理的请求查询参数input.request.query["token"][0]
    request.methodstring发送到内置反向代理的 HTTP 方法input.request.method
    request.pathstring发送到内置反向代理的请求路径input.request.path
    request.hoststring发送到内置反向代理的请求主机input.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
        }

    该示例通过以下方式演示了健壮的 token 提取：

    • 定义一个默认规则，返回空的 token 字符串
    • 在访问之前检查 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 Condition

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

    • 当其他 Conditions 都为 True 时，当前 Condition 为 True。
    • 当任意其他 Condition 为 False 时，当前 Condition 为 False。
    • 当任意其他 Condition 为 Unknown 时，当前 Condition 为 Unknown。

    APIReady Condition

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

    StatusReasonDescription
    TrueNonAPIspec.api 未配置，当前 ConnectorClass 不具备 API 能力
    True已定义 spec.api，API 服务正常
    False已定义 spec.api，API 能力异常或检测本身异常
    UnknownAPI 能力检测进行中

    注意：

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

    ProxyReady Condition

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

    StatusReasonDescription
    TrueNonProxyspec.proxy 未配置，当前 ConnectorClass 不具备 Proxy 能力
    True已定义 spec.proxy，Proxy 服务正常
    False已定义 spec.proxy，Proxy 能力异常或检测本身异常
    UnknownProxy 能力检测进行中

    兼容性

    对 ConnectorClass 的更新可能会影响现有 Connectors。如果 ConnectorClass 发生不兼容变更，可能导致之前创建的 Connectors 失效。以下是一些可能导致不兼容的变更：

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

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

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

    更多