Connector API
目录
概述Connector API 地址与认证API 地址认证与授权访问原始工具 API写入方法(passthrough)使用x-openapi-address 选择后端地址自定义 APIAPI 定义API 路径查询参数分页响应格式OpenAPI 描述ConnectorClass API 扩展规范在 Dynamic Forms 中使用 Connectors APIConnectors Operator API后续步骤概述
在集群中集成工具后,可以为当前 Connector 提供一个 RESTful API,以便从工具中方便地获取资源。这些 API 统一通过 Connector API 暴露,使用户能够从当前 Connector 所指向的工具中获取资源。
Connectors 系统支持通过 API 访问工具资源的两种方式:
- 原始工具 API:通过 Proxy Service 访问工具的原始 API
- 自定义 API:使用为 ConnectorClass 提供的自定义 API
使用 Connectors API 时,客户端无需管理工具的原始认证凭据。客户端只需要具备访问该 Connector 的权限即可。对工具 API 请求的权限由 Connector 中配置的凭据(Secret)的权限决定。
Connector API 地址与认证
API 地址
Connector API 地址由三部分组成:
- Platform API 或集群 ingress 访问入口
- Connector API 相对路径
- 所请求工具的原始 API 路径或自定义 API 路径
在集群中创建 Connector 后,系统会自动将当前 Connector 的 API 路径记录到 <connector>.status.api.path 中。注意,该路径是相对于集群访问入口的相对路径。
最终的 Connector API 地址为:{platform_api_address}/{<connector>.status.api.path}/{api-path}
在 Alauda Container Platform 中,API 访问入口通常为 {platform_address}/clusters-rewrite/{cluster_name}。
认证与授权
认证遵循 Kubernetes 认证标准,并通过 Kubernetes 的认证与授权机制完成。请求用户必须对相应的 Connector 具备读取权限。目前仅支持 Bearer Token 认证。
在向工具发起最终请求时,将使用 Connector 指定的 Secret 信息进行认证。
默认情况下,当 enable-connector-apis-permissions 被禁用时,只要对 Connector 具有读取权限即可调用 Connectors API。
当 enable-connector-apis-permissions 被启用时,系统会对目标 Connector 额外执行一次 connectors/apis 权限检查。这是用于区分 Connector 发现与实际 API 使用的额外能力权限。
有关整体模型以及 connectors/apis 的含义,请参阅 Connectors 权限模型。
读取方法 GET、HEAD 和 OPTIONS 默认均已启用,并共享相同的授权链。HEAD(RFC 7231:不带 body 的 GET——用于资源存在性和元数据探测)以及 OPTIONS(安全/幂等的能力探测——用于 CORS 预检、API 发现和 SDK 功能检查)都会路由到 ConnectorClass OpenAPI 中声明的 get: operation,并在 RBAC 中使用 Kubernetes 动词 get。因此,只要授予 connectors/apis/<class> 上的单个 get 权限,就同时覆盖 GET / HEAD / OPTIONS;类作者无需单独声明 head: / options: operation。
写入方法(POST、PUT、DELETE、PATCH)由 enable-connector-apis-write-passthrough 单独控制。详情请参见下文的 写入方法(passthrough)。
有关 Kubernetes API 认证的更多信息,请参阅 Kubernetes 认证文档。
访问原始工具 API
当您的 ConnectorClass 提供 Proxy Service 功能时,您可以通过 Connector API 直接访问工具的原始 API。
例如,如果工具的原始 API 地址为 /api/v4/projects,则可以通过 Connector API 访问它。假设您在 default 命名空间中有一个名为 gitlab-connector 的 Connector,且该 Connector 的 API 路径为 /connectors/v1alpha1/default/gitlab-connector/path,则请求如下:
Proxy Service 功能可通过 ConnectorClass 规范进行配置。有关配置详情,请参阅 ConnectorClass Proxy。如需更深入地了解 Connectors Proxy 概念,请参阅 Connectors Proxy。
写入方法(passthrough)
默认情况下,Connectors API 网关仅接受 /connectors/v1alpha1/{namespace}/{connector}/path/{api-path} 上的 GET。写入方法——POST、PUT、DELETE、PATCH——受 enable-connector-apis-write-passthrough 功能开关控制,在该开关启用之前,会在路由层直接返回 HTTP 405 Method Not Allowed。
当该开关启用后,写请求会被转发到目标工具,并保留请求体、查询参数和请求头不变(仅将 auth header 替换为 Connector 中配置的凭据)。响应状态、响应体和响应头会原样返回给客户端。
写请求的授权遵循与 GET 相同的链路,并由 enable-connector-apis-permissions 控制:
-
enable-connector-apis-permissions=false(默认):只需要对Connector资源具有get权限。 -
enable-connector-apis-permissions=true:还会运行细粒度的connectors/apisSAR。在执行 SAR 之前,HTTP 方法会映射为标准的 Kubernetes 动词:现有角色如果只在
connectors/apis/*上授予了get,并不会自动获得写权限——管理员必须显式添加相应的写动词。例如,要授予用户通过 Connectors API 创建 GitLab 分支的能力,需要:
示例——通过 GitLab Connector 创建分支:
请求最终是否能在工具侧成功,取决于 Connector 所引用的 Secret 中配置的凭据。如果这些凭据在工具侧没有相应权限,则会原样返回工具原生的 401/403 响应(以及响应体)。
当匹配到的 OpenAPI operation 声明了 x-provider-type: proxy(或者未声明任何 operation——proxy 为默认值)时,支持向上游工具进行写方法 passthrough(POST / PUT / DELETE / PATCH)。这是推荐的设置,可将客户端请求透明转发到 GitLab、GitHub 或 Harbor 等工具,并保留原始 HTTP 方法、body 和 headers。
有关底层开关的配置详情,请参阅 enable-connector-apis-write-passthrough。
使用 x-openapi-address 选择后端地址
当 OpenAPI operation 使用 x-provider-type: proxy 时,可以选择性地设置 x-openapi-address 来控制请求应使用哪个后端地址。
支持的选择器形式:
- 为空或未设置:回退到
Connector.spec.address。 - 扩展名:根据
name从Connector.spec.addressExtensions中解析。 - 直接地址:完整的
http/httpsURL。
示例:
在此示例中:
/repos/{owner}/{repo}/pulls使用名为api的 connector extension。/search/code使用直接 URLhttps://api.github.com。- 如果省略
x-openapi-address,请求将使用Connector.spec.address。
如果 x-openapi-address 引用了不存在的扩展名或无效的直接 URL,请求将被拒绝。
自定义 API
当工具的原始 API 无法满足您的需求,或者 ConnectorClass 未提供 Proxy Service 功能时,您可以为当前 ConnectorClass 提供一个自定义 API 服务,以满足您的需求。
自定义 API 服务可以通过 ConnectorClass 的 spec.api 字段进行配置,从而让 Connectors 系统能够发现并使用它。有关配置详情,请参阅 ConnectorClass API。
此外,为了让系统能够识别该 API 是自定义 API,还需要通过 spec.api.openapi 字段配置 OpenAPI 描述。
API 定义
API 路径
自定义 API 提供的 API 路径可以在扩展 API 服务中自由定义。推荐格式为 /<connectorclass-name>/xxx。
结合上文的 API 地址与认证方式,下面给出一个请求示例。假设您在 default 命名空间中有一个名为 git-connector 的 Connector,且自定义 API 路径为 /git/gitrefs,则请求如下:
查询参数
查询参数由具体的 ConnectorClass API Specification 决定。
分页
分页信息通过查询参数表示:
响应格式
当返回列表时,响应结构如下:
当响应不是 200 时,返回的数据结构应符合 k8s status。
例如:
字段定义和枚举值与 k8s status 保持一致。
OpenAPI 描述
除了提供自定义 API 服务之外,还需要在 ConnectorClass 的 spec.api.openapi 字段中配置 OpenAPI 描述信息,以便系统识别该 API 为自定义 API。
示例:
系统会根据 spec.api.openapi 描述,自动将自定义 API 转发到 ConnectorClass API 地址。
有关 spec.api.openapi 的配置详情,请参阅 ConnectorClass OpenAPI 描述。如需更多使用示例,请参阅 在 Dynamic Forms 中使用 Connectors API。
ConnectorClass API 扩展规范
开发者可以扩展 ConnectorClass 的 API 能力,为用户提供更丰富的资源获取能力。
在 Dynamic Forms 中使用 Connectors API
Connector API 可以提供给 UI 客户端,尤其适用于动态表单场景,UI 客户端可以灵活配置要调用的 API 请求。
为此,您需要通过 ConnectorClass 的 spec.api.openapi 字段配置 OpenAPI 描述信息,该配置与 dynamic form DSL 协同工作,以实现前端动态表单渲染。
动态表单描述通常在 资源接口 中提供。更多细节请参阅 资源接口。
Connectors Operator API
Connectors Operator API 是 Connectors API 提供的一组 RESTful API,用于让用户获取关于 Connectors 的信息。
API 路径为 {platform_address}/clusters-rewrite/{cluster_name}/connectors-operator/{api-path}。
当前提供的 API 包括:
-
GET /connectors-operator/featureflags:返回当前集群中 Connectors 系统的功能开关信息响应体示例:
权限要求:需要具备访问 ConnectorClass 的权限。
有关各功能开关的含义及其配置方式,请参阅 Feature Flags。