Alauda DevOps Connectors Docs
简体中文

ConnectorClass API 扩展

目录

Overview

扩展 ConnectorClass API 本质上是创建一个 Restful API Server。在扩展 ConnectorClass 的 API 能力时，需要包含两部分信息：

  1. 在 ConnectorClass 的 spec.api 字段中指定 API 地址信息，使系统能够知道该 ConnectorClass 当前的 API 地址。详见“API 地址规范”。
  2. 实现 ConnectorClass 的 Restful API Server。详见“API 定义规范”。

API 地址规范

API 地址信息必须在 ConnectorClass 的 spec.api 字段中指定。

ConnectorClass API 服务是否部署在当前集群内没有限制，只要 Connectors 系统能够访问该服务地址即可。

字段配置可参考 connectorclass 中 connectorclass api 的描述。

API 定义规范

API 地址

当 Connectors 系统接收到客户端请求时，会将请求转发到该 Connector 所属 ConnectorClass 的 API 地址。 API 地址格式为 {connectorclass.status.api.address.url}/{resource-name}

认证信息

转发 API 请求时，Connectors 系统会通过 Http Header 向 ConnectorClass API 服务传递认证信息。 认证信息包括：

  • 工具地址信息：通过 Http Header X-Plugin-Meta 传递。
  • 认证类型：通过 Http Header X-Plugin-Auth 传递。
  • 认证数据：通过 Http Header X-Plugin-Secret 传递。

X-Plugin-Meta

该值是一个 Base64 编码的字符串，内容为 {"baseURL":"Connector Tool Address"}，例如：

{"baseURL":"http://github.com"} 编码后为 eyJiYXNlVVJMIjoiaHR0cDovL2dpdGh1Yi5jb20ifQ==

解码时，从 Header 中获取的 Base64 值解码为 JSON 字符串 {"baseURL":""}，其中 baseURL 的值即为工具的访问地址。

X-Plugin-Auth

该值是一个 Base64 编码的 K8S Secret Type 字符串。

例如，kubernetes.io/basic-auth 编码后为 a3ViZXJuZXRlcy5pby9iYXNpYy1hdXRo

解码时，从 Header 中获取的 Base64 值解码后即为 Secret Type。

X-Plugin-Secret

该值是一个 Base64 编码的 JSON 字符串，表示 K8S Secret Data。

例如，{"username":"YWRtaW4=","password":"c2VjcmV0"} 编码后为 eyJ1c2VybmFtZSI6IllXUnRhVzQ9IiwicGFzc3dvcmQiOiJjMlZqY21WMCJ9

解码时，从 Header 中获取的 Base64 值解码为 JSON 字符串 {"username":"YWRtaW4=","password":"c2VjcmV0"}。访问某个键的值时，需要对该值再次进行 base64 解码以获取原始值。

请求示例

GET /api/gitrefs?repositoryUrl=https%3A%2F%2Fgithub.com%2FAlaudaDevops%2Fconnectors.git HTTP/1.1
Host: 192.168.162.100:8080
X-Plugin-Meta: eyJiYXNlVVJMIjoiaHR0cHM6Ly9naXRodWIuY29tIn0=
X-Plugin-Auth: a3ViZXJuZXRlcy5pby9iYXNpYy1hdXRo
X-Plugin-Secret: eyJwYXNzd29yZCI6ImNHRnpjekV5TXc9PSIsInVzZXJuYW1lIjoiWVdSdGFXND0ifQ==

分页信息

通过 Query 参数传递：

参数名类型必填说明
pageint否页码
itemsPerPageint否每页条目数

响应

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

字段名类型必填说明
listMetaListMeta是列表的元数据
listMeta.totalItemsint是请求资源的总数，供客户端进行分页分析
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 保持一致。

资源命名

开发者可自行定义，建议包括：

  • 名称使用小写复数形式
  • 名称应在当前 ConnectorClass 的命名空间内唯一，并符合现有行业命名规范