Connector 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}

Info

在 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,则请求如下:

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。

写入方法(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/apis SAR。在执行 SAR 之前,HTTP 方法会映射为标准的 Kubernetes 动词:

    HTTP methodKubernetes verb
    GETget
    HEADget
    OPTIONSget
    POSTcreate
    PUTupdate
    DELETEdelete
    PATCHpatch

    现有角色如果只在 connectors/apis/* 上授予了 get,并不会自动获得写权限——管理员必须显式添加相应的写动词。例如,要授予用户通过 Connectors API 创建 GitLab 分支的能力,需要:

    apiVersion: rbac.authorization.k8s.io/v1
    kind: ClusterRole
    metadata:
      name: gitlab-connector-branch-writer
    rules:
      - apiGroups: ["connectors.alauda.io"]
        resources: ["connectors"]
        verbs: ["get"]
      - apiGroups: ["connectors.alauda.io"]
        resources:
          - "connectors/apis/gitlab"          # subresource level — covers any GitLab path
          # or scope to a specific path pattern declared in the ConnectorClass openapi:
          # - "connectors/apis/gitlab/apis/v4/projects/{projectId}/repository/branches"
        verbs: ["create"]                     # add "update", "delete", or "patch" as needed

示例——通过 GitLab Connector 创建分支:

K8S_TOKEN=xxxx

curl -X POST \
  -H "Authorization: Bearer ${K8S_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"branch":"feature-foo","ref":"main"}' \
  "https://platform.example.com/connectors/v1alpha1/default/gitlab-connector/path/api/v4/projects/123/repository/branches"

请求最终是否能在工具侧成功,取决于 Connector 所引用的 Secret 中配置的凭据。如果这些凭据在工具侧没有相应权限,则会原样返回工具原生的 401/403 响应(以及响应体)。

NOTE

当匹配到的 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/https URL。

示例:

spec:
  api:
    openapi:
      openapi: "3.0.1"
      paths:
        /repos/{owner}/{repo}/pulls:
          get:
            x-provider-type: proxy
            x-openapi-address: api
        /search/code:
          get:
            x-provider-type: proxy
            x-openapi-address: https://api.github.com

在此示例中:

  • /repos/{owner}/{repo}/pulls 使用名为 api 的 connector extension。
  • /search/code 使用直接 URL https://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,则请求如下:

K8S_TOKEN=xxxx

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

查询参数

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

分页

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

参数名称类型是否必填描述
pageintfalse页码
itemsPerPageintfalse每页条目数

响应格式

当返回列表时,响应结构如下:

字段名称类型是否必填描述
listMetaListMetatrue列表元数据
listMeta.totalItemsinttrue请求资源总数,客户端可用于分析分页信息
items[]true列表中的数据项;数据结构由 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:  # Reference to the custom API service
      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:  # Custom API defined in the connectors-gitlab-api service
          get:
            x-provider-type: api  # Indicates this API is a custom API
            summary: Request custom API
            responses:
              "200":
                description: Custom API response

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

有关 spec.api.openapi 的配置详情,请参阅 ConnectorClass OpenAPI 描述。如需更多使用示例,请参阅 在 Dynamic Forms 中使用 Connectors API。

ConnectorClass 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 系统的功能开关信息

    响应体示例:

    {
       "enable-connector-apis-permissions": "false",
       "enable-connector-apis-write-passthrough": "false",
       "enable-connector-proxy-permissions": "false",
       "enable-connectors-approval": "false",
       "enable-multi-connector": "false"
    }

    权限要求:需要具备访问 ConnectorClass 的权限。

    有关各功能开关的含义及其配置方式,请参阅 Feature Flags。

后续步骤