#PAC-резолвер

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

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

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

#О PAC Resolver

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

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

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

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

   • URL 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 задачи:

   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, чтобы избежать breaking changes из-за обновлений 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 поддерживает два способа использования локальных задач:

#Inline-определение задачи (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 автоматически разрешает и встраивает задачи из вашего репозитория, когда вы используете относительные пути в аннотациях task
• Имя задачи в 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-файле

#Несколько аннотаций task

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

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.

PAC разрешает задачи Hub по имени и при необходимости может зафиксировать версию задачи с помощью task-name:version.

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

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

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

Значение 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"

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

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

• Определение PipelineRun в Git - файлы PipelineRun и аннотации триггеров
• Расширенная конфигурация репозитория - расширенные настройки CR Repository
• Управление PipelineRun - управление PipelineRun
• Распространённые проблемы - руководство по устранению неполадок