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.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 类型,可以省略参数。例如:
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 结合挂载到 Pod 中。
如果客户端在访问工具时不需要依赖配置信息,则可以将 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 添加自定义信息。
例如:
例如:
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。更多信息
Resolver 类型
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 进行配置。
注意:
- API 检测只会尝试请求链接,不会对 HTTP 返回值进行判断。API 服务的健康检查应依赖 API 服务自身的健康检查机制。
- 由于 API 服务可能随时变化,API 的状态信息无法反映实时情况。建议客户端将该状态信息作为提示,而不要依赖它来阻止客户端行为。
ProxyReady Condition
表示为 ConnectorClass 配置的 Proxy 服务的状态信息。Proxy 服务通过 ConnectorClass 的 spec.proxy 进行配置。
兼容性
对 ConnectorClass 的更新可能会影响现有的 Connectors。如果 ConnectorClass 存在不兼容的更改,可能会导致之前创建的 Connectors 失效。以下是一些可能导致不兼容的更改:
-
认证信息的更改:如果 ConnectorClass 修改了支持的认证类型或方法,可能会导致使用旧认证方式的 Connectors 无法正常工作。
-
配置信息的更改:如果 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 }}
更多