#Основные концепции PAC

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

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

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

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

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

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

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

#1. Концепция репозитория

#1.1. Custom Resource Repository

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

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

• spec.url: URL Git-репозитория
• spec.git_provider: конфигурация Git-провайдера (тип, URL, учетные данные)
• spec.webhook: конфигурация webhook (секрет для валидации)

Пример:

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-провайдеров
• Получает определения пайплайнов из Git-репозиториев
• Создаёт ресурсы PipelineRun в Kubernetes
• Управляет Custom Resources Repository

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

#3. PAC Watcher

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

• Отслеживает статус пайплайна (ожидание, выполнение, успех, ошибка)
• Отправляет статус обратно Git-провайдеру
• Обновляет статус коммита и проверки Pull Request/Merge Request

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

#4. PAC Webhook

PAC Webhook принимает HTTP-запросы от Git-провайдеров:

• Проверяет подписи webhook
• Обрабатывает полезные нагрузки webhook
• Перенаправляет события в PAC Controller

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

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

#1. Регистрация репозитория

При настройке репозитория с помощью tkn pac create repo:

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

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

PAC Event Flow Diagram

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

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

#3. Выполнение пайплайна

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

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

#Kubernetes

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

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

#Интеграция с Git-провайдерами

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

Конфигурация webhook:

• URL: конечная точка контроллера PAC
• Секрет: секрет webhook для валидации
• События: push, Pull Request/Merge Request, комментарии

Отчёт о статусе:

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

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

• Personal Access Token или токены приложений с соответствующими правами (зависит от провайдера)
• Хранится в Kubernetes Secret

Для деталей настройки провайдера смотрите:

• Configure Repository
• Руководства по конкретным провайдерам в документации

#Определение пайплайна

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

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

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

#Структура пайплайна

Пайплайн PAC — это стандартный 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 использует аннотации для определения момента запуска пайплайнов:

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

Подробнее см. Event Annotations.

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

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

Подробнее см. Parameterizing Commits and URLs.

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

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

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

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

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

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

Полный список доступных переменных и их использование см. в Parameterizing Commits and URLs.

#Разрешение задач

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

1. Локальные задачи: задачи, определённые в репозитории
2. Tekton Hub: задачи из каталога Tekton Hub
3. Удалённые URL: задачи из удалённых Git-репозиториев или URL

Подробнее см. PAC Resolver.

#Вопросы безопасности

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

• Секреты webhook проверяют входящие запросы
• Секреты хранятся в Kubernetes Secrets
• Git-провайдеры проверяют подписи webhook

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

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

#Разрешения пайплайнов

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

#Лучшие практики

#1. Организация репозитория

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

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

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

#3. Управление задачами

• Используйте задачи из Tekton Hub, когда возможно
• Создавайте переиспользуемые определения задач
• Контролируйте версии определений задач

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

• Не храните секреты в файлах пайплайнов
• Используйте Kubernetes Secrets
• Ограничивайте разрешения пайплайнов

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

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

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

Для подробного устранения неполадок см. Common Issues.

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

• Quick Start - Начало работы с PAC
• Manage PAC Component - Развёртывание и управление PAC
• Configure Repository - Настройка интеграции репозитория
• Maintain Pipeline Code - Определение пайплайнов в коде

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

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