#PAC Resolver

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

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

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

#О PAC Resolver

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

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

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

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

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

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

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

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

#Рабочий процесс 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 отправляет запрос в Tekton Hub API (или настроенный URL Hub)
   • получает определение задачи (YAML)
   • проверяет структуру задачи
5. Внедрение задачи: PAC внедряет разрешённые определения задач в PipelineRun:
   • PAC преобразует taskRef в taskSpec и внедряет определение задачи inline в каждую запись задачи
   • Внедрённая задача становится частью определения 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 получает именно эту версию
     • Формат версии соответствует semantic versioning (например, 0.1, 0.9, 1.2.3)

4. Запрашивает Tekton Hub API:

   • Hub URL: по умолчанию используется внутренний кластерный Hub (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-определение Task:

   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)

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

• Production-среды: указывайте точные версии (например, "git-clone:0.1") для воспроизводимости и стабильности
• Разработка/тестирование: используйте последнюю версию (без суффикса версии), чтобы автоматически получать новые функции и исправления ошибок
• Фиксация версии: всегда фиксируйте конкретные версии в production, чтобы избежать несовместимых изменений из-за обновлений 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 converts taskRef to taskSpec and embeds the task definition
      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
      # Task definition is embedded as 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. Это означает:

• Задачи разрешаются на этапе определения pipeline, а не во время выполнения
• Если задачу невозможно разрешить, создание 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"  # Replace <pac-namespace> with your actual namespace (default: 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. Проверьте, что задача корректно указана:

   # Check that taskRef.name matches the task name in annotations
   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 внутри каждой задачи pipeline
• Внешнее разрешение не требуется — задачи уже являются частью определения 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]"
    # Reference local tasks using relative paths
    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

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

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

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

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

Вы можете использовать аннотации 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]"
    # Reference task from remote 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 documentation.

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

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

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

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"  # Uses latest

#Пользовательский Hub 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:
    # For cluster-internal Hub in different namespace
    hub-url: "http://tekton-hub-api.<your-namespace>:8000/v1"
    
    # Or for external/public Hub
    hub-url: "https://api.hub.tekton.dev/v1"
    
    # Or for custom Hub instance
    hub-url: "https://custom-hub.example.com/v1"

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

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

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

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]"
    # Reference remote pipeline from 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 получить pipeline из Tekton Hub
• PAC автоматически внедряет определение pipeline
• Вы ссылаетесь на него с помощью pipelineRef.name

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

#Объединение удалённых задач и pipeline

#Сравнение с синтаксисом 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. Проверьте Hub URL: убедитесь, что URL Hub настроен правильно

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

   # Test Hub connectivity from PAC controller pod
   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. Проверьте версию задачи: убедитесь, что указанная версия существует

   # Query Tekton Hub for available versions
   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 - Руководство по определению Pipeline
• Advanced Repository Configuration - Расширенные настройки CR Repository
• Manage PipelineRuns - Управление PipelineRun
• Common Issues - Руководство по устранению неполадок