#Основные понятия PAC Core

В этом документе приведен подробный обзор основных понятий, лежащих в основе Pipelines-as-Code (PAC), его архитектуры и интеграции с Kubernetes и Git provider.

#Что такое Pipelines as Code?

Pipelines-as-Code (PAC) — это компонент, который позволяет определять и управлять рабочими процессами Tekton Pipeline непосредственно в репозитории исходного кода. Вместо того чтобы хранить pipeline в кластере Kubernetes, вы можете:

• Хранить определения pipeline в Git рядом с кодом
• Версионировать конфигурации pipeline
• Проверять изменения pipeline через Merge Requests
• Автоматически запускать pipeline по событиям Git

#Обзор архитектуры

PAC состоит из нескольких ключевых компонентов, которые работают вместе:

#Основные компоненты

#1. Концепция Repository

#1.1. Repository Custom Resource

Repository Custom Resource определяет связь между Git repository и PAC controller.

Ключевые поля:

• spec.url: URL Git repository
• spec.git_provider: конфигурация Git provider (type, URL, credentials)
• spec.webhook: конфигурация Webhook (secret для проверки)

Пример:

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-repo
  namespace: project-pipelines
spec:
  url: "https://gitlab.com/user/repo"
  git_provider:
    type: gitlab
    url: "https://gitlab.com"
    secret:
      name: gitlab-secret
      key: token
    webhook_secret:
      name: webhook-secret
      key: secret

#2. PAC Controller

PAC Controller — это основной компонент, который:

• Получает события webhook от Git provider
• Извлекает определения pipeline из Git repositories
• Создает ресурсы PipelineRun в Kubernetes
• Управляет Repository CR (Custom Resources)

Развертывание: Развертывается как Kubernetes Deployment в namespace (по умолчанию: tekton-pipelines, но может быть настроен через targetNamespace в CR OpenShiftPipelinesAsCode).

#3. PAC Watcher

PAC Watcher отслеживает выполнение PipelineRun и:

• Отслеживает состояние pipeline (pending, running, success, failure)
• Отправляет статус обратно в Git provider
• Обновляет статус commit и проверки Pull Request/Merge Request

Развертывание: Развертывается как Kubernetes Deployment в namespace (по умолчанию: tekton-pipelines, но может быть настроен через targetNamespace в CR OpenShiftPipelinesAsCode).

#4. PAC Webhook

PAC Webhook получает HTTP-запросы от Git provider:

• Проверяет подписи webhook
• Обрабатывает payload webhook
• Пересылает события в PAC Controller

Развертывание: Развертывается как Kubernetes Service и при необходимости публикуется через Ingress/NodePort.

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

#1. Регистрация Repository

Когда вы настраиваете repository с помощью tkn pac create repo:

1. В вашем кластере Kubernetes создается Repository CR
2. В Git provider настраивается webhook, указывающий на PAC controller
3. Создается Kubernetes Secret с учетными данными Git provider
4. Генерируется базовый шаблон .tekton/pipelinerun.yaml

#2. Поток событий

Схема потока событий PAC

Когда происходит событие Git (push, pull request, merge request, comment):

1. Git provider отправляет webhook → PAC Webhook получает событие
2. Проверка webhook → PAC проверяет подпись webhook
3. Обработка события → PAC Controller обрабатывает событие
4. Поиск repository → Controller находит соответствующий Repository CR
5. Получение pipeline → Controller извлекает определения pipeline из Git
6. Создание PipelineRun → Controller создает PipelineRun в Kubernetes
7. Мониторинг статуса → PAC Watcher отслеживает выполнение PipelineRun
8. Отправка статуса → Watcher отправляет статус обратно в Git provider

#3. Выполнение Pipeline

1. PAC Controller создает PipelineRun на основе определения pipeline
2. Контроллер Tekton Pipeline подхватывает PipelineRun
3. Задачи pipeline выполняются последовательно
4. PAC Watcher отслеживает выполнение
5. Статус отправляется обратно в Git provider

#Поддержка платформ

#Kubernetes

PAC можно развернуть в стандартных кластерах Kubernetes через Tekton Operator. Хотя в имени ресурса присутствует "OpenShift", патч позволяет поддерживать PAC controller в Kubernetes.

Развертывание: Создайте CR OpenShiftPipelinesAsCode напрямую.

#Интеграция с Git Provider

PAC поддерживает несколько Git provider, включая GitHub, GitLab, Bitbucket Cloud и Bitbucket Data Center. У каждого provider есть свои особенности интеграции:

Настройка Webhook:

• URL: endpoint PAC controller
• Secret: secret webhook для проверки
• Events: Push, Pull Request/Merge Request, Comments

Отправка статуса:

• Обновления статуса commit
• Проверки статуса Pull Request/Merge Request
• Команды на основе комментариев

Аутентификация:

• Personal Access Token или App token с соответствующими scopes (зависит от provider)
• Хранится в Kubernetes Secret

Для получения сведений о конфигурации для конкретного provider см.:

• Настройка Repository
• Руководства для конкретных provider в документации

#Определение Pipeline

#Расположение файлов

По умолчанию PAC ищет определения pipeline в следующих местах:

• .tekton/pipelinerun.yaml (будут обработаны все манифесты PipelineRun в .tekton/*.yaml)
• Все файлы .yaml и .yml в каталоге .tekton/

#Структура Pipeline

PAC pipeline — это стандартный Tekton 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]"
spec:
  pipelineSpec:
    tasks:
    - name: hello
      taskSpec:
        steps:
        - name: echo
          image: alpine:latest
          script: |
            echo "Hello from PAC!"

#Аннотации событий

PAC использует аннотации, чтобы определить, когда запускать pipeline:

• pipelinesascode.tekton.dev/on-target-branch: Целевая ветка для события (например, "[main]" или "[refs/heads/main]")
• pipelinesascode.tekton.dev/on-event: Тип события (например, "[push]" или "[pull_request]")
• pipelinesascode.tekton.dev/on-comment: Запуск по командам в комментарии

Дополнительные сведения см. в разделе Аннотации событий.

#Переменные и контекст

PAC предоставляет динамические переменные, которые можно использовать в определениях pipeline. Переменные используют формат {{<var>}} и автоматически подставляются PAC при создании PipelineRun.

Дополнительные сведения см. в разделе Параметризация commit и URL.

#Переменные контекста Git

• {{repo_url}}: Полный URL repository
• {{revision}}: Полный SHA revision commit
• {{source_branch}}: Имя ветки, в которой возникло событие
• {{target_branch}}: Имя ветки, на которую направлено событие
• {{repo_owner}}: Владелец repository
• {{repo_name}}: Имя repository

#Переменные контекста события

• {{sender}}: Имя пользователя или ID учетной записи, отправившей событие

#Переменные контекста Pull Request / Merge Request

• {{pull_request_number}}: Номер Pull Request или Merge Request (доступно только для событий pull_request)

Полный список доступных переменных и способы их использования см. в разделе Параметризация commit и URL.

#Разрешение Tasks

PAC может автоматически находить tasks из нескольких источников:

1. Локальные tasks: Tasks, определенные в repository
2. Tekton Hub: Tasks из каталога Tekton Hub
3. Удаленные URLs: Tasks из удаленных Git repositories или URL

Дополнительные сведения см. в PAC Resolver.

#Соображения безопасности

#Безопасность Webhook

• Webhook secrets проверяют входящие запросы
• Secrets хранятся в Kubernetes Secrets
• Git providers проверяют подписи webhook

#Контроль доступа

• Repository CR имеют область действия namespace
• RBAC определяет, кто может создавать Repository CR
• Токены Git provider имеют ограниченные scopes в целях безопасности

#Разрешения Pipeline

• PipelineRun выполняются в указанных namespace
• ServiceAccount управляют разрешениями pipeline
• Secrets монтируются по мере необходимости

#Рекомендации

#1. Организация Repository

• Храните определения pipeline в каталоге .tekton/
• Используйте понятные имена pipeline
• Версионируйте все изменения pipeline

#2. Фильтрация событий

• Используйте конкретные шаблоны веток
• Используйте фильтрацию по путям, чтобы ограничить запуск
• Разделяйте pipeline для merge request и push

#3. Управление tasks

• По возможности используйте tasks из Tekton Hub
• Создавайте переиспользуемые определения tasks
• Версионируйте определения tasks

#4. Безопасность

• Не задавайте secrets напрямую в файлах pipeline
• Используйте Kubernetes Secrets
• Ограничивайте разрешения pipeline

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

#Распространенные проблемы

1. Pipeline не запускается: Проверьте аннотации и имена веток
2. Webhook не получен: Проверьте URL webhook и secret
3. Tasks не найдены: Проверьте ссылки на tasks и сетевое подключение
4. Статус не отправляется: Проверьте права токена Git provider

Подробные сведения по устранению неполадок см. в Распространенные проблемы.

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

• Быстрый старт - Начните работу с PAC
• Управление компонентом PAC - Развертывание и управление PAC
• Настройка Repository - Настройка интеграции repository
• Поддержка pipeline code - Определение pipeline в коде

#Связанная документация

• Pipeline As Code - Официальная документация Pipelines As Code