#Интеграция Pipeline

#Обзор

При построении CI/CD pipeline с Tekton разработчикам часто требуется интеграция с внешними ресурсами, такими как Git repositories, container registries и artifact repositories. Традиционно это требует ручной настройки URL, учетных данных и параметров для каждого внешнего инструмента, что подвержено ошибкам и занимает много времени.

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

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

#Что такое Pipeline Integration

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

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

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

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

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

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

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

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

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

Метаданные интеграции хранятся с использованием аннотации 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

Имя pipeline integration.

name: "code-repo"

#Ссылка на ResourceInterface

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

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

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

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

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

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

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

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

#Ссылка на Connector

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

connectorRef:
  name: "github-connector"        # Connector name
  namespace: "default"            # Optional, defaults to same namespace as pipeline
  setAtRuntime: true              # Whether to select connector at runtime

Параметры конфигурации:

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

#Параметры

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

params:
- name: repository
  value: "myorg/myapp"           # Fixed value
  setAtRuntime: false            # Not changeable at runtime
- name: revision
  value: "main"                  # Default value
  setAtRuntime: true             # Can be changed at runtime

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

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

#Атрибуты

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

attributes:
- name: url
  param: git-url                 # Pipeline parameter name (when parameterized)
  transform:                     # Optional value transform
    prefix: "https://"           # Add prefix before resolved attribute value
    suffix: ".git"               # Add suffix after resolved attribute value
    accessor: "repository"       # Read sub-value (field/index) from structured attribute
  refPath:                       # Where this attribute is used
  - tasks.git-clone.params.url   # PipelineTask parameter that receives this value
- name: revision
  value: "refs/heads/main"       # Static value (no parameterization)
  refPath:
  - tasks.git-clone.params.revision

Конфигурация атрибутов:

• Имя атрибута должно соответствовать ResourceInterface.spec.attributes[].name
• Значение атрибута вычисляется с использованием выражения, определенного в ResourceInterface.spec.attributes[].expression
• Параметризованные атрибуты создают параметры pipeline (указываются в поле param)
• Статические атрибуты используют фиксированные значения (указываются в поле value)
• transform при необходимости корректирует вычисленное значение атрибута перед сопоставлением:
  • prefix: добавляет префикс к значению атрибута
  • suffix: добавляет суффикс к значению атрибута
  • accessor: выбирает подзначение из структурированного атрибута:
    • для массивов используйте индекс (например, "0")
    • для объектов используйте имя поля (например, "repository")
    • после выбора подзначения с помощью accessor результирующее значение атрибута преобразуется в string
• refPath определяет, где используется значение атрибута в задачах pipeline

Краткий пример (transform)

attributes:
- name: artifacts
  param: chartRef
  transform:
    accessor: "0"
    prefix: "oci://"
    suffix: "-prod"

Если вычисленное значение artifacts равно ["registry.example.com/team/app"], это сопоставление использует первый элемент и формирует oci://registry.example.com/team/app-prod.

• Используйте accessor, когда атрибут является массивом/объектом и вам нужен только один элемент/поле.
• Используйте prefix, когда downstream task ожидает фиксированный протокол или буквальный префикс (например, oci://).
• Используйте suffix, когда downstream task требуется фиксированный постфикс, например маркер среды (например, -prod).

#Workspace

Сопоставление workspace между workspace ResourceInterface и workspace pipeline:

workspaces:
- name: git-source              # ResourceInterface workspace name
  workspace: source-workspace   # Pipeline workspace name
  refPath:                      # Where this workspace is used
  - 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
• Pipeline workspace автоматически создается с именем, заданным в поле workspace, а значение по умолчанию берется из ResourceInterface.spec.workspaces[].workspaceMapping.name.
• refPath определяет, какой workspace какого pipelinetask использует этот workspace.

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

Tasks могут объявлять поддержку интеграции, чтобы включить автоматическое сопоставление параметров и 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 задается во время выполнения

• connector и repository заданы фиксированными значениями, 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

Connector, repository и revision задаются во время выполнения

• connector, repository и 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

#Ссылки

• What is Connector
• What is ResourceInterface