#PipelineRuns

PipelineRun — это пользовательский ресурс Kubernetes, который создаёт экземпляр Pipeline для выполнения. PipelineRuns отвечают за выполнение Tasks, определённых в Pipeline, и управление их жизненным циклом, предоставляя способ запуска сквозных CI/CD рабочих процессов.

#Зачем нужны PipelineRuns

#Задачи CI/CD рабочих процессов

В системах CI/CD существует несколько задач, связанных с выполнением рабочих процессов:

• Оркестрация рабочего процесса: необходимость координировать несколько задач в определённом порядке
• Координация ресурсов: управление ресурсами между несколькими задачами
• Обмен данными: необходимость обмена данными между задачами в рабочем процессе
• Отслеживание выполнения: контроль прогресса всего рабочего процесса
• Обработка ошибок: управление сбоями как на уровне задач, так и всего рабочего процесса
• Аудит: ведение записи всех выполнений рабочего процесса

#Решение Tekton

PipelineRuns Tekton решают эти задачи следующим образом:

• Экземпляр рабочего процесса: каждый PipelineRun представляет собой отдельное выполнение Pipeline с конкретными входными данными
• Оркестрация: PipelineRuns управляют порядком выполнения Tasks на основе зависимостей
• Привязка ресурсов: PipelineRuns связывают реальные ресурсы с требованиями Pipeline
• Отслеживание статуса: PipelineRuns отслеживают статус выполнения каждой Task
• Передача результатов: PipelineRuns обеспечивают обмен результатами между Tasks
• Интеграция с Kubernetes: PipelineRuns используют возможности Kubernetes для управления ресурсами и планирования

#Преимущества

• Изоляция: каждый PipelineRun выполняется независимо, что позволяет параллельно запускать один и тот же Pipeline
• Отслеживаемость: PipelineRuns предоставляют подробную историю выполнения и логи
• Гибкость: PipelineRuns могут переопределять параметры Pipeline и привязки рабочих областей
• Повторное использование: один и тот же Pipeline может выполняться с разными входными данными через разные PipelineRuns
• Интеграция: PipelineRuns могут запускаться различными системами через Kubernetes API
• Наблюдаемость: статус и логи PipelineRun можно мониторить с помощью инструментов Kubernetes

#Сценарии использования

PipelineRuns полезны в различных сценариях, включая:

• CI/CD приложений: сборка, тестирование и деплой приложений
• Infrastructure as Code: Provision и управление инфраструктурой
• Управление релизами: координация сложных процессов релиза
• Запланированные рабочие процессы: запуск рабочих процессов по расписанию
• Событийно-ориентированные рабочие процессы: запуск рабочих процессов в ответ на внешние события

#Ограничения и лимиты

• PipelineRuns выполняются в пределах одного кластера Kubernetes
• После запуска параметры PipelineRun изменить нельзя
• PipelineRuns имеют ограниченные возможности повторных попыток для неудачных Tasks
• Время выполнения PipelineRun ограничено таймаутами pod Kubernetes
• PipelineRuns нельзя приостанавливать после начала выполнения (за исключением задач "finally")

#Принципы

#Модель выполнения PipelineRun

При создании PipelineRun:

1. Tekton проверяет спецификацию PipelineRun
2. Tekton создаёт TaskRuns для каждой Task в Pipeline
3. TaskRuns выполняются согласно зависимостям
4. Результаты Tasks собираются и могут использоваться последующими Tasks
5. Статус PipelineRun обновляется по мере завершения каждого TaskRun
6. Задачи "finally" выполняются после завершения или сбоя всех остальных Tasks
7. PipelineRun завершается, когда все TaskRuns завершены

#Статус PipelineRun

Статус PipelineRun предоставляет подробную информацию о выполнении:

1. Общий статус (Running, Succeeded, Failed и т.д.)
2. Время начала и завершения
3. Статусы отдельных TaskRun
4. Результаты Tasks
5. Причина сбоя (если применимо)
6. Имена TaskRun для доступа к логам

#Примеры конфигурации

#Пример базового PipelineRun

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: build-deploy-app-run
spec:
  pipelineRef:
    name: build-deploy-app
  params:
    - name: image-name
      value: my-registry/my-app:latest
    - name: deployment-name
      value: my-app
  workspaces:
    - name: source
      persistentVolumeClaim:
        claimName: app-source-pvc

#PipelineRun с встроенным определением Pipeline

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: simple-pipeline-run
spec:
  pipelineSpec:
    params:
      - name: message
        type: string
    tasks:
      - name: print-message
        taskSpec:
          params:
            - name: message
              type: string
          steps:
            - name: print
              image: ubuntu
              script: |
                echo "$(params.message)"
        params:
          - name: message
            value: "$(params.message)"
  params:
    - name: message
      value: "Hello, Tekton Pipeline!"

#Важные параметры

#Timeout

Timeout позволяет задать максимальную продолжительность выполнения PipelineRun.

#Сценарии использования

• Предотвращение бесконечного потребления ресурсов длительными Pipeline
• Обеспечение завершения CI/CD рабочих процессов в разумные сроки
• Обработка зависших или заблокированных Tasks
• Установка различных лимитов времени для разных фаз выполнения pipeline

#Принципы

Таймауты:

• Задаются в спецификации PipelineRun через поле timeouts (устаревшее поле timeout не рекомендуется)
• Применяются ко всему PipelineRun или к отдельным секциям (tasks, finally)
• Измеряются от начала первой Task до завершения последней
• Приводят к ошибке PipelineRun при превышении
• Должны удовлетворять условию: timeouts.pipeline >= timeouts.tasks + timeouts.finally
• Важно: если любое из подполей установлено в "0", таймаут для этой секции отсутствует. Чтобы установить timeouts.tasks или timeouts.finally в "0", необходимо также установить timeouts.pipeline в "0"

#Поля таймаута

• pipeline: максимальная продолжительность всего PipelineRun
• tasks: максимальная продолжительность всех обычных задач
• finally: максимальная продолжительность всех задач finally

#Примеры конфигурации

Пример 1: Стандартная конфигурация таймаута

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: build-deploy-with-timeout
spec:
  pipelineRef:
    name: build-deploy-app
  timeouts:
    pipeline: "1h"    # Общий таймаут pipeline
    tasks: "45m"      # Таймаут для всех обычных задач
    finally: "15m"    # Таймаут для задач finally
  params:
    - name: image-name
      value: my-registry/my-app:latest

Пример 2: Отсутствие таймаута для tasks и finally (требует pipeline timeout = 0)

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: build-deploy-no-timeout
spec:
  pipelineRef:
    name: build-deploy-app
  timeouts:
    pipeline: "0"     # Нет общего таймаута
    tasks: "0"        # Нет таймаута для обычных задач
    finally: "0"      # Нет таймаута для finally задач
  params:
    - name: image-name
      value: my-registry/my-app:latest

Примечание:

• В примере 1 соблюдается условие pipeline (1h) >= tasks (45m) + finally (15m)
• В примере 2 показано, как отключить таймауты, установив все значения в "0"

#ServiceAccount

ServiceAccount позволяет указать Kubernetes ServiceAccount для аутентификации.

#Сценарии использования

• Предоставление учётных данных для доступа к приватным реестрам контейнеров
• Аутентификация в облачных провайдерах
• Авторизация доступа к ресурсам Kubernetes
• Предоставление учётных данных для операций с Git

#Принципы

ServiceAccount:

• Может задаваться на уровне PipelineRun для всех Tasks
• Может быть назначен конкретным Tasks через taskRunSpecs
• Предоставляет учётные данные через Kubernetes secrets
• Обеспечивает безопасный доступ к внешним ресурсам

#Пример конфигурации

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: build-deploy-with-service-account
spec:
  pipelineRef:
    name: build-deploy-app
  taskRunTemplate:
    serviceAccountName: pipeline-service-account
  params:
    - name: image-name
      value: my-registry/my-app:latest

#Pod Template

Pod Template позволяет указать шаблон Pod, который будет использоваться как основа для конфигурации Pod, выполняющего каждую Task.

#Сценарии использования

• Установка node selectors для специфических аппаратных требований
• Настройка tolerations для выделенных узлов
• Указание security contexts для повышения безопасности
• Задание лимитов и запросов ресурсов на уровне Pod
• Настройка правил affinity для оптимального использования ресурсов
• Добавление пользовательских аннотаций или меток к Pod

#Принципы

Pod Templates:

• Применяются ко всем Tasks в PipelineRun, если не переопределены в taskRunSpecs
• Соответствуют спецификациям шаблонов Pod Kubernetes
• Могут быть переопределены конфигурациями конкретных Tasks в taskRunSpecs
• Обеспечивают единообразную конфигурацию Pod для всех Tasks PipelineRun
• Поддерживают все стандартные поля шаблона Pod Kubernetes

#Пример конфигурации

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: build-deploy-with-pod-template
spec:
  pipelineRef:
    name: build-deploy-app
  taskRunTemplate:
    serviceAccountName: default
    # Глобальный шаблон Pod для всех Tasks в PipelineRun
    podTemplate:
      nodeSelector:
        disktype: ssd
        environment: production
      tolerations:
      - key: "dedicated"
        operator: "Equal"
        value: "pipeline"
        effect: "NoSchedule"
      securityContext:
        runAsNonRoot: true
        runAsUser: 1000
        fsGroup: 2000
      affinity:
        nodeAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
            nodeSelectorTerms:
            - matchExpressions:
              - key: kubernetes.io/os
                operator: In
                values:
                - linux
  params:
    - name: image-name
      value: my-registry/my-app:latest

#TaskRunSpecs

TaskRunSpecs позволяют настраивать отдельные TaskRun внутри PipelineRun, задавая список PipelineTaskRunSpec, который позволяет устанавливать ServiceAccountName, Pod template и Metadata для каждой задачи.

#Сценарии использования

• Назначение разных ServiceAccount для разных Tasks для тонкой настройки доступа
• Установка специфичных Pod шаблонов для Tasks с разными требованиями к ресурсам или безопасности
• Конфигурация метаданных Tasks для лучшей организации и отслеживания
• Переопределение глобальных настроек PipelineRun для отдельных Tasks
• Применение разных вычислительных ресурсов или node selectors для разных этапов Pipeline

#Принципы

TaskRunSpecs:

• Переопределяют Pod template, установленный для всего Pipeline
• Позволяют тонко настраивать окружение выполнения Tasks
• Используются для удовлетворения специфических требований безопасности, ресурсов или планирования
• Позволяют задавать разные конфигурации для разных этапов Pipeline
• Поддерживают все стандартные спецификации шаблонов Pod Kubernetes
• Могут комбинироваться с глобальными настройками PipelineRun

#Поля конфигурации

Каждый TaskRunSpec поддерживает следующие поля:

• pipelineTaskName: имя задачи Pipeline, к которой применяется конфигурация
• serviceAccountName: ServiceAccount для конкретной задачи
• podTemplate: конфигурация Pod шаблона для этой задачи
• metadata: конфигурация метаданных для TaskRun

#Примеры конфигурации

Пример 1: Базовые TaskRunSpecs с ServiceAccount и Pod Template

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: build-deploy-with-taskrunspecs
spec:
  pipelineRef:
    name: build-deploy-app
  taskRunSpecs:
    - pipelineTaskName: build
      serviceAccountName: build-service-account
      podTemplate:
        nodeSelector:
          disktype: ssd
          environment: build
        tolerations:
        - key: "dedicated"
          operator: "Equal"
          value: "build"
    - pipelineTaskName: deploy
      serviceAccountName: deploy-service-account
      podTemplate:
        nodeSelector:
          disktype: ssd
          environment: production
        tolerations:
        - key: "dedicated"
          operator: "Equal"
          value: "deploy"
          effect: "NoSchedule"
  params:
    - name: image-name
      value: my-registry/my-app:latest

Пример 2: TaskRunSpecs с расширенной конфигурацией Pod

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: advanced-taskrunspecs
spec:
  pipelineRef:
    name: multi-stage-pipeline
  taskRunSpecs:
    - pipelineTaskName: build
      serviceAccountName: build-sa
      podTemplate:
        nodeSelector:
          gpu: available
          disktype: nvme
        securityContext:
          runAsNonRoot: true
          runAsUser: 1000
    - pipelineTaskName: test
      serviceAccountName: test-sa
      podTemplate:
        nodeSelector:
          environment: testing
        tolerations:
        - key: "test-only"
          operator: "Equal"
          value: "true"
          effect: "NoSchedule"
    - pipelineTaskName: deploy
      serviceAccountName: deploy-sa
      podTemplate:
        nodeSelector:
          environment: production
        affinity:
          nodeAffinity:
            requiredDuringSchedulingIgnoredDuringExecution:
              nodeSelectorTerms:
              - matchExpressions:
                - key: kubernetes.io/os
                  operator: In
                  values:
                  - linux

Пример 3: TaskRunSpecs с конфигурацией метаданных

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: taskrunspecs-with-metadata
spec:
  pipelineRef:
    name: build-test-deploy
  taskRunSpecs:
    - pipelineTaskName: build
      serviceAccountName: build-sa
      metadata:
        labels:
          stage: build
          environment: development
        annotations:
          tekton.dev/description: "Build stage with optimized resources"
      podTemplate:
        nodeSelector:
          disktype: ssd
    - pipelineTaskName: deploy
      serviceAccountName: deploy-sa
      metadata:
        labels:
          stage: deploy
          environment: production
        annotations:
          tekton.dev/description: "Production deployment stage"
      podTemplate:
        nodeSelector:
          environment: production

Пример 4: TaskRunSpecs, переопределяющие глобальный Pod Template

TaskRunSpecs могут переопределять глобальный Pod template, заданный на уровне PipelineRun:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: override-global-template
spec:
  pipelineRef:
    name: build-deploy-app
  taskRunTemplate:
    serviceAccountName: default
    # Глобальный Pod template для всех Tasks
    podTemplate:
      nodeSelector:
        disktype: ssd
      tolerations:
      - key: "general"
        operator: "Equal"
        value: "pipeline"
        effect: "NoSchedule"
  # Переопределения для конкретных Tasks
  taskRunSpecs:
    - pipelineTaskName: build
      podTemplate:
        nodeSelector:
          disktype: nvme
          gpu: available
        tolerations:
        - key: "build-only"
          operator: "Equal"
          value: "true"
          effect: "NoSchedule"
    - pipelineTaskName: deploy
      podTemplate:
        nodeSelector:
          environment: production
        tolerations:
        - key: "deploy-only"
          operator: "Equal"
          value: "true"
          effect: "NoSchedule"
  params:
    - name: image-name
      value: my-registry/my-app:latest

#Workspaces

Workspaces позволяют обмениваться данными между Tasks в Pipeline.

#Сценарии использования

• Совместное использование исходного кода между задачами сборки и тестирования
• Передача артефактов сборки задачам деплоя
• Совместное использование конфигурационных файлов между несколькими задачами
• Сохранение данных между выполнениями Pipeline

#Принципы

Workspaces:

• Объявляются в Pipeline и привязываются в PipelineRun
• Могут использовать различные типы томов (PVC, ConfigMap, Secret и др.)
• Обеспечивают обмен данными без прямых зависимостей
• Поддерживают разные режимы доступа (ReadOnly, ReadWrite)

#Пример конфигурации

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: build-test-with-workspace
spec:
  pipelineRef:
    name: build-test-pipeline
  workspaces:
    - name: source-code
      volumeClaimTemplate:
        spec:
          accessModes:
            - ReadWriteOnce
          resources:
            requests:
              storage: 1Gi
    - name: cache
      persistentVolumeClaim:
        claimName: build-cache-pvc

#Управление статусом PipelineRun

#Мониторинг статуса выполнения

Поле status PipelineRun предоставляет подробную информацию о ходе выполнения:

status:
  completionTime: "2023-05-04T02:19:14Z"
  conditions:
    - lastTransitionTime: "2023-05-04T02:19:14Z"
      message: "Tasks Completed: 4, Skipped: 0"
      reason: Succeeded
      status: "True"
      type: Succeeded
  startTime: "2023-05-04T02:00:11Z"
  childReferences:
  - name: build-deploy-app-run-build
    pipelineTaskName: build
    kind: TaskRun

#Отмена PipelineRun

Для отмены выполняющегося PipelineRun обновите поле spec.status:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: build-deploy-app-run
spec:
  # [...other fields...]
  status: "Cancelled"

Это немедленно завершит все запущенные TaskRuns и не запустит ожидающие или finally задачи.

#Корректная остановка PipelineRun

Для корректной остановки PipelineRun с выполнением finally задач:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: build-deploy-app-run
spec:
  # [...other fields...]
  status: "StoppedRunFinally"

Это завершит текущие выполняющиеся задачи, но не запустит новые, кроме finally задач.

#Ссылки

• Tekton PipelineRuns Official Documentation
• Tekton Pipelines GitHub Repository
• Kubernetes Custom Resources