连接器 API
目录
概述Connector API 地址和认证API 地址认证与授权访问原始工具 API写方法(透传)使用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 会自动将当前 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 使用的额外 capability 权限。
关于整体模型以及 connectors/apis 的含义,请参见 Connectors Permission Model。
读方法 GET、HEAD 和 OPTIONS 默认全部启用,并共享相同的授权链。HEAD(RFC 7231:不带 body 的 GET,用于资源存在性和元数据探测)以及 OPTIONS(安全/幂等的能力探测,用于 CORS 预检、API 发现和 SDK 功能检查)都会路由到 ConnectorClass OpenAPI 中声明的 get: 操作,并在 RBAC 中使用 Kubernetes 动词 get。因此,在 connectors/apis/<class> 上授予单个 get 即可覆盖 GET / HEAD / OPTIONS;class 作者无需单独声明 head: / options: 操作。
写方法(POST、PUT、DELETE、PATCH)由 enable-connector-apis-write-passthrough 标志单独控制。更多详情请参见下面的 写方法(透传)。
有关 Kubernetes API 认证的更多信息,请参阅 Kubernetes Authentication documentation。
访问原始工具 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。
写方法(透传)
默认情况下,Connectors API 网关仅接受 /connectors/v1alpha1/{namespace}/{connector}/path/{api-path} 上的 GET。写方法——POST、PUT、DELETE、PATCH——由 enable-connector-apis-write-passthrough 特性标志控制,在该标志启用之前会在路由层返回 HTTP 405 Method Not Allowed 拒绝请求。
当该标志启用后,写请求会转发到目标工具,并保留请求体、查询参数和头部信息(仅会将认证头替换为在 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 操作声明了 x-provider-type: proxy 时(或者未声明任何操作——proxy 是默认值),支持将写方法(POST / PUT / DELETE / PATCH)透传到上游工具。这是推荐的设置,用于将客户端请求——包括原始 HTTP 方法、body 和 headers——透明转发到 GitLab、GitHub 或 Harbor 等工具。
关于底层标志的配置细节,请参阅 enable-connector-apis-write-passthrough。
使用 x-openapi-address 选择后端地址
当 OpenAPI 操作使用 x-provider-type: proxy 时,您可以选择性地设置 x-openapi-address 来控制请求应使用哪个后端地址。
支持的选择器形式:
- 为空或未设置:回退到
Connector.spec.address。 - 扩展名:通过
name从Connector.spec.addressExtensions中解析。 - 直接地址:完整的
http/httpsURL。
示例:
在此示例中:
/repos/{owner}/{repo}/pulls使用名为api的 connector 扩展。/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 Address。
关于 spec.api.openapi 的配置细节,请参阅 ConnectorClass OpenAPI Description。更多使用示例,请参阅 在 Dynamic Forms 中使用 Connectors API。
ConnectorClass API 扩展规范
开发者可以扩展 ConnectorClass 的 API 能力,为用户提供更丰富的资源获取能力。
请参阅 ConnectorClass API Extension Specification。
在 Dynamic Forms 中使用 Connectors API
Connector API 可以提供给 UI 客户端,特别适用于 Dynamic Forms 场景,在该场景下 UI 客户端可以灵活配置要调用的 API 请求。
为实现这一点,您需要通过 ConnectorClass 的 spec.api.openapi 字段配置 OpenAPI 描述信息,它将与 dynamic form DSL 协同工作,实现前端 Dynamic Forms 渲染。
Dynamic Form 描述通常在 Resource Interface 中提供。更多细节请参阅 Resource Interface。
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 系统的 feature flags 信息响应体示例:
权限要求:需要拥有访问 ConnectorClass 的权限。
关于各个 feature flag 的含义及其配置方式,请参阅 Feature Flags。