Connector API

Overview

在集群内集成工具后，可以为当前 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 地址由三部分组成：

平台 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}

Info

在 Alauda Container Platform 中，API 访问入口通常为 {platform_address}/clusters-rewrite/{cluster_name}。

认证与授权

认证遵循 Kubernetes 认证标准，通过 Kubernetes 的认证和授权机制完成。请求用户必须对对应的 Connector 拥有读取权限。目前仅支持 Bearer Token 认证。

向工具发起最终请求时，将使用 Connector 指定的 Secret 信息进行认证。

有关 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，请求示例如下：

K8S_TOKEN=xxxx

curl -H "Authorization: Bearer ${K8S_TOKEN}" "https://platform.example.com/connectors/v1alpha1/default/gitlab-connector/path/api/v4/projects"

Proxy Service 功能可通过 ConnectorClass 规范进行配置。配置详情请参阅 ConnectorClass Proxy。关于 Connectors Proxy 概念的深入理解，请参阅 Connectors Proxy。

自定义 API

当工具的原始 API 无法满足需求或 ConnectorClass 不提供 Proxy Service 功能时，可以为当前 ConnectorClass 提供自定义 API 服务以满足需求。

自定义 API 服务可通过 ConnectorClass 的 spec.api 字段进行配置，使 Connectors 系统能够发现并使用该服务。配置详情请参阅 ConnectorClass API。

此外，为使系统识别该 API 为自定义 API，需要通过 spec.api.openapi 字段配置 OpenAPI 描述。

API 定义

API 路径

自定义 API 提供的路径可在扩展 API 服务中自由定义，推荐格式为 /<connectorclass-name>/xxx。

结合上述 API 地址和认证，以下是请求示例。假设您在 default 命名空间下有一个名为 git-connector 的 Connector，自定义 API 路径为 /git/gitrefs，请求示例如下：

K8S_TOKEN=xxxx

curl -H "Authorization: Bearer ${K8S_TOKEN}" "https://platform.example.com/connectors/v1alpha1/default/git-connector/path/git/gitrefs"

查询参数

查询参数由具体的 ConnectorClass API 规范决定。

分页

分页信息通过查询参数表示：

参数名	类型	是否必需	说明
page	int	否	页码
itemsPerPage	int	否	每页条目数

响应格式

返回列表时，响应结构如下：

字段名	类型	是否必需	说明
listMeta	ListMeta	是	列表元数据
listMeta.totalItems	int	是	请求资源总数，客户端可用以分析分页信息
items	[]	是	列表中的数据项；数据结构由 ConnectorClass API 决定

{
    "listMeta":{
        "totalItems":0
    },
    "items": [
        {

        }
    ]
}

当响应非 200 时，返回的数据结构应符合 k8s status。

例如：

{
    "status": "Failure",
    "message": "api address of connectorclass 'git-noapi' is not resolved",
    "reason": "BadRequest",
    "code": 400,
    "details": null
}

字段定义和枚举值与 k8s status 保持一致。

OpenAPI 描述

除了提供自定义 API 服务外，还需在 ConnectorClass 的 spec.api.openapi 字段配置 OpenAPI 描述信息，以便系统识别该 API 为自定义 API。

示例：

kind: ConnectorClass
metadata:
  name: gitlab
spec:
  api:
    ref:  # 自定义 API 服务引用
      name: connectors-gitlab-api
      namespace: connectors-system
    openapi:
      openapi: "3.0.1"
      info:
        title: GitLab Custom API
        version: "1.0.0"
      paths:
        /gitlab/custom-api:  # 定义在 connectors-gitlab-api 服务中的自定义 API
          get:
            x-provider-type: api  # 表明该 API 是自定义 API
            summary: 请求自定义 API
            responses:
              "200":
                description: 自定义 API 响应

系统将根据 spec.api.openapi 描述自动将自定义 API 转发至 ConnectorClass API 地址。

有关 spec.api.openapi 的配置详情，请参阅 ConnectorClass OpenAPI 描述。更多使用示例，请参阅动态表单中使用 Connectors API。

ConnectorClass API 扩展规范

开发者可以为 ConnectorClass 扩展 API 能力，为用户提供更丰富的资源获取能力。

请参阅 ConnectorClass API 扩展规范。

在动态表单中使用 Connectors API

Connector API 可提供给 UI 客户端，尤其适用于动态表单场景，UI 客户端可灵活配置调用的 API 请求。

为实现此功能，需要通过 ConnectorClass 的 spec.api.openapi 字段配置 OpenAPI 描述信息，配合动态表单 DSL 实现前端动态表单渲染。

动态表单描述通常在资源接口中提供。详情请参阅资源接口。

#Connector API

#目录

#Overview

#Connector API 地址与认证

#API 地址

#认证与授权

#访问原始工具 API

#自定义 API

#API 定义

#API 路径

#查询参数

#分页

#响应格式

#OpenAPI 描述

#ConnectorClass API 扩展规范

#在动态表单中使用 Connectors API