#PAC Resolver

В этом руководстве объясняется, как использовать Pipelines as Code (PAC) resolver для автоматического разрешения и внедрения задач и пайплайнов из трёх источников: локальных задач, определённых в вашем репозитории, удалённых задач из Tekton Hub и задач из удалённых Git-репозиториев или HTTP URL.

#Предварительные требования

• Компонент PAC развернут и работает
• Настроен Repository CR (см. Configure Repository)
• Понимание структуры Tekton PipelineRun

#О PAC Resolver

PAC resolver автоматически получает и внедряет удалённые задачи и пайплайны в определения PipelineRun. Это устраняет необходимость вручную определять задачи или использовать синтаксис resolver в вашем коде пайплайна.

#Поддерживаемые источники

• Локальные задачи: задачи, определённые в вашем Git-репозитории (с использованием taskSpec или синтаксиса resolver)
• Tekton Hub: задачи и пайплайны из каталога Tekton Hub
• Удалённые URL: задачи и пайплайны из удалённых Git-репозиториев или HTTP URL

#Официальная документация

Для получения полной информации о возможностях удалённого разрешения Pipelines as Code обратитесь к:

• Red Hat OpenShift Pipelines as Code Documentation
• Pipelines as Code Community Documentation

#Как работает PAC Resolver

Понимание рабочего процесса resolver поможет вам устранять неполадки и оптимизировать конфигурации пайплайнов.

#Рабочий процесс resolver

Когда PAC обрабатывает PipelineRun с аннотациями resolver, он выполняет следующие шаги:

1. Триггер события: Git-событие (push, pull request и т.д.) запускает контроллер PAC
2. Получение Pipeline: контроллер PAC получает определение PipelineRun из вашего Git-репозитория
3. Обнаружение аннотаций: контроллер PAC сканирует аннотации на предмет директив resolver:
   • pipelinesascode.tekton.dev/task: "task-name"
   • pipelinesascode.tekton.dev/task-1: "task-name"
   • pipelinesascode.tekton.dev/pipeline: "pipeline-name"
4. Разрешение задач: для каждой аннотации задачи:
   • контроллер PAC запрашивает API Tekton Hub (или настроенный URL хаба)
   • получает определение задачи (YAML)
   • проверяет структуру задачи
5. Внедрение задач: PAC внедряет разрешённые определения задач в PipelineRun:
   • PAC преобразует taskRef в taskSpec и внедряет определение задачи непосредственно в каждую задачу
   • Внедрённая задача становится частью определения PipelineRun, поэтому она не должна существовать как отдельный ресурс Task в кластере
6. Создание PipelineRun: PAC создаёт итоговый PipelineRun с внедрёнными задачами в Kubernetes
7. Выполнение: контроллер Tekton Pipeline подхватывает PipelineRun и выполняет его

#Подробный пример: пошаговое разрешение

Рассмотрим полный пример, чтобы увидеть, как работает resolver:

#Шаг 1: Исходное определение PipelineRun

Вы определяете PipelineRun в вашем репозитории (.tekton/pipelinerun.yaml):

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: my-pipeline
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]"
    pipelinesascode.tekton.dev/on-event: "[push]"
    pipelinesascode.tekton.dev/task: "git-clone"
spec:
  pipelineSpec:
    tasks:
    - name: fetch-code
      taskRef:
        name: git-clone
      params:
        - name: url
          value: "https://github.com/tektoncd/catalog.git"
        - name: revision
          value: "main"

#Шаг 2: Контроллер PAC обрабатывает аннотации

При возникновении события push контроллер PAC:

1. Читает PipelineRun из Git: PAC получает файл .tekton/pipelinerun.yaml из репозитория

2. Обнаруживает аннотацию: PAC сканирует аннотации на предмет задач, например pipelinesascode.tekton.dev/task: "git-clone"

3. Парсит имя задачи и версию:

   • Только имя задачи (например, "git-clone"): получает последнюю версию из Hub
   • С версией (например, "git-clone:0.1"): получает указанную версию
   • Выбор версии:
     • Если версия не указана → PAC запрашивает последнюю стабильную версию из Hub
     • Если версия указана (формат: task-name:version) → PAC получает именно эту версию
     • Формат версии соответствует семантическому версионированию (например, 0.1, 0.9, 1.2.3)

4. Запрос к API Tekton Hub:

   • URL хаба: по умолчанию внутренний сервис хаба в кластере (http://tekton-hub-api.tekton-pipelines:8000/v1) или публичный Hub (https://api.hub.tekton.dev/v1)
   • Запрос последней версии: PAC запрашивает у Hub последнюю доступную версию
   • Запрос конкретной версии: PAC запрашивает точную версию, указанную в аннотации
   • Примеры запросов:
     • Последняя: "git-clone" → Hub возвращает новейшую версию
     • Конкретная: "git-clone:0.1" → Hub возвращает версию 0.1

5. Получение определения задачи из Hub: Hub возвращает полный YAML задачи:

   apiVersion: tekton.dev/v1
   kind: Task
   metadata:
     name: git-clone
   spec:
     params:
     - name: url
       description: git url to clone
     - name: revision
       description: revision to checkout
     steps:
     - name: clone
       image: gcr.io/tekton-releases/git-init
       script: |
         #!/bin/sh
         git clone $(params.url) $(workspaces.output.path)
         cd $(workspaces.output.path)
         git checkout $(params.revision)

Рекомендации по выбору версии:

• Для продакшн-среды: указывайте точные версии (например, "git-clone:0.1") для воспроизводимости и стабильности
• Для разработки/тестирования: используйте последнюю версию (без суффикса версии) для автоматического получения новых функций и исправлений
• Фиксация версии: всегда фиксируйте версии в продакшне, чтобы избежать сбоев из-за обновлений в Hub
• Обновление версий: периодически проверяйте и обновляйте зафиксированные версии контролируемым образом

#Шаг 3: PAC внедряет задачу в PipelineRun

PAC изменяет PipelineRun, преобразуя taskRef в taskSpec и внедряя разрешённое определение задачи:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: my-pipeline
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]"
    pipelinesascode.tekton.dev/on-event: "[push]"
spec:
  pipelineSpec:
    tasks:
    - name: fetch-code
      # PAC преобразует taskRef в taskSpec и внедряет определение задачи
      taskSpec:
        params:
        - name: url
          description: git url to clone
        - name: revision
          description: revision to checkout
        steps:
        - name: clone
          image: gcr.io/tekton-releases/git-init
          script: |
            #!/bin/sh
            git clone $(params.url) $(workspaces.output.path)
            cd $(workspaces.output.path)
            git checkout $(params.revision)
      params:
        - name: url
          value: "https://github.com/tektoncd/catalog.git"
        - name: revision
          value: "main"

#Шаг 4: PipelineRun создаётся в Kubernetes

PAC создаёт итоговый PipelineRun в вашем кластере. Вы можете проверить его:

kubectl get pipelinerun my-pipeline -n <namespace> -o yaml

Пример вывода (сокращённый, с внедрённой задачей):

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: my-pipeline
spec:
  pipelineSpec:
    tasks:
    - name: fetch-code
      # Определение задачи внедрено как taskSpec
      taskSpec:
        params:
        - name: url
        - name: revision
        steps:
        - name: clone
          image: gcr.io/tekton-releases/git-init
          script: |
            #!/bin/sh
            git clone $(params.url) $(workspaces.output.path)
      params:
        - name: url
          value: "https://gitlab.com/user/repo"
        - name: revision
          value: "abc1234"

#Время разрешения resolver

Важно: разрешение задач происходит до создания PipelineRun в Kubernetes. Это означает:

• Задачи разрешаются на этапе определения пайплайна, а не во время выполнения
• Если задача не может быть разрешена, создание PipelineRun завершится ошибкой
• Вы можете проверить разрешение задач, просмотрев YAML PipelineRun в Kubernetes
• Разрешённые задачи кэшируются PAC для повышения производительности

#Проверка разрешения задач

Чтобы убедиться, что задачи разрешены корректно:

1. Проверьте PipelineRun в Kubernetes:

   kubectl get pipelinerun <name> -n <namespace> -o yaml

Ищите внедрённые задачи с taskSpec внутри отдельных задач:

spec:
  pipelineSpec:
    tasks:
    - name: fetch-code
      taskSpec:
        params:
        - name: url
        - name: revision
        steps:
        - name: clone
          image: gcr.io/tekton-releases/git-init
          script: |
            #!/bin/sh
            git clone $(params.url) $(workspaces.output.path)
      params:
        - name: url
          value: "https://gitlab.com/user/repo"
        - name: revision
          value: "abc1234"

2. Проверьте логи контроллера PAC:

   kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --tail=100 | grep -i "task.*resolve"  # Замените <pac-namespace> на ваш namespace (по умолчанию: tekton-pipelines)

Пример вывода (показывает разрешение задачи):

{"level":"info","ts":"2024-01-01T12:00:00Z","logger":"controller","msg":"Resolving task","task":"git-clone","source":"hub"}
{"level":"info","ts":"2024-01-01T12:00:01Z","logger":"controller","msg":"Task resolved successfully","task":"git-clone","version":"0.9"}
{"level":"info","ts":"2024-01-01T12:00:02Z","logger":"controller","msg":"Task embedded in PipelineRun","task":"git-clone","pipelineRun":"my-pipeline"}

3. Проверьте, что задача корректно ссылается:

   # Проверьте, что taskRef.name совпадает с именем задачи в аннотациях
   kubectl get pipelinerun <name> -n <namespace> -o jsonpath='{.spec.pipelineSpec.tasks[*].taskRef.name}'

Пример вывода:

git-clone golangci-lint

4. Проверьте успешность создания PipelineRun:

   kubectl get pipelinerun <name> -n <namespace> -o jsonpath='{.status.conditions[*].type}'

Пример вывода:

Succeeded

Если разрешение задачи не удалось, PipelineRun может не создаться или иметь состояние Failed с сообщением об ошибке.

#Использование локальных задач

Локальные задачи — это задачи, определённые непосредственно в вашем Git-репозитории. PAC поддерживает два способа использования локальных задач:

#Встроенное определение задачи (taskSpec)

Вы можете определить задачи прямо в PipelineRun с помощью taskSpec:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: my-pipeline
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]"
    pipelinesascode.tekton.dev/on-event: "[push]"
spec:
  pipelineSpec:
    tasks:
    - name: build
      taskSpec:
        steps:
        - name: build
          image: golang:1.21
          script: |
            #!/bin/sh
            go build -o app ./cmd
    - name: test
      taskSpec:
        steps:
        - name: test
          image: golang:1.21
          script: |
            #!/bin/sh
            go test ./...

Как это работает:

• Задачи определяются inline с помощью taskSpec внутри каждой задачи пайплайна
• Внешнее разрешение не требуется — задачи являются частью определения PipelineRun
• Удобно для простых задач, специфичных для репозитория

#Ссылка на файлы задач в репозитории

Вы можете ссылаться на файлы задач, хранящиеся в вашем репозитории, используя аннотации PAC со специальным синтаксисом для задач внутри репозитория.

Важно: для задач в вашем репозитории используйте формат аннотаций с pipelinesascode.tekton.dev/task или pipelinesascode.tekton.dev/task-<N>.

Структура репозитория:

.tekton/
├── pipelinerun.yaml
└── tasks/
    ├── build-task.yaml
    └── test-task.yaml

Определение PipelineRun с использованием аннотаций PAC:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: my-pipeline
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]"
    pipelinesascode.tekton.dev/on-event: "[push]"
    # Ссылка на локальные задачи с использованием относительных путей
    pipelinesascode.tekton.dev/task: ".tekton/tasks/build-task.yaml"
    pipelinesascode.tekton.dev/task-1: ".tekton/tasks/test-task.yaml"
spec:
  pipelineSpec:
    tasks:
    - name: build
      taskRef:
        name: build-task
    - name: test
      taskRef:
        name: test-task
      runAfter: [build]

Как это работает:

• PAC автоматически разрешает и внедряет задачи из вашего репозитория при использовании относительных путей в аннотациях задач
• Имя задачи в taskRef.name должно совпадать с именем задачи, определённым в YAML-файле
• Этот метод проще, чем использование синтаксиса resolver: git и рекомендуется для PAC

#Когда использовать локальные задачи

Используйте локальные задачи, когда:

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

#Использование аннотаций для удалённых задач

Вы можете использовать аннотации PAC для ссылки на удалённые задачи из Tekton Hub или удалённых HTTP URL. PAC автоматически получит и внедрит эти задачи в ваш PipelineRun.

#Удалённые задачи из Tekton Hub

Ссылка на одну задачу из Tekton Hub:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: my-pipeline
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]"
    pipelinesascode.tekton.dev/on-event: "[push]"
    pipelinesascode.tekton.dev/task: "git-clone"
spec:
  pipelineSpec:
    tasks:
    - name: fetch-code
      taskRef:
        name: git-clone
      params:
        - name: url
          value: "https://github.com/tektoncd/catalog.git"
        - name: revision
          value: "main"

Как это работает:

• Аннотация pipelinesascode.tekton.dev/task: "git-clone" указывает PAC получить задачу git-clone из Tekton Hub
• PAC автоматически внедряет определение задачи в ваш PipelineRun
• Вы можете ссылаться на неё через taskRef.name: git-clone

#Удалённые задачи из HTTP URL

Вы также можете ссылаться на задачи из удалённых HTTP URL:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: my-pipeline
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]"
    pipelinesascode.tekton.dev/on-event: "[push]"
    # Ссылка на задачу из удалённого URL
    pipelinesascode.tekton.dev/task: "https://raw.githubusercontent.com/tektoncd/catalog/main/task/git-clone/0.9/git-clone.yaml"
spec:
  pipelineSpec:
    tasks:
    - name: fetch-code
      taskRef:
        name: git-clone
      params:
        - name: url
          value: "https://github.com/tektoncd/catalog.git"
        - name: revision
          value: "main"

Как это работает:

• PAC получает определение задачи по указанному HTTP URL
• PAC автоматически внедряет задачу в ваш PipelineRun
• Имя задачи в taskRef.name должно совпадать с именем задачи, определённым в удалённом YAML-файле

#Несколько аннотаций задач

Ссылка на несколько задач с использованием нумерованных аннотаций:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: build-pipeline
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]"
    pipelinesascode.tekton.dev/on-event: "[push]"
    pipelinesascode.tekton.dev/task: "git-clone"
    pipelinesascode.tekton.dev/task-1: "golangci-lint"
    pipelinesascode.tekton.dev/task-2: "buildah"
spec:
  pipelineSpec:
    tasks:
    - name: fetch
      taskRef:
        name: git-clone
      params:
        - name: url
          value: "https://github.com/tektoncd/catalog.git"
        - name: revision
          value: "main"
    - name: lint
      taskRef:
        name: golangci-lint
      runAfter: [fetch]
    - name: build
      taskRef:
        name: buildah
      runAfter: [lint]

#Синтаксис списка задач

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

metadata:
  annotations:
    pipelinesascode.tekton.dev/task-1: "[golangci-lint, buildah]"

Это эквивалентно:

metadata:
  annotations:
    pipelinesascode.tekton.dev/task-1: "golangci-lint"
    pipelinesascode.tekton.dev/task-2: "buildah"

#Указание версии задачи

По умолчанию PAC получает последнюю версию задачи из Hub. Чтобы указать конкретную версию, используйте формат task-name:version.

Ссылка: Подробнее о разрешении удалённых задач см. в документации Red Hat OpenShift Pipelines as Code.

Последняя версия (рекомендуется для разработки):

metadata:
  annotations:
    pipelinesascode.tekton.dev/task: "git-clone"

Конкретная версия (рекомендуется для продакшна):

metadata:
  annotations:
    pipelinesascode.tekton.dev/task: "git-clone:0.9"

Несколько задач с версиями:

metadata:
  annotations:
    pipelinesascode.tekton.dev/task: "git-clone:0.9"
    pipelinesascode.tekton.dev/task-1: "golangci-lint:0.4"
    pipelinesascode.tekton.dev/task-2: "buildah"  # Используется последняя версия

#Пользовательский URL хаба

По умолчанию hub-url указывает на внутренний сервис Tekton Hub в namespace по умолчанию (http://tekton-hub-api.tekton-pipelines:8000/v1). Если Tekton Hub развернут в другом namespace, измените namespace в URL соответственно. Если нужно использовать другой экземпляр Hub, настройте его в CR OpenShiftPipelinesAsCode:

apiVersion: operator.tekton.dev/v1alpha1
kind: OpenShiftPipelinesAsCode
metadata:
  name: pipelines-as-code
spec:
  settings:
    # Для внутреннего Hub в другом namespace
    hub-url: "http://tekton-hub-api.<your-namespace>:8000/v1"
    
    # Или для внешнего/публичного Hub
    hub-url: "https://api.hub.tekton.dev/v1"
    
    # Или для кастомного экземпляра Hub
    hub-url: "https://custom-hub.example.com/v1"

Примечание: доступ к URL хаба требуется только контроллеру PAC. Если используется внутренний Hub, убедитесь, что контроллер PAC может достучаться до сервиса Hub.

#Использование аннотаций для удалённых пайплайнов

Вы можете ссылаться на удалённые пайплайны из Tekton Hub, хотя это встречается реже, чем использование inline-определений пайплайнов:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: my-pipeline
  annotations:
    pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]"
    pipelinesascode.tekton.dev/on-event: "[push]"
    # Ссылка на удалённый пайплайн из Tekton Hub
    pipelinesascode.tekton.dev/pipeline: "pipeline-name"
spec:
  pipelineRef:
    name: pipeline-name
  params:
  - name: image-url
    value: "registry.example.com/myapp"

Как это работает:

• Аннотация pipelinesascode.tekton.dev/pipeline: "pipeline-name" указывает PAC получить пайплайн из Tekton Hub
• PAC автоматически внедряет определение пайплайна
• Вы ссылаетесь на него через pipelineRef.name

Примечание: в большинстве случаев рекомендуется определять пайплайн inline с помощью pipelineSpec в вашем репозитории, а не использовать удалённые пайплайны. Это обеспечивает лучший контроль версий и видимость определений пайплайнов.

#Комбинирование удалённых задач и пайплайнов

#Сравнение с синтаксисом resolver

Аннотации PAC предоставляют более простой альтернативный синтаксис по сравнению с синтаксисом resolver Tekton:

#Использование аннотаций PAC (рекомендуется)

metadata:
  annotations:
    pipelinesascode.tekton.dev/task: "git-clone"
spec:
  pipelineSpec:
    tasks:
    - name: clone
      taskRef:
        name: git-clone

#Использование синтаксиса resolver

spec:
  pipelineSpec:
    tasks:
    - name: clone
      taskRef:
        resolver: hub
        params:
        - name: name
          value: git-clone
        - name: kind
          value: task

Преимущества аннотаций PAC:

• Проще синтаксис
• Автоматическое внедрение задач
• Нет необходимости указывать параметры resolver
• Работает бесшовно с разрешением задач PAC

#Устранение неполадок

#Задача не найдена

1. Проверьте имя задачи: убедитесь, что имя задачи корректно в Tekton Hub

2. Проверьте URL хаба: убедитесь, что URL хаба настроен правильно

3. Просмотрите логи PAC:

   kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --tail=100 | grep -i task

Пример вывода:

{"level":"info","ts":"2024-01-01T12:00:00Z","logger":"controller","msg":"Resolving task","task":"git-clone","source":"hub"}
{"level":"info","ts":"2024-01-01T12:00:01Z","logger":"controller","msg":"Task resolved successfully","task":"git-clone","version":"0.9"}
{"level":"info","ts":"2024-01-01T12:00:02Z","logger":"controller","msg":"Task embedded in PipelineRun","task":"git-clone","pipelineRun":"my-pipeline"}

#Ошибка разрешения задачи

1. Проверьте сетевое соединение: убедитесь, что контроллер PAC может достучаться до Tekton Hub

   # Тест подключения к Hub из пода контроллера PAC
   kubectl exec -n <pac-namespace> \
     $(kubectl get pod -n <pac-namespace> -l app=pipelines-as-code-controller -o jsonpath='{.items[0].metadata.name}') \
     -- curl -I https://api.hub.tekton.dev/v1/resource/task/git-clone

Пример вывода (если доступно):

HTTP/1.1 200 OK
Content-Type: application/json

2. Проверьте конфигурацию Hub: проверьте настройку hub-url в CR OpenShiftPipelinesAsCode

   kubectl get openshiftpipelinesascodes.operator.tekton.dev pipelines-as-code -o jsonpath='{.spec.settings.hub-url}'

Пример вывода:

http://tekton-hub-api.tekton-pipelines:8000/v1

3. Проверьте версию задачи: убедитесь, что указанная версия существует

   # Запрос доступных версий в Tekton Hub
   curl https://api.hub.tekton.dev/v1/resource/task/git-clone

Пример вывода (сокращённый):

{
  "id": 1,
  "name": "git-clone",
  "kind": "Task",
  "latestVersion": {
    "id": 1,
    "version": "0.9"
  },
  "versions": [
    {"version": "0.9"},
    {"version": "0.8"},
    {"version": "0.7"}
  ]
}

#Задача не внедрена

1. Проверьте синтаксис аннотаций: убедитесь в правильности ключей и формата значений аннотаций
2. Проверьте PipelineRun: убедитесь, что taskRef.name совпадает с именем задачи в аннотации
3. Просмотрите логи контроллера PAC на предмет ошибок внедрения

#Следующие шаги

• Maintain Pipeline Code - Руководство по определению пайплайнов
• Advanced Repository Configuration - Расширенные настройки Repository CR
• Manage PipelineRuns - Управление PipelineRun
• Common Issues - Руководство по устранению неполадок