ResourceInterface

Обзор

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

Пример ниже определяет интерфейс 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 pipeline пользователи традиционно сталкиваются с несколькими проблемами:

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

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

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

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

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

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

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

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

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

ResourceInterface — стандартный ресурс Kubernetes, который можно аннотировать человекочитаемой информацией с помощью 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). Ресурсы в одной категории должны предоставлять одинаковые стандартные атрибуты и рабочие области для обеспечения совместимости.

Параметры

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

Параметры задаются в 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)"

Атрибуты

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

Атрибуты задаются в 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)

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

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

name: имя рабочей области
workspaceMapping.name: имя рабочей области по умолчанию при добавлении в pipeline
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-компонентов для интеграции pipeline. С помощью динамических форм пользователи могут просматривать и выбирать ресурсы, такие как 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 gitrefs

Следующая конфигурация 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: docker-config
    workspaceMapping:
      name: docker-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

Примеры

Что дальше

Ссылки