ConnectorClass
目录
概述地址信息参数认证信息认证类型认证参数可选认证存活探针通过 HTTP 请求进行探测通过 ConnectorClass API 进行探测认证探测通过 HTTP 请求进行探测通过 ConnectorClass API 进行探测自定义认证校验参数认证校验表达式基于 Rego 的认证逻辑配置Rego 策略示例高级 Rego 技巧ConnectorClass API配置能力用于可读性展示的元数据信息ConnectorClass 代理Resolver 类型状态信息兼容性更多示例更多概述
ConnectorClass 是一种集群级资源,用于定义特定类型工具的访问模式和行为规范。
以下示例定义了一个支持基本认证的 hello-git 类型连接器:
在 ConnectorClass 中,通过描述以下信息来定义工具连接平台时的访问模式和行为规范:
- 工具访问地址的格式
- 支持的认证方式
- 如何检查工具的可访问性
- 如何验证认证的有效性
- 工具如何提供 API 能力
- 工具提供了哪些配置能力
- 用于可读性展示的元数据
本文档还提供了示例,帮助读者更好地理解如何自定义 ConnectorClass。示例
地址信息
地址信息定义了访问工具所使用的格式。目前支持字符串类型的地址配置。该地址信息限制了当前类型工具必须满足的字段类型约束。
此时,它表示连接工具到平台的地址信息必须为 string 类型。
参数
参数用于在创建连接器时定义额外参数。
你可以通过 connectorclass 的 spec.params 字段定义连接器创建时所需的参数。
spec.params[].name- 参数名称。spec.params[].type- 参数类型。目前仅支持string类型。spec.params[].default- 参数默认值(可选)。如果提供了默认值,用户在创建连接器时可以省略该参数。spec.params[].description- 参数描述(可选)。
例如,以下定义允许用户在创建 git 类型连接器时提供 sslVerify 参数,默认值为 true。
有关创建 Connectors 时的参数配置,请参考 Connector 文档。
结合 connectors-csi-driver 的能力,这使得配置更加灵活。这在需要提供参数化配置时尤其有用。例如,在创建 git 类型连接器时,用户可以提供 sslVerify 参数来控制 SSL 证书校验。更多详情请参考 ConnectorClass 配置 文档。
认证信息
认证类型
认证类型定义了用于工具认证的凭证类型。一个工具可以支持多种认证类型,允许用户在使用工具时进行选择。
用户可以通过以下方式为当前认证类型定义唯一名称:
spec.auth.types[].name,该名称必须唯一且不能重复。spec.auth.types[].secretType,用于指定认证所需的Secret类型,对应 Kubernetes Secret Type。
示例:
在内置的 K8S Secret Type 中,除了 Opaque 之外,其余类型都具有字段约束。用户在提供 Secret 时,必须确保 Secret 的字段与该类型约束相匹配。
使用 Opaque 类型时,必须声明认证参数。
与 k8s 一样,你也可以使用自己的 Secret Type。此时,必须声明认证参数。
认证参数
通过 spec.auth.types[].params 定义认证过程中凭证所需的参数。
对于字段定义明确的标准 Kubernetes secret 类型,可以省略参数。例如:
kubernetes.io/basic-auth:用户名和密码认证kubernetes.io/ssh-auth:SSH 密钥认证
对于自定义认证类型,你可以定义所需的认证参数,此时 secretType 会标记为 Opaque 或自定义名称。
例如,GitLab 的 Personal Access Token(PAT)认证:
该定义要求工具连接器中使用的凭证包含 params 中指定的字段。
可选认证
某些工具支持无需认证即可访问,通过 optional 字段标记认证是否可选:
例如,以下配置表示 basicAuth 的凭证是可选的,而 sshAuth 的凭证是必填的。
此时,将该类型工具连接到平台时,可以省略 basicAuth 类型的认证。
存活探针
可访问性检查用于验证工具是否可以正常访问。此类检查的配置通过 livenessProbe 字段完成。
可以使用 HTTP 请求或 ConnectorClass API 进行存活检查。
通过 HTTP 请求进行探测
你可以配置 spec.livenessProbe.http,通过 HTTP 请求执行存活检查。
示例
以下片段表示使用 HTTP 请求进行检测。
当工具返回 200 状态码时,即认为其可访问。
更多详情请参考 认证探测中的通过 HTTP 请求进行探测。其配置与此相同,仅字段路径不同。
通过 ConnectorClass API 进行探测
你可以配置 spec.livenessProbe.api,通过 ConnectorClass API 执行存活检查。
示例
以下片段表示使用 ConnectorClass API 进行检测。
更多详情请参考 认证探测中的通过 ConnectorClass API 进行探测。其配置与此相同,仅字段路径不同。
认证探测
认证校验用于验证此类型工具认证凭证的有效性。如果不需要认证校验,可以省略 authProbes 字段。
spec.authProbes[].authName指定正在校验的认证类型,且必须与spec.auth.types[].name中定义的名称之一匹配。
认证校验可以通过 HTTP 请求或 ConnectorClass API 执行。
通过 HTTP 请求进行探测
你可以配置 spec.authProbes[].probe.http,通过 HTTP 请求执行认证校验。
spec.authProbes[].probe.http.host指定认证校验的目标主机。默认值为连接器地址中的主机。spec.authProbes[].probe.http.path指定认证校验的请求路径。该路径是一个绝对路径,在执行探测时会追加到从连接器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 headers。spec.authProbes[].probe.http.scheme指定认证校验使用的 URI scheme。默认值为连接器地址中的 scheme。
示例
以下 YAML 配置演示了在认证校验期间,系统会向连接器地址发送带有 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。
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 请求。
自定义认证校验参数
某些认证校验场景可能需要额外参数,例如在验证对 Git 仓库的访问时指定仓库名称。这些参数可以通过 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用于移除字符串前缀
- 例如:
示例
基本认证校验:
连接器将根据 ConnectorClass 中定义的配置执行认证校验。
上面的 YAML 演示了基本认证校验:
path:使用 Connector 的auth.params中的repository值,将路径构造为/<repository>/info/refs?service=git-upload-packAuthorization:当 Connector 配置了 Secret 时,username和password字段会进行 Base64 编码,并包含在 Basic authentication header 中。
基于 Rego 的认证逻辑配置
当工具连接器需要更复杂的认证逻辑时,可以使用基于 Rego 的认证逻辑配置。
Rego 是一种声明式策略语言,允许你定义认证逻辑。在 ConnectorClass 中,Rego 策略通过 auth.types[].generator.rego 字段指定:
Rego 策略必须遵循以下规则:
- 在 proxy package 下定义规则
- 生成具有以下结构的 auth 对象:
- position:注入认证信息的位置,例如
"header"、"query"或"body" - contentType:body 注入时的内容类型(可选,与
"body"位置配合使用) - auth:认证键值对映射
- position:注入认证信息的位置,例如
Rego 策略示例
基本认证
API Key 认证
JSON Body 认证
高级 Rego 技巧
你可以使用 Rego 的条件逻辑来处理不同的认证方式:
条件认证
基于时间的认证
更多 Rego 语言详情请参考:
ConnectorClass API
为当前 ConnectorClass 提供一个 RESTful API,使客户端在使用 Connectors 时能够轻松访问工具中的资源。
如果工具不需要提供 API 能力,则可以不定义 spec.api。
ConnectorClass API 需要在 spec.api 字段中配置,例如:
你可以通过 spec.api.ref 指定 API 的 Service 信息。如果 ConnectorClass 的 API 地址具有固定前缀,可以通过 spec.api.uri 指定。例如:
此外,你还可以使用 spec.api.uri 指定 API 的绝对路径。例如:
无论采用哪种形式,最终解析得到的 API 地址都会存储在 status.api.address.url 中。例如:
通过 service 指定 connectorclass API:
通过 uri 指定 connectorclass API:
通过 svc 指定 connectorclass API,同时使用 spec.api.uri 指定 API path:
更多信息请参考:
配置能力
配置能力用于定义该类型工具的配置信息。结合 connectors-csi-driver,这些配置信息可以挂载到 Pods 中。
如果客户端在访问工具时不需要依赖配置信息,则可以不定义 spec.configurations。
配置信息通过 spec.configurations 指定。例如:
通常,我们可以为某一类工具指定特定类型的配置信息,以便在使用时进行配置。例如:
- 对于
git类型工具,提供.gitconfig配置 - 对于
oci registry类型工具,提供config.json配置
配置内容支持使用变量,在挂载时可以动态渲染。
更多配置使用示例,请参考 connectors csi driver 文档。
用于可读性展示的元数据信息
ConnectorClass 是一个标准的 k8s 资源,可以通过 labels 和 annotations 添加自定义信息。
例如:
例如:
ConnectorClass 代理
ConnectorClass Proxy 用于配置 ConnectorClass 的代理地址。
ConnectorClass Proxy 通过 spec.proxy 进行配置。例如:
Connector 会使用该代理地址将请求转发到 ConnectorClass。更多信息
Resolver 类型
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 Condition
Ready Condition 用于标记当前 ConnectorClass 的状态。它会汇总其他条件的状态。
- 当其他 Conditions 都为 True 时,当前 Condition 为 True。
- 当任意其他 Condition 为 False 时,当前 Condition 为 False。
- 当任意其他 Condition 为 Unknown 时,当前 Condition 为 Unknown。
APIReady Condition
表示为 ConnectorClass 配置的 API 服务的状态信息。API 服务通过 ConnectorClass 的 spec.api 进行配置。
注意:
- API 检测只会尝试请求链接,不会对任何 HTTP 返回值进行判断。API 服务的健康检查应依赖 API 服务自身的健康检查机制。
- 由于 API 服务可能随时变化,API 的状态信息无法反映实时信息。建议客户端将该状态信息视为提示,而不是依赖它来阻止客户端行为。
ProxyReady Condition
表示为 ConnectorClass 配置的 Proxy 服务的状态信息。Proxy 服务通过 ConnectorClass 的 spec.proxy 进行配置。
兼容性
对 ConnectorClass 的更新可能会影响现有 Connectors。如果 ConnectorClass 存在不兼容变更,可能会导致之前创建的 Connectors 失效。以下是一些可能导致不兼容的变更:
-
认证信息变更:如果 ConnectorClass 修改了支持的认证类型或认证方式,可能会导致使用旧认证方式的 Connectors 无法正常工作。
-
配置信息变更:如果 ConnectorClass 的配置信息发生变化,例如移除了已有配置,可能会导致依赖旧配置的 Kubernetes workloads 无法正常工作。
建议在更新 ConnectorClass 时确认影响范围,必要时创建新的 ConnectorClass。
更多示例
-
支持
basic-auth认证类型的 ConnectorClass -
自定义认证类型的 ConnectorClass
-
配置了
liveness probe的 ConnectorClass -
配置了
auth probe的 ConnectorClass -
完整的 Git 连接器配置示例: