#PipelineRuns

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

#Зачем нужны 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 и привязки workspaces
• Повторное использование: один и тот же Pipeline можно запускать с разными входными данными через разные PipelineRuns
• Интеграция: PipelineRuns могут запускаться различными системами через Kubernetes API
• Наблюдаемость: состояние и журналы PipelineRun можно отслеживать с помощью инструментов Kubernetes

#Сценарии

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

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

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

• PipelineRuns выполняются в одном кластере Kubernetes
• После запуска параметры PipelineRun нельзя изменить
• PipelineRuns имеют ограниченные возможности повторных попыток для сбойных Tasks
• Время выполнения PipelineRun ограничено таймаутами Pod Kubernetes
• 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. Результаты 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.

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

• Предотвращение бесконечного потребления ресурсов долго выполняющимися Pipelines
• Обеспечение завершения CI/CD workflow в разумные сроки
• Обработка зависших или взаимоблокированных 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, используемый для аутентификации.

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

• Предоставление учетных данных для доступа к частным container registries
• Аутентификация у cloud providers
• Авторизация доступа к ресурсам Kubernetes
• Предоставление учетных данных для 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 для выделенных nodes
• Указание security contexts для повышения безопасности
• Задание ограничений и запросов ресурсов на уровне Pod
• Настройка правил affinity для более эффективного использования ресурсов
• Добавление пользовательских annotations или labels к Pods

#Принципы

Pod Templates:

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

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

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.

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

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

#Принципы

TaskRunSpecs:

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

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

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

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

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

• Совместное использование исходного кода между Tasks сборки и тестирования
• Передача артефактов сборки в 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
• GitHub repository Tekton Pipelines
• Пользовательские ресурсы Kubernetes