ResourceInterface

Обзор

ResourceInterface — это ресурс на уровне кластера, который определяет стандартизированные абстракции для внешних ресурсов (таких как Git-репозитории, OCI-артефакты, Maven-артефакты) и способ их интеграции в конвейеры. Он служит мостом между коннекторами и оркестрацией конвейеров, обеспечивая бесшовную интеграцию ресурсов с минимальной ручной настройкой.

В следующем примере определяется интерфейс GitCodeRepository, описывающий доступ к Git-репозиторию:

apiVersion: connectors.alauda.io/v1alpha1
kind: ResourceInterface
metadata:
  name: gitcoderepository
  labels:
    resourceinterface.connectors.cpaas.io/category: "GitCodeRepository"
spec:
  params:
  - name: repository
    type: string
    description: "Repository name"
  - name: revision
    type: string
    default: "refs/heads/main"
    description: "Git revision (branch, tag, or commit)"
  attributes:
  - name: url
    type: string
    expression: "{connector.spec.address + '/' + params.repository}"
    parameterize:
      name: git-url
    dependsOn:
    - params.repository
    - connector
  workspaces:
  - name: git-basic-auth
    workspaceMapping:
      name: git-basic-auth
    value:
      csi:
        driver: connectors-csi
        readOnly: true
        volumeAttributes:
          connector.name: "{connector.metadata.name}"
          connector.namespace: "{connector.metadata.namespace}"
          configuration.names: "gitconfig"
          token.expiration: 30m

ResourceInterface определяет следующие ключевые аспекты для интеграции ресурсов:

Входные параметры, необходимые для настройки ресурса
Выходные атрибуты, вычисляемые на основе параметров и информации о коннекторе
Определения рабочих областей (workspaces) для томов и учетных данных

В этом документе представлены определение структуры данных ResourceInterface и примеры, которые помогут понять, как настраивать ResourceInterface.

Вам не обязательно понимать детали ResourceInterface, если вы не планируете его настраивать.

Решаемые задачи

При построении CI/CD конвейеров пользователи традиционно сталкиваются с несколькими проблемами:

Ручной ввод ресурсов: Пользователи не могут легко просматривать и добавлять внешние ресурсы, такие как Git-репозитории, OCI-репозитории и другие внешние сервисы. Им приходится вручную вводить URL и настраивать рабочие области, что подвержено ошибкам и занимает много времени.

Повторяющаяся настройка исполнения: Каждый раз при запуске конвейера пользователи должны вручную вводить детали версии, такие как Git revision и целевой тег OCI, а также повторно настраивать рабочие области.

Разделение атрибутов: Атрибуты одного и того же удаленного ресурса часто разбиты на разные параметры. Например, задача git-clone требует отдельные параметры url и revision, а также настройки рабочих областей для учетных данных и исходного кода.

Сложный выбор рабочих областей: Процесс выбора рабочих областей в конвейере отображает все доступные варианты, но предоставляет мало рекомендаций о том, какой тип коннектора подходит для каждой рабочей области.

ResourceInterface решает эти проблемы, предоставляя стандартизированный способ описания и интеграции внешних ресурсов в конвейерные рабочие процессы, позволяя пользователям просматривать и выбирать ресурсы через UI, автоматически генерируя правильную конфигурацию и учетные данные.

Структура данных

ResourceInterface — это ресурс Kubernetes на уровне кластера

Kind: ResourceInterface
API Version: connectors.alauda.io/v1alpha1

Читаемая информация

ResourceInterface — стандартный ресурс k8s, который можно аннотировать читаемой информацией с помощью annotations.

Ключ	Позиция	Описание
`cpaas.io/display-name`	annotations	Отображаемое имя ResourceInterface, необязательно.
`cpaas.io/description`	annotations	Описание ResourceInterface, необязательно.

apiVersion: connectors.alauda.io/v1alpha1
kind: ResourceInterface
metadata:
  name: gitcoderepository
  annotations:
    cpaas.io/display-name: "Git Code Repository"
    cpaas.io/description: "GitCodeRepository is a resource interface for Git code repository"

Также можно использовать аннотацию style.tekton.dev/descriptors для описания параметров динамической формы.

metadata:
  annotations:
    style.tekton.dev/descriptors: |-
      - path: params.revision
        x-descriptors:
          - urn:alm:descriptor:widgets:select
          - urn:alm:descriptor:expression:props.options:schema:openapi:context.connectorClass.spec.api.openapi:listGitRefs

Подробнее см. в разделе dynamic-form.

Категории ресурсов

ResourceInterface организует ресурсы в категории, которые определяют общие контракты и поведение. Категории отмечаются с помощью метки resourceinterface.connectors.cpaas.io/category.

metadata:
  labels:
    resourceinterface.connectors.cpaas.io/category: "GitCodeRepository"

Несколько ResourceInterface могут принадлежать одной категории (например, gitcoderepository и githubcoderepository обе относятся к категории GitCodeRepository). Ресурсы в одной категории должны предоставлять одинаковые стандартные атрибуты и рабочие области для обеспечения совместимости.

Параметры

Параметры определяют входные данные, необходимые для настройки ресурса при интеграции в конвейер. Эти параметры влияют на вычисление выходных атрибутов.

Параметры задаются в spec.params и соответствуют типам параметров Tekton:

name: имя параметра
type: поддерживает string, array, object (соответствует типам Tekton ParamSpec)
default: значение параметра по умолчанию (необязательно)
description: описание параметра для отображения в UI (необязательно)

например:

kind: ResourceInterface
metadata:
  name: gitcoderepository
  labels:
    resourceinterface.connectors.cpaas.io/category: "GitCodeRepository"
spec:
  params:
  - name: repository
    type: string
    description: "Repository name"
  - name: revision
    type: string
    default: "refs/heads/main"
    description: "Git revision (branch, tag, or commit)"

Атрибуты

Атрибуты определяют выходные значения, вычисляемые на основе входных параметров и информации о коннекторе. Они могут использоваться задачами конвейера в качестве параметров и могут быть подняты до параметров уровня конвейера.

Атрибуты задаются в spec.attributes:

name: имя атрибута
type: тип значения — поддерживает string, array
expression: JavaScript-выражение для вычисления значения атрибута
parameterize: конфигурация параметризации
- name: имя параметра по умолчанию при параметризации
- disable: отключить параметризацию
dependsOn: зависимости от параметров или коннектора

например:

spec:
  attributes:
  - name: url
    type: string
    expression: "{connector.spec.address + '/' + params.repository}"
    parameterize:
      name: git-url
    dependsOn:
    - params.repository
    - connector
  - name: artifact-versions
    type: array
    expression: "{params.tags.map(tag => connector.spec.registry + '/' + params.repository + ':' + tag)}"
    dependsOn:
    - params.repository
    - params.tags
    - connector

Синтаксис выражений

Выражения используют синтаксис JavaScript и поддерживают:

Конкатенацию строк: params.organization + '/' + params.repository
Доступ к свойствам объектов: connector.metadata.name
Операции с массивами: params.tags.map(tag => connector.spec.address + ':' + tag)
Встроенные функции:
- url(connector.spec.address).host: получить хост из адреса

и другие синтаксисы JavaScript.

Доступный контекст:

connector: текущая информация о коннекторе, структура коннектора описана в Concept of Connector
params: текущие значения параметров

структура контекста:

{
  "params": {
    "param-name1": "param-value",
    "param-name2": "param-value"
  },
  "connector": {}
}

Безопасность: Фронтенд выполняет JavaScript-код в песочнице, разрешая только безопасные, изолированные функции.

Примеры:

{connector.spec.address + '/' + params.repository}: получить адрес репозитория
{url(connector.spec.address).host + '/' + params.repository + ':' + params.tag}: получить адрес артефакта
{params.tags.map(tag => url(connector.spec.address).host + '/' + params.repository + ':' + tag)}: получить массив адресов артефактов, перебирая теги

Зависимости

Зависимости указывают, от каких параметров или информации о коннекторе зависит вычисление атрибута:

params.<param-name>: зависит от конкретного параметра
connector: зависит от выбора коннектора

Рабочие области (Workspaces)

Рабочие области определяют тома и учетные данные, предоставляемые интерфейсом ресурса. Они позволяют автоматически выделять необходимые ресурсы для задач конвейера.

Рабочие области задаются в spec.workspaces:

name: имя рабочей области
workspaceMapping.name: имя рабочей области по умолчанию при добавлении в рабочие области конвейера
value: значение рабочей области по умолчанию (соответствует формату Tekton WorkspaceBinding), совместимо с типами Tekton WorkspaceBinding

например:

spec:
  workspaces:
  - name: git-source
    workspaceMapping:
      name: git-source
    value:
      volumeClaimTemplate:
        spec:
          accessModes: [ReadWriteMany]
          resources:
            requests:
              storage: 1Gi
  - name: git-basic-auth
    workspaceMapping:
      name: git-basic-auth
    value:
      csi:
        driver: connectors-csi
        readOnly: true
        volumeAttributes:
          connector.name: "{connector.metadata.name}"
          connector.namespace: "{connector.metadata.namespace}"
          configuration.names: "gitconfig"
          token.expiration: 30m

Значения рабочих областей поддерживают выражения для динамического обращения к параметрам и значениям коннектора с использованием того же синтаксиса, что и атрибуты.

ConnectorClass

ConnectorClass отмечает поддерживаемые ResourceInterface с помощью меток resourceinterface.connectors.cpaas.io/<resource-interface-name>: "true", например:

metadata:
  labels:
    resourceinterface.connectors.cpaas.io/gitcoderepository: "true"
    resourceinterface.connectors.cpaas.io/githubcoderepository: "true"

Это позволяет системе сопоставлять совместимые коннекторы с ResourceInterface и предоставлять соответствующие формы параметров на основе определений ResourceInterface.

Подробнее о ConnectorClass см. в Concept of ConnectorClass

Динамическая форма

Динамические формы предоставляют декларативный способ настройки интерактивных UI-компонентов для интеграции в конвейер. С помощью динамических форм пользователи могут просматривать и выбирать ресурсы, такие как Git-репозитории и ревизии, непосредственно через коннектор.

Обзор

Используйте аннотацию style.tekton.dev/descriptors для определения поведения динамической формы для параметров. Пример:

metadata:
  annotations:
    style.tekton.dev/descriptors: >-
      - path: params.repository
        x-descriptors:
          - urn:alm:descriptor:com.tectonic.ui:select:repository
          - urn:alm:descriptor:expression:props.options:api:/clusters-rewrite/${context.cluster}${context.connector.status.api.path}/api/v4/projects?simple=true
          - urn:alm:descriptor:expression:props.options:label:path:path_with_namespace
          - urn:alm:descriptor:expression:props.options:value:path:path_with_namespace
          - urn:alm:descriptor:label:en:Repository
          - urn:alm:descriptor:label:zh:Repository
          - urn:alm:descriptor:description:zh:Repository path including group name or username, e.g. mygroup/my-app.
          - urn:alm:descriptor:description:en:Repository path including group name or username, e.g. mygroup/my-app.

Синтаксис соответствует спецификации Pipeline Dynamic Forms. Рекомендуется ознакомиться с этой документацией перед использованием.

Помимо стандартных возможностей, динамические формы в ResourceInterface поддерживают:

Расширенные переменные контекста для доступа к данным коннектора и ResourceInterface
Ссылки на схемы отображения OpenAPI в ConnectorClass для централизованной настройки API и использования этих определений в динамических формах

Расширенные переменные контекста

В динамических формах ResourceInterface доступны следующие переменные контекста:

Переменная	Описание
`context.connector`	Объект Connector. Доступ к любому полю, например, `context.connector.status.api.path`
`context.connectorClass`	Объект ConnectorClass. Доступ к любому полю, например, `context.connectorClass.spec.api.openapi`
`context.params`	Значения параметров в UI форме Pipeline Integration, например, `context.params.repository`
`context.resourceInterface`	Объект ResourceInterface. Доступ к любым необходимым полям

Подходы к настройке динамической формы

Существует два подхода к настройке динамических форм в ResourceInterface:

Прямая конфигурация API: вызов API коннектора напрямую с помощью выражений дескрипторов. Этот подход прост и понятен. Система Connectors предоставляет Connector API для получения списков репозиториев, git-референсов и др.
Ссылка на схему отображения OpenAPI в ConnectorClass: определение вызовов API и отображения в ConnectorClass с помощью spec.api.openapi. Этот подход централизует определения API и конфигурацию отображения, избегая дублирования в нескольких ResourceInterface. При использовании динамической формы можно напрямую ссылаться на определение API в ConnectorClass.

Можно использовать любой из подходов отдельно или комбинировать их.

Прямая конфигурация API

Пример: Получение списка репозиториев GitLab

Коннекторы GitLab предоставляют нативный API GitLab, который можно использовать для заполнения селектора репозиториев:

kind: ResourceInterface
metadata:
  name: gitlabcoderepository
  annotations:
    style.tekton.dev/descriptors: >-
      - path: params.repository
        x-descriptors:
          - urn:alm:descriptor:com.tectonic.ui:select:repository
          - urn:alm:descriptor:expression:props.options:api:/clusters-rewrite/${context.cluster}${context.connector.status.api.path}/api/v4/projects?simple=true
          - urn:alm:descriptor:expression:props.options:label:path:path_with_namespace
          - urn:alm:descriptor:expression:props.options:value:path:path_with_namespace
          - urn:alm:descriptor:label:en:Repository
          - urn:alm:descriptor:label:zh:Repository
          - urn:alm:descriptor:description:zh:Repository path including group name or username, e.g. mygroup/my-app.
          - urn:alm:descriptor:description:en:Repository path including group name or username, e.g. mygroup/my-app.

Пример: Получение списка Git-референсов

Git-коннектор предоставляет endpoint gitrefs для получения списка веток и тегов:

kind: ResourceInterface
metadata:
  name: gitcoderepository
  annotations:
    style.tekton.dev/descriptors: >-
      - path: params.revision
        x-descriptors:
          - urn:alm:descriptor:com.tectonic.ui:select:revision
          - urn:alm:descriptor:expression:props.options:api:/clusters-rewrite/${context.cluster}${context.connector.status.api.path}/git/gitrefs?repositoryUrl=${context.connector.spec.address + "/" + context.params.repository + ".git"}&search=${current.search}
          - urn:alm:descriptor:expression:props.options:path:items
          - urn:alm:descriptor:expression:props.options:label:path:name
          - urn:alm:descriptor:expression:props.options:value:path:name
          - urn:alm:descriptor:label:en:Revision
          - urn:alm:descriptor:label:zh:Revision
          - urn:alm:descriptor:description:zh:Git revision reference, e.g. refs/heads/main.
          - urn:alm:descriptor:description:en:Git revision reference (e.g., refs/heads/main for branches)

Ссылка на схему отображения OpenAPI

Для централизованного определения API и конфигурации отображения их задают в ConnectorClass с помощью spec.api.openapi. Динамические формы могут ссылаться на эти определения напрямую, что устраняет дублирование конфигураций в ResourceInterface.

Требования

Определить спецификацию OpenAPI в ConnectorClass. Подробнее в ConnectorClass OpenAPI Description.
Добавить расширение x-display-schema для описания интеграции API с динамическими формами.

Структура схемы отображения

Расширение x-display-schema содержит:

parameters[]: определяет, как заполнять параметры API во время выполнения.
- name: имя параметра (должно совпадать с именем параметра API)
- value: выражение для значения параметра. Синтаксис соответствует Pipeline Dynamic Forms.
descriptors: определяет, как данные ответа API отображаются в опции формы. Синтаксис соответствует Pipeline Dynamic Forms.

Пример: API Git References

Следующая конфигурация ConnectorClass определяет API GET /git/gitrefs с схемой отображения:

Параметр repositoryUrl задается как ${context.connector.spec.address + "/" + context.params.repository + ".git"} и передается как query-параметр
Параметр search задается как ${current.search} для фильтрации результатов
Массив items ответа сопоставляется с опциями выбора, используя name для метки и значения

пример:

kind: ConnectorClass
spec:
  api:
    openapi:
      openapi: 3.0.3
      info:
        title: Git API
        version: v1alpha1
      paths:
        /git/gitrefs:
          get:
            x-provider-type: api
            x-display-schema:
              parameters:
              - name: repositoryUrl
                value: ${context.connector.spec.address + "/" + context.params.repository + ".git"}
              - name: search
                value: ${current.search}
              descriptors:
              - urn:alm:descriptor:expression:props.options:path:items
              - urn:alm:descriptor:expression:props.options:label:path:name
              - urn:alm:descriptor:expression:props.options:value:path:name
            operationId: listGitRefs
            parameters:
            - name: repositoryUrl
              in: query
              description: "Cloneable URL of the repository (e.g., https://github.com/mygroup/my-app.git)"
              required: true
              schema:
                type: string
            - name: search
              in: query
              description: "Return list of git references containing the search string"
              required: false
              schema:
                type: string
            responses:
              '200':
                description: "All git references for a repository"
                content:
                  application/json: {}

Ссылка на OpenAPI в ResourceInterface

После определения API в ConnectorClass, ссылаться на него в ResourceInterface можно следующим образом:

urn:alm:descriptor:widgets:select для указания типа виджета
schema:openapi:context.connectorClass.spec.api.openapi:<operationId> для ссылки на определение API в ConnectorClass

например:

kind: ResourceInterface
metadata:
  name: gitcoderepository
  annotations:
    style.tekton.dev/descriptors: >-
      - path: params.revision
        x-descriptors:
          - urn:alm:descriptor:widgets:select
          - urn:alm:descriptor:expression:props.options:schema:openapi:context.connectorClass.spec.api.openapi:listGitRefs
          - urn:alm:descriptor:label:en:Revision
          - urn:alm:descriptor:label:zh:Revision
          - urn:alm:descriptor:description:zh:Git revision reference, e.g. refs/heads/main.
          - urn:alm:descriptor:description:en:Git revision reference (e.g., refs/heads/main for branches)

С такой конфигурацией поле revision в Pipeline Integration отображается как выпадающий список, который получает опции из API listGitRefs.

Примеры

ResourceInterface GitCodeRepository

apiVersion: connectors.alauda.io/v1alpha1
kind: ResourceInterface
metadata:
  name: gitcoderepository
  labels:
    resourceinterface.connectors.cpaas.io/category: "GitCodeRepository"
spec:
  params:
  - name: repository
    type: string
    description: "Repository name"
  - name: revision
    type: string
    default: "refs/heads/main"
    description: "Git revision"
  attributes:
  - name: url
    type: string
    expression: "{connector.spec.address + '/' + params.repository}"
    parameterize:
      name: git-url
    dependsOn:
    - params.repository
    - connector
  - name: revision
    type: string
    expression: "{params.revision}"
    parameterize:
      name: git-revision
    dependsOn:
    - params.revision
  workspaces:
  - name: git-source
    workspaceMapping:
      name: git-source
    value:
      volumeClaimTemplate:
        spec:
          accessModes: [ReadWriteMany]
          resources:
            requests:
              storage: 200Mi
  - name: git-basic-auth
    workspaceMapping:
      name: git-basic-auth
    value:
      csi:
        driver: connectors-csi
        readOnly: true
        volumeAttributes:
          connector.name: "{connector.metadata.name}"
          connector.namespace: "{connector.metadata.namespace}"
          configuration.names: "gitconfig"
          token.expiration: 30m

ResourceInterface OCIArtifact

apiVersion: connectors.alauda.io/v1alpha1
kind: ResourceInterface
metadata:
  name: ociartifact
  labels:
    resourceinterface.connectors.cpaas.io/category: "OCIArtifact"
spec:
  params:
  - name: repository
    type: string
    description: "Repository name"
  - name: tags
    type: array
    description: "Image tags"
  attributes:
  - name: repository-address
    type: string
    expression: "{connector.spec.registry + '/' + params.repository}"
    dependsOn:
    - params.repository
    - connector
  - name: artifact-versions
    type: array
    expression: "{params.tags.map(tag => connector.spec.registry + '/' + params.repository + ':' + tag)}"
    dependsOn:
    - params.repository
    - params.tags
    - connector
  workspaces:
  - name: registry-config
    workspaceMapping:
      name: registry-config
    value:
      csi:
        driver: connectors-csi
        readOnly: true
        volumeAttributes:
          connector.name: "{connector.metadata.name}"
          connector.namespace: "{connector.metadata.namespace}"
          configuration.names: "config"
          token.expiration: 60m

Что дальше

Изучите Pipeline Integration, если хотите интегрировать Connector в свой кастомный Pipeline или Task.

#ResourceInterface

#Содержание

#Обзор

#Решаемые задачи

#Структура данных

#Читаемая информация

#Категории ресурсов

#Параметры

#Атрибуты

#Синтаксис выражений

#Зависимости

#Рабочие области (Workspaces)

#ConnectorClass

#Динамическая форма

#Обзор

#Расширенные переменные контекста

#Подходы к настройке динамической формы

#Прямая конфигурация API

#Ссылка на схему отображения OpenAPI

#Примеры

#Что дальше

#Ссылки

ResourceInterface

Содержание

Обзор

Решаемые задачи

Структура данных

Читаемая информация

Категории ресурсов

Параметры

Атрибуты

Синтаксис выражений

Зависимости

Рабочие области (Workspaces)

ConnectorClass

Динамическая форма

Обзор

Расширенные переменные контекста

Подходы к настройке динамической формы

Прямая конфигурация API

Ссылка на схему отображения OpenAPI

Примеры

Что дальше

Ссылки