#PipelineRuns

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

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

#Проблемы CI/CD workflow

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

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

#Решение Tekton

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

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

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

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

#Сценарии

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

• Application CI/CD: сборка, тестирование и развёртывание applications
• Infrastructure as Code: подготовка и управление infrastructure
• Управление релизами: координация сложных процессов release
• Плановые workflow: запуск workflow по расписанию
• Event-Driven workflow: запуск workflow в ответ на внешние события

#Ограничения

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

#Принципы

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

Когда создаётся PipelineRun:

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

#Состояние PipelineRun

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

1. Общее состояние (Running, Succeeded, Failed и т. д.)
2. Время начала и завершения
3. Состояния отдельных TaskRun
4. Результаты Task
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.

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

• Предотвращение бесконечного потребления ресурсов долгоживущими Pipelines
• Обеспечение завершения CI/CD workflow в разумные сроки
• Обработка зависших или deadlocked Tasks
• Настройка разных ограничений timeout для разных фаз выполнения pipeline

#Принципы

Timeouts:

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

#Поля Timeout

• pipeline: максимальная длительность всего PipelineRun
• tasks: максимальная длительность всех non-finally tasks
• finally: максимальная длительность всех finally tasks

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

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

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

Пример 2: без timeout для tasks и finally (требует, чтобы timeout pipeline был 0)

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

Примечание:

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

#ServiceAccount

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

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

• Предоставление учётных данных для доступа к private container registries
• Аутентификация у cloud providers
• Авторизация доступа к Kubernetes resources
• Предоставление учётных данных для Git operations

#Принципы

ServiceAccounts:

• могут быть заданы на уровне 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 template, который будет использоваться как основа для конфигурации Pod, выполняющего каждую Task.

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

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

#Принципы

Pod Templates:

• применяются ко всем Tasks в PipelineRun, если не переопределены через taskRunSpecs
• соответствуют спецификациям Kubernetes Pod template
• могут быть переопределены Task-specific конфигурациями в taskRunSpecs
• обеспечивают единообразную конфигурацию Pod для всех Tasks в PipelineRun
• поддерживают все стандартные поля Kubernetes Pod template

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

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: build-deploy-with-pod-template
spec:
  pipelineRef:
    name: build-deploy-app
  taskRunTemplate:
    serviceAccountName: default
    # Global Pod template for all Tasks in the 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, computeResources и Metadata для каждой task.

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

• Применение разных ServiceAccounts к разным Tasks для тонкой настройки контроля доступа
• Задание Task-specific Pod templates для разных требований к ресурсам или безопасности
• Конфигурирование Task-specific metadata для лучшей организации и отслеживания
• Переопределение глобальных настроек PipelineRun для конкретных Tasks
• Применение разных compute resources или node selectors к разным этапам Pipeline

#Принципы

TaskRunSpecs:

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

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

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

• pipelineTaskName: имя Pipeline task, к которой применяется конфигурация
• serviceAccountName: ServiceAccount, используемый для этой конкретной Task
• podTemplate: конфигурация Pod template, специфичная для этой Task
• computeResources: требования к вычислительным ресурсам (requests и limits) для этой Task, переопределяющие значения по умолчанию, определённые в spec Task
• metadata: конфигурация 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 с конфигурацией Metadata

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
    # Global Pod template for all Tasks
    podTemplate:
      nodeSelector:
        disktype: ssd
      tolerations:
      - key: "general"
        operator: "Equal"
        value: "pipeline"
        effect: "NoSchedule"
  # Task-specific overrides
  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

Пример 5: переопределение computeResources для конкретных Tasks

Используйте taskRunSpecs[].computeResources, чтобы назначить разные CPU/memory quotas для отдельных Tasks, переопределяя любые значения по умолчанию, определённые в spec Task:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: pipeline-run-with-compute-resources
spec:
  pipelineRef:
    name: build-test-deploy
  taskRunSpecs:
    - pipelineTaskName: build
      # Allocate more resources for the resource-intensive build step
      computeResources:
        requests:
          cpu: "1"
          memory: "2Gi"
        limits:
          cpu: "2"
          memory: "4Gi"
    - pipelineTaskName: test
      # Use lighter resources for the test step
      computeResources:
        requests:
          cpu: "500m"
          memory: "512Mi"
        limits:
          cpu: "1"
          memory: "1Gi"

#Workspaces

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

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

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

#Принципы

Workspaces:

• объявляются в Pipeline и привязываются в PipelineRun
• могут использовать различные типы volumes (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 и не запускает ожидающие Tasks или finally Tasks.

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

Чтобы корректно остановить PipelineRun и позволить выполниться finally Tasks:

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

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

#Ссылки

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