#Pipeline Integration

#Overview

При построении CI/CD конвейеров с помощью Tekton разработчикам часто требуется интеграция с внешними ресурсами, такими как Git-репозитории, реестры контейнеров и репозитории артефактов. Традиционно это требует ручной настройки URL, учетных данных и параметров для каждого внешнего инструмента, что подвержено ошибкам и занимает много времени.

Интеграция Tekton Pipelines с Connectors решает эту проблему, предоставляя стандартизированный способ подключения внешних ресурсов к рабочим процессам конвейера. Эта интеграция обеспечивает:

• Удобный просмотр и выбор ресурсов: просмотр и добавление внешних ресурсов, таких как Git-репозитории, Git Revision, OCI-репозитории и другие ресурсы через UI, вместо ручного ввода
• Единые атрибуты ресурсов: обработка разделённых атрибутов одного и того же удалённого ресурса как единого целого, исключая необходимость настраивать отдельные параметры url и revision, а также конфигурации workspace
• Руководство по настройке workspace: быстрая настройка workspace с соответствующими коннекторами и чёткими рекомендациями, какой тип коннектора подходит для каждого workspace
• Сохранение гибкости: сохранение текущего опыта оркестрации и выполнения конвейера при добавлении мощных возможностей коннекторов

#Что такое Pipeline Integration

Pipeline Integration — это механизм, который связывает внешние ресурсы (через Connectors и ResourceInterfaces) с задачами Tekton Tasks и конвейерами Pipelines. Он определяет:

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

PipelineIntegration не является реальным ресурсом Kubernetes, а представляет собой метаданные интеграции, хранящиеся в аннотациях Tekton Pipeline или Task с использованием ключа integrations.tekton.dev/integrations.

В этом документе описываются концепции и ключевые поля Pipeline Integration. Если вы хотите интегрировать коннекторы в свой кастомный pipeline или task, вам следует ознакомиться с деталями, изложенными в этом документе.

Встроенные компоненты Pipeline и Task уже поддерживают Pipeline Integration, поэтому вы можете использовать их напрямую без дополнительной настройки.

#Ключевые поля Pipeline Integration

Pipeline Integration содержит следующие ключевые поля:

• Ссылка на ResourceInterface: указывает, какой ResourceInterface использовать (по категории или имени)
• Ссылка на Connector: идентифицирует, какой экземпляр Connector предоставляет ресурс
• Конфигурация параметров: входные параметры, требуемые ResourceInterface
• Отображение атрибутов: как атрибуты ресурса сопоставляются с параметрами pipeline/task
• Отображение workspace: как workspace ресурса сопоставляются с workspace конвейера

#Хранение в аннотациях

Метаданные интеграции хранятся с помощью аннотации integrations.tekton.dev/integrations в виде YAML-массива:

apiVersion: tekton.dev/v1
kind: Pipeline
metadata:
  annotations:
    integrations.tekton.dev/integrations: |
      - name: code-repo
        interface:
          category: "GitCodeRepository"
        connectorRef:
          name: github-connector
          namespace: default
          setAtRuntime: false
        params:
        - name: repository
          value: "myorg/myapp"
          setAtRuntime: false
        - name: revision
          setAtRuntime: true
        attributes:
        - name: url
          param: git-url
          refPath:
          - tasks.git-clone.params.url
        - name: revision
          param: git-revision
          refPath:
          - tasks.git-clone.params.revision
        workspaces:
        - name: git-source
          workspace: source-workspace
          refPath:
          - tasks.git-clone.workspaces.output

#Структура Pipeline Integration

#Name

Имя интеграции конвейера.

name: "code-repo"

#Ссылка на ResourceInterface

Указывает, какой ResourceInterface использовать. Поддерживаются ссылки как по категории, так и по имени:

Ссылка по категории (гибкая, работает с любым совместимым коннектором):

interface:
  apiVersion: "connectors.alauda.io/v1alpha1"
  category: "GitCodeRepository"

все имена категорий определены в метках ResourceInterface с именем resourceinterface.connectors.cpaas.io/category.

Ссылка по имени (конкретный интерфейс):

interface:
  name: "gitcoderepository"
  apiVersion: "connectors.alauda.io/v1alpha1"

Когда использовать каждый подход:

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

#Ссылка на Connector

Указывает, какой экземпляр Connector использовать для доступа к внешнему ресурсу:

connectorRef:
  name: "github-connector"        # Имя коннектора
  namespace: "default"            # Необязательно, по умолчанию совпадает с namespace конвейера
  setAtRuntime: true              # Можно ли выбрать коннектор во время выполнения

Варианты настройки:

• Фиксированный коннектор: укажите name и namespace, оставьте setAtRuntime как false или опустите
• Выбор во время выполнения: установите setAtRuntime: true, чтобы разрешить выбор коннектора при выполнении конвейера
• По умолчанию с возможностью переопределения: укажите name и установите setAtRuntime: true для значения по умолчанию с возможностью переопределения во время выполнения

#Параметры

Входные параметры, необходимые ResourceInterface. Эти параметры используются для вычисления атрибутов ресурса:

params:
- name: repository
  value: "myorg/myapp"           # Фиксированное значение
  setAtRuntime: false            # Нельзя изменить во время выполнения
- name: revision
  value: "main"                  # Значение по умолчанию
  setAtRuntime: true             # Можно изменить во время выполнения

Поведение параметров:

• Если setAtRuntime: true, параметр должен быть предоставлен при выполнении конвейера
• Если setAtRuntime: false или опущено, параметр использует фиксированное value
• Параметры без value, но с setAtRuntime: true требуют ввода пользователя во время выполнения

#Атрибуты

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

attributes:
- name: url
  param: git-url                 # Имя параметра конвейера (при параметризации)
  refPath:                       # Где используется этот атрибут
  - tasks.git-clone.params.url   # Параметр PipelineTask, который получает это значение
- name: revision
  value: "refs/heads/main"       # Статическое значение (без параметризации)
  refPath:
  - tasks.git-clone.params.revision

Настройка атрибутов:

• Имя атрибута должно совпадать с ResourceInterface.spec.attributes[].name
• Значение атрибута вычисляется с помощью выражения, определённого в ResourceInterface.spec.attributes[].expression
• Параметризованные атрибуты создают параметры конвейера (указываются в поле param)
• Статические атрибуты используют фиксированные значения (указываются в поле value)
• refPath определяет, где значение атрибута используется в задачах конвейера

#Workspaces

Отображение workspace между workspace ResourceInterface и workspace конвейера:

workspaces:
- name: git-source              # Имя workspace ResourceInterface
  workspace: source-workspace   # Имя workspace конвейера
  refPath:                      # Где используется этот workspace
  - tasks.git-clone.workspaces.output
- name: git-basic-auth
  workspace: git-credentials
  refPath:
  - tasks.git-clone.workspaces.basic-auth

Настройка workspace:

• Имя workspace должно совпадать с ResourceInterface.spec.workspaces[].name
• Workspace конвейера создаётся автоматически с именем, указанным в поле workspace, по умолчанию берётся из ResourceInterface.spec.workspaces[].workspaceMapping.name.
• refPath определяет, какой workspace PipelineTask использует этот workspace.

#Поддержка интеграции в Task

Задачи могут объявлять поддержку интеграции для автоматического отображения параметров и workspace:

apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: git-clone
  annotations:
    integrations.tekton.dev/integrations: |
      - name: code-repo
        interface:
          category: Git Code Repository
        attributes:
        - name: url
          param: git-url
        - name: revision
          param: git-revision
        workspaces:
        - name: source
          workspace: output
        - name: credentials
          workspace: basic-auth
spec:
  params:
  - name: git-url
    type: string
  - name: revision
    type: string
  workspaces:
  - name: output
  - name: basic-auth

#Примеры

Revision задаётся во время выполнения

• коннектор и репозиторий — фиксированные значения, revision задаётся во время выполнения.
• используется фиксированное значение https://github.com/myorg/myapp.git в параметре url задачи git-clone.
• используется параметр времени выполнения $(params.revision) в параметре revision задачи git-clone.
• используется workspace source-workspace в workspace source задачи git-clone.

Например:

- name: app-source
  interface:
    category: "GitCodeRepository"
  connectorRef:
    name: github-connector
    namespace: default
  params:
  - name: repository
    value: "myorg/myapp"
  - name: revision
    setAtRuntime: true
  attributes:
  - name: url
    value: "https://github.com/myorg/myapp.git"
    refPath:
    - tasks.git-clone.params.url
  - name: revision
    value: "$(params.revision)"
    refPath:
    - tasks.git-clone.params.revision
  workspaces:
  - name: git-source
    workspace: source-workspace
    refPath:
    - tasks.git-clone.workspaces.output

Коннектор, репозиторий и revision задаются во время выполнения

• коннектор, репозиторий и revision задаются во время выполнения.
• используется параметр времени выполнения $(params.git-url) в параметре url задачи git-clone.
• используется параметр времени выполнения $(params.git-revision) в параметре revision задачи git-clone.
• используется workspace source-workspace в workspace source задачи git-clone.

Например:

- name: app-source
  interface:
    category: "GitCodeRepository"
    apiVersion: "connectors.alauda.io/v1alpha1"
  connectorRef:
    setAtRuntime: true
  params:
  - name: repository
    setAtRuntime: true
  - name: revision
    setAtRuntime: true
  attributes:
  - name: url
    param: git-url
    value: $(params.git-url)
    refPath:
    - tasks.git-clone.params.url
  - name: revision
    param: git-revision
    value: $(params.git-revision)
    refPath:
    - tasks.git-clone.params.revision
  workspaces:
  - name: git-source
    workspace: source-workspace
    refPath:
    - tasks.git-clone.workspaces.output

#References

• What is Connector
• What is ResourceInterface