Alauda DevOps Connectors Docs

Connector API

TOC

Overview

After integrating tools within the cluster, a RESTful API can be provided for the current Connector to conveniently acquire resources from the tool. These APIs are uniformly exposed through the Connector API, allowing users to obtain resources from the tool pointed to by the current Connector.

The Connectors system supports two ways to access tool resources through the API:

  • Original Tool API: Access the tool's original API through the Proxy Service
  • Custom API: Use a custom API provided for the ConnectorClass

When using the Connectors API, clients do not need to manage the tool's original authentication credentials. They only need to have permissions to access the Connector. The permissions for API requests to the tool are determined by the permissions of the credentials (Secret) configured in the Connector.

Connector API Address and Authentication

API Address

The Connector API address consists of three parts:

  • Platform API or cluster ingress access entry point
  • Connector API relative path
  • Requested tool's original API path or custom API path

After creating a Connector in the cluster, the Connector automatically records the current Connector's API path in <connector>.status.api.path. Note that this path is a relative path to the cluster access entry point.

The final Connector API address is: {platform_api_address}/{<connector>.status.api.path}/{api-path}

INFO

In Alauda Container Platform, the API access entry point is typically {platform_address}/clusters-rewrite/{cluster_name}.

Authentication and Authorization

Authentication complies with Kubernetes authentication standards and is completed through Kubernetes' authentication and authorization mechanisms. The requesting user must have read permissions for the corresponding Connector. Currently, only Bearer Token authentication is supported.

When making the final request to the tool, the Secret information specified by the Connector will be used for authentication.

For more information about Kubernetes API authentication, refer to the Kubernetes Authentication documentation.

Accessing Original Tool API

When your ConnectorClass provides Proxy Service capabilities, you can directly access the tool's original API through the Connector API.

For example, if the tool's original API address is /api/v4/projects, you can access it through the Connector API. Assuming you have a Connector named gitlab-connector in the default namespace, and the Connector's API path is /connectors/v1alpha1/default/gitlab-connector/path, the request would be:

K8S_TOKEN=xxxx

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

The Proxy Service capabilities can be configured through the ConnectorClass specification. For configuration details, refer to ConnectorClass Proxy. For a deeper understanding of the Connectors Proxy concept, refer to Connectors Proxy.

Custom API

When the tool's original API cannot meet your requirements or the ConnectorClass does not provide Proxy Service capabilities, you can provide a custom API service for the current ConnectorClass to meet your needs.

The custom API service can be configured through the spec.api field of the ConnectorClass, allowing the Connectors system to discover and use it. For configuration details, refer to ConnectorClass API.

Additionally, to enable the system to identify that the API is a custom API, you need to configure the OpenAPI description through the spec.api.openapi field.

API Definition

API Path

The API path provided by the custom API can be freely defined in the extended API service. The recommended format is /<connectorclass-name>/xxx.

Combined with the API address and authentication described above, here is a request example. Assuming you have a Connector named git-connector in the default namespace, and the custom API path is /git/gitrefs, the request would be:

K8S_TOKEN=xxxx

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

Query Parameters

Query parameters are determined by the specific ConnectorClass API Specification.

Pagination

Pagination information is indicated by query parameters:

Parameter NameTypeRequiredDescription
pageintfalsePage number
itemsPerPageintfalseNumber of items per page

Response Format

When returning a list, the response structure is as follows:

Field NameTypeRequiredDescription
listMetaListMetatrueMetadata of the list
listMeta.totalItemsinttrueTotal number of requested resources, usable by the client to analyze pagination information
items[]trueData items in the list; the data structure is determined by the ConnectorClass API
{
    "listMeta":{
        "totalItems":0
    },
    "items": [
        {

        }
    ]
}

When the response is not 200, the returned data structure should conform to the k8s status.

For example:

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

Field definitions and enumeration values are consistent with k8s status.

OpenAPI Description

In addition to providing a custom API service, you need to configure the OpenAPI description information in the spec.api.openapi field of the ConnectorClass to enable the system to identify that the API is a custom API.

Example:

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

The system will automatically forward the custom API to the ConnectorClass API Address based on the spec.api.openapi description.

For configuration details about spec.api.openapi, refer to ConnectorClass OpenAPI Description. For more usage examples, refer to Using Connectors API in Dynamic Forms.

ConnectorClass API Extension Specification

Developers can extend the API capabilities for ConnectorClass to provide users with richer resource retrieval capabilities.

Refer to the ConnectorClass API Extension Specification.

Using Connectors API in Dynamic Forms

The Connector API can be provided to UI clients, especially for dynamic form scenarios where UI clients can flexibly configure the API requests to be called.

To enable this, you need to configure the OpenAPI description information through the spec.api.openapi field of the ConnectorClass, which works together with the dynamic form DSL to implement frontend dynamic form rendering.

The dynamic form description is typically provided in the Resource Interface. For more details, refer to Resource Interface.