ConnectorClass
目录
概述地址信息地址扩展参数认证信息认证类型认证参数可选认证存活探测使用 HTTP 请求进行探测使用 ConnectorClass API 进行探测认证探测使用 HTTP 请求进行探测使用 ConnectorClass API 进行探测自定义认证验证参数认证验证表达式基于 Rego 的认证逻辑配置Rego 中可用的变量Rego 策略示例高级 Rego 技术ConnectorClass API配置 API 地址API 地址解析OpenAPI 描述配置能力配置类型自定义配置用于可读性展示的元数据信息ConnectorClass Proxy使用 Rego 从请求中提取令牌解析器类型状态信息兼容性更多示例更多概述
ConnectorClass 是一种集群级资源,用于定义特定类型工具的访问模式和行为规范。
以下示例定义了一个支持基本认证的 hello-git 类型 connector:
在 ConnectorClass 中,通过描述以下信息来定义连接工具到平台的访问模式和行为规范:
- 工具访问地址的格式
- 支持的认证方法
- 如何检查工具的可访问性
- 如何验证认证的有效性
- 工具如何提供 API 能力
- 工具提供哪些配置能力
- 用于可读性展示的元数据
本文档还提供了示例,帮助读者更好地理解如何自定义 ConnectorClass。 示例
地址信息
地址信息定义了访问工具时使用的格式。当前支持 string 类型的地址配置。该地址信息限制了当前类型工具必须满足的字段类型约束。
此时表示,连接工具到平台的地址信息必须是 string 类型。
地址扩展
spec.addressExtensions 定义了当前工具类型的额外命名地址。其 schema 与 spec.params 相同:
spec.addressExtensions[].name- 扩展名称。在一个 ConnectorClass 中必须唯一。spec.addressExtensions[].type- 值类型。当前仅支持string。spec.addressExtensions[].default- 默认值(可选)。如果未设置,则该扩展在 Connector 中是必填项。spec.addressExtensions[].description- 描述(可选)。
当一个 connector 需要多个后端地址时,通常会使用该机制,例如一个 Web 访问地址和一个 API 地址。
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。
有关创建 Connectors 时的参数配置,请参见 Connector 文档。
结合 connectors-csi-driver 的能力,可以实现更灵活的配置。这在需要提供参数化配置时尤其有用。例如,在创建 git 类型 connector 时,用户可以提供 sslVerify 参数来控制 SSL 证书验证。更多详情请参见 ConnectorClass 配置 文档。
认证信息
认证类型
认证类型定义了用于工具认证的凭证类型。一个工具可以支持多种认证类型,允许用户在使用工具时进行选择。
用户可以通过以下方式唯一命名当前认证类型:
spec.auth.types[].name,该名称必须唯一且不能重复。spec.auth.types[].secretType,指定认证所需的Secret类型,对应于 Kubernetes Secret Type。
示例:
在内置 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)认证:
此定义要求工具 connector 使用的凭证包含 params 中指定的字段。
可选认证
某些工具支持在无需认证的情况下访问,这由 optional 字段标记,用于指示认证是否可选:
例如,以下配置表示 basicAuth 类型的凭证是可选的,而 sshAuth 类型的凭证是必需的。
此时,将这种类型的工具连接到平台时,可以省略 basicAuth 类型的认证。
存活探测
可访问性检查用于验证工具是否可以正常访问。此类检查的配置通过 livenessProbe 字段完成。
存活检查可以通过 HTTP 请求或 ConnectorClass API 执行。
使用 HTTP 请求进行探测
你可以配置 spec.livenessProbe.http,通过 HTTP 请求执行存活检查。
示例
以下片段表示使用 HTTP 请求进行检测。
当工具返回 200 状态码时,认为其可访问。
更多详情请参见 Authentication Probe 中的使用 HTTP 请求进行探测。其配置与此处相同,仅字段路径不同。
使用 ConnectorClass API 进行探测
你可以配置 spec.livenessProbe.api,通过 ConnectorClass API 执行存活检查。
示例
以下片段表示使用 ConnectorClass API 进行检测。
更多详情请参见 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 表达式可以使用以下变量:
示例
以下 YAML 配置演示了在认证验证期间,系统将向 connector 地址发送带有 Authorization: abc header 的 GET https://example.com/ HTTP/1.1 请求。
使用 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 请求。
自定义认证验证参数
某些认证验证场景可能需要额外参数,例如在验证对 Git repository 的访问时指定 repository 名称。这些参数可以通过 spec.authProbes[].params 定义。
认证验证表达式
配置 authProbes 时,可以使用表达式动态获取凭证信息或 Connector 元数据。
例如:
- 表达式可用于
probe.http.httpHeaders、probe.http.path和probe.api.path字段。 - 表达式格式遵循 Go template 语法。
- 支持的顶层字段包括:
.Connector:包含 Connector 资源自身的信息.Secret:包含用于 Connector 认证的 Secret 数据
- 表达式中可用的方法记录在 sprig 库中:
- 例如:
b64enc用于对字符串进行 Base64 编码,trimPrefix用于移除字符串前缀
- 例如:
示例
Basic Authentication 验证:
connector 将根据 ConnectorClass 中定义的配置执行认证验证。
上述 YAML 演示了基本认证验证:
path:使用 Connector 的auth.params中的repository值,构造路径为/<repository>/info/refs?service=git-upload-packAuthorization:当 Connector 配置了 Secret 时,username和password字段会进行 Base64 编码,并包含在 Basic authentication header 中。
基于 Rego 的认证逻辑配置
当工具 connector 需要更复杂的认证逻辑时,可以使用基于 Rego 的认证逻辑配置。
Rego 是一种声明式策略语言,可用于定义认证逻辑。在 ConnectorClass 中,Rego 策略通过 auth.types[].generator.rego 字段指定:
Rego 策略必须遵循以下规则:
- 在 proxy package 下定义规则
- 生成一个 auth 对象,其结构如下:
- position:注入认证的位置,例如 "header"、"query" 或 "body"
- contentType:body 注入的 content type(可选,与 "body" 位置配合使用)
- auth:认证键值对的 map
Rego 中可用的变量
Rego 策略示例
Basic Authentication
API Key Authentication
JSON Body Authentication
高级 Rego 技术
你可以使用 Rego 的条件逻辑来处理不同的认证方法:
条件认证
基于时间的认证
更多 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 引用:
2. 通过带有 URI path 前缀的 Service 引用:
如果 API 地址具有固定的 path 前缀,可以使用 spec.api.uri 指定:
3. 通过绝对 URI:
你也可以使用 spec.api.uri 指定 API 的绝对路径:
API 地址解析
无论使用哪种配置方式,最终解析得到的 API 地址都会存储在 status.api.address.url 中。例如:
更多信息请参见:
OpenAPI 描述
OpenAPI 描述是一个可选配置,主要有两个用途:
- 标记 API 是自定义 API,还是使用 Connector Proxy 访问工具的原始 API
- 提供 API 定义,以支持客户端动态表单中的 API 引用
你可以使用 spec.api.openapi 定义 OpenAPI 描述。其结构遵循 OpenAPI 3.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地址
示例:
当客户端请求 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 指定:
更多详情请参见:配置文件渲染
注意: spec.configurations 是可选的。未定义时,仅可使用内置配置。
用于可读性展示的元数据信息
ConnectorClass 是一个标准的 k8s 资源,可以通过 labels 和 annotations 标记自定义信息。
例如:
例如:
ConnectorClass Proxy
ConnectorClass Proxy 用于配置 ConnectorClass 的代理地址。
ConnectorClass Proxy 通过 spec.proxy 进行配置。例如:
Connector 将使用该代理地址将请求代理到 ConnectorClass。更多信息
使用 Rego 从请求中提取令牌
在使用内置反向代理时,可以通过 spec.proxy.authExtractor 配置 Rego 规则,从客户端请求中提取令牌,使内置反向代理能够使用提取到的令牌验证客户端认证。
例如:
Rego 规则必须满足以下要求:
- 规则必须定义在
proxypackage 中 - 使用
auth变量返回令牌,令牌为 string 类型,例如:auth = { "token": "abcd1234" } - 如果无法提取令牌,则返回空字符串,例如:
auth = { "token": "" }
Rego 中可用的变量如下:
注意:
headers中的 Header key 使用 Canonical MIME Header Key 格式(首字母大写)- 实现 Rego 规则时,请确保逻辑健壮。例如,当
input.request.headers为 null 或空时,返回空字符串。
示例
该示例通过以下方式演示了健壮的令牌提取:
- 定义一个默认规则,返回空令牌字符串
- 在访问 headers 之前,先检查其是否存在且不为 null
- 验证特定 header key 是否存在且至少有一个值
更多高级 Rego 规则,请参见 Rego Policy Language 文档。 有关使用内置反向代理的更多信息,请参见 Connectors Proxy。
解析器类型
ConnectorClass 的代理地址将根据指定的 resolver 类型进行解析。
resolver 类型通过注解 connectors.cpaas.io/proxy-resolver 进行配置。例如:
该字段是 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 进行配置。
注意:
- API 检测只会尝试请求链接,不会对任何 HTTP 返回值做判定。API service 的健康检查应依赖其自身的健康检查机制。
- 由于 API service 可能随时变化,API 的状态信息无法反映实时情况。建议客户端将该状态信息作为提示,而不是依赖它来阻止客户端行为。
ProxyReady 条件
表示为 ConnectorClass 配置的 Proxy service 的状态信息。Proxy service 通过 ConnectorClass 的 spec.proxy 进行配置。
兼容性
对 ConnectorClass 的更新可能会影响现有 Connectors。如果 ConnectorClass 存在不兼容变更,可能会导致先前创建的 Connectors 失效。以下是可能引发不兼容的一些变更:
-
认证信息变更:如果 ConnectorClass 修改了支持的认证类型或方法,可能会导致使用旧认证方式的 Connectors 无法正常工作。
-
配置信息变更:如果 ConnectorClass 的配置信息发生变化,例如移除了某个现有配置,可能会导致依赖旧配置的 Kubernetes workload 无法正常工作。
建议在更新 ConnectorClass 时确认影响范围,必要时创建新的 ConnectorClass。
更多示例
-
支持
basic-auth认证类型的 ConnectorClass -
自定义认证类型的 ConnectorClass
-
配置了
liveness probe的 ConnectorClass -
配置了
auth probe的 ConnectorClass -
完整的 Git connector 配置示例: