#Connector API

#Обзор

После интеграции инструментов в кластер для текущего Connector может быть предоставлен RESTful API, чтобы удобно получать ресурсы из инструмента. Эти API единообразно предоставляются через Connector API, позволяя пользователям получать ресурсы из инструмента, на который указывает текущий Connector.

Система Connectors поддерживает два способа доступа к ресурсам инструмента через API:

• Original Tool API: доступ к исходному API инструмента через Proxy Service
• Custom API: использование пользовательского API, предоставляемого для ConnectorClass

При использовании Connectors API клиентам не нужно управлять исходными учетными данными аутентификации инструмента. Им достаточно иметь права на доступ к Connector. Права для API-запросов к инструменту определяются правами учетных данных (Secret), настроенных в Connector.

#Адрес Connector API и аутентификация

#Адрес API

Адрес Connector API состоит из трех частей:

• Точка входа доступа Platform API или ingress кластера
• Относительный путь Connector API
• Исходный путь API запрашиваемого инструмента или путь пользовательского API

После создания Connector в кластере Connector автоматически записывает путь API текущего Connector в <connector>.status.api.path. Обратите внимание, что этот путь является относительным по отношению к точке входа доступа к кластеру.

Итоговый адрес Connector API: {platform_api_address}/{<connector>.status.api.path}/{api-path}

#Аутентификация и авторизация

Аутентификация соответствует стандартам аутентификации Kubernetes и выполняется через механизмы аутентификации и авторизации Kubernetes. Пользователь, выполняющий запрос, должен иметь права на чтение соответствующего Connector. В настоящее время поддерживается только аутентификация Bearer Token.

При выполнении итогового запроса к инструменту для аутентификации будут использоваться сведения Secret, указанные в Connector.

По умолчанию, когда enable-connector-apis-permissions отключен, для вызова Connectors API достаточно прав на чтение Connector. Когда enable-connector-apis-permissions включен, система выполняет дополнительную проверку прав connectors/apis для целевого Connector. Это дополнительное право отделяет обнаружение Connector от фактического использования API.

Для общей модели и значения connectors/apis см. Connectors Permission Model.

Дополнительные сведения об аутентификации Kubernetes API см. в Kubernetes Authentication documentation.

#Доступ к исходному API инструмента

Когда ваш ConnectorClass предоставляет возможности Proxy Service, вы можете напрямую обращаться к исходному API инструмента через Connector API.

Например, если исходный адрес API инструмента — /api/v4/projects, вы можете получить к нему доступ через Connector API. Предположим, что в пространстве имен default у вас есть Connector с именем gitlab-connector, а путь API Connector равен /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.

#Выбор backend-адреса с помощью x-openapi-address

Когда операция OpenAPI использует x-provider-type: proxy, вы можете при необходимости задать x-openapi-address, чтобы управлять тем, какой backend-адрес будет использовать запрос.

Поддерживаются следующие формы выбора:

• Пустое значение или значение не задано: используется Connector.spec.address.
• Имя расширения: разрешается по name из Connector.spec.addressExtensions.
• Прямой адрес: полный URL http/https.

Пример:

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 использует расширение Connector с именем api.
• /search/code использует прямой URL https://api.github.com.
• Если x-openapi-address не указан, запрос использует Connector.spec.address.

Если x-openapi-address ссылается на отсутствующее имя расширения или недопустимый прямой URL, запрос отклоняется.

#Пользовательский API

Когда исходный API инструмента не может удовлетворить ваши требования или ConnectorClass не предоставляет возможности Proxy Service, вы можете предоставить пользовательский API service для текущего ConnectorClass, чтобы реализовать необходимые функции.

Сервис пользовательского API можно настроить через поле spec.api в ConnectorClass, что позволяет системе Connectors обнаруживать и использовать его. Подробности настройки см. в ConnectorClass API.

Кроме того, чтобы система могла определить, что API является пользовательским API, необходимо настроить описание OpenAPI через поле spec.api.openapi.

#Определение API

#Путь API

Путь API, предоставляемый пользовательским API, может быть свободно определен в расширенном API service. Рекомендуемый формат: /<connectorclass-name>/xxx.

В сочетании с адресом API и аутентификацией, описанными выше, ниже приведен пример запроса. Предположим, что в пространстве имен default у вас есть Connector с именем git-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.

#Пагинация

Информация о пагинации задается параметрами запроса:

#Формат ответа

При возврате списка структура ответа выглядит следующим образом:

{
    "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 service, необходимо настроить информацию описания OpenAPI в поле spec.api.openapi ConnectorClass, чтобы система могла определить, что 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

Система автоматически перенаправит пользовательский API на ConnectorClass API Address на основе описания spec.api.openapi.

Для подробностей настройки spec.api.openapi см. ConnectorClass OpenAPI Description. Дополнительные примеры использования см. в Using Connectors API in Dynamic Forms.

#Спецификация расширения ConnectorClass API

Разработчики могут расширять возможности API для ConnectorClass, чтобы предоставлять пользователям более богатые возможности получения ресурсов.

См. ConnectorClass API Extension Specification.

#Использование Connectors API в динамических формах

Connector API может предоставляться UI clients, особенно в сценариях динамических форм, где UI clients могут гибко настраивать вызываемые API requests.

Чтобы включить это, необходимо настроить информацию описания OpenAPI через поле spec.api.openapi ConnectorClass, которое совместно с dynamic form DSL обеспечивает отрисовку динамических форм на frontend.

Описание dynamic form обычно предоставляется в Resource Interface. Дополнительные сведения см. в Resource Interface.

#Connectors Operator API

Connectors Operator API — это набор RESTful API, предоставляемых Connectors API, чтобы позволить пользователям получать информацию о Connectors.

Путь API: {platform_address}/clusters-rewrite/{cluster_name}/connectors-operator/{api-path}.

В настоящее время предоставляются следующие API:

• GET /connectors-operator/featureflags: возвращает информацию о feature flags системы Connectors в текущем кластере

  пример тела ответа:

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

  Требование к правам: требуется право на доступ к ConnectorClass.

  Значение каждого feature flag и способ их настройки см. в Feature Flags.

#Дальнейшие шаги

• Connectors Permission Model
• Connector Resource Levels and Permissions
• Connectors Proxy
• Feature Flags