#Основные концепции 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 создаётся Custom Resource Repository
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. Поиск репозитория → Контроллер находит соответствующий Repository CR
5. Загрузка пайплайна → Контроллер загружает определения пайплайна из Git
6. Создание PipelineRun → Контроллер создаёт 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
• Команды на основе комментариев

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

• Персональный токен доступа или токены приложений с соответствующими правами (зависит от провайдера)
• Хранится в 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
• ServiceAccount контролируют права пайплайна
• Секреты монтируются по необходимости

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

#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