连接器 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}

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 使用的额外 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,则请求如下:

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。

写方法(透传)

默认情况下,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/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 操作声明了 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/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 扩展。
  • /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 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 信息

    响应体示例:

    {
       "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 flag 的含义及其配置方式,请参阅 Feature Flags。

下一步