PipelineRuns

PipelineRun 是一种用于实例化 Pipeline 以执行的 Kubernetes Custom Resource。PipelineRun 负责执行 Pipeline 中定义的 Task 并管理其生命周期,为端到端 CI/CD 工作流的运行提供支持。

为什么需要 PipelineRun

CI/CD 工作流挑战

在 CI/CD 系统中,工作流执行涉及多个挑战:

  • 工作流编排:需要按特定顺序协调多个 Task
  • 资源协调:需要管理多个 Task 之间的资源
  • 数据共享:需要在工作流中的 Task 之间共享数据
  • 执行跟踪:需要跟踪整个工作流的进度
  • 错误处理:需要处理 Task 级别和工作流级别的故障
  • 可审计性:需要维护所有工作流执行的记录

Tekton 的解决方案

Tekton PipelineRun 通过以下方式应对这些挑战:

  • 工作流实例:每个 PipelineRun 表示一次使用特定输入执行 Pipeline 的过程
  • 编排:PipelineRun 根据依赖关系管理 Task 的执行顺序
  • 资源绑定:PipelineRun 将实际资源绑定到 Pipeline 的要求
  • 状态跟踪:PipelineRun 跟踪每个 Task 的执行状态
  • 结果传递:PipelineRun 支持在 Task 之间共享结果
  • Kubernetes 集成:PipelineRun 利用 Kubernetes 进行资源管理和调度

优势

  • 隔离性:每个 PipelineRun 独立执行,因此可以并行执行同一 Pipeline
  • 可追溯性:PipelineRun 提供详细的执行历史记录和日志
  • 灵活性:PipelineRun 可以覆盖 Pipeline 参数和 workspace 绑定
  • 可复用性:通过不同的 PipelineRun,可以使用不同的输入执行同一 Pipeline
  • 集成能力:可以通过 Kubernetes API 由各种系统触发 PipelineRun
  • 可观测性:可以通过 Kubernetes 工具监控 PipelineRun 状态和日志

场景

PipelineRun 适用于各种场景,包括:

  • 原生应用 CI/CD:构建、测试和部署应用
  • 基础设施即代码:预配和管理基础设施
  • 发布管理:协调复杂的发布流程
  • 计划工作流:按计划运行工作流
  • 事件驱动的工作流:响应外部事件触发工作流

约束和限制

  • PipelineRun 在单个 Kubernetes 集群内执行
  • PipelineRun 启动后,无法修改其参数
  • PipelineRun 对失败 Task 的重试能力有限
  • PipelineRun 的执行时间受 Kubernetes Pod 超时限制
  • PipelineRun 开始执行后无法暂停(使用 "finally" Task 时除外)

原则

PipelineRun 执行模型

创建 PipelineRun 时:

  1. Tekton 验证 PipelineRun 规范
  2. Tekton 为 Pipeline 中的每个 Task 创建 TaskRun
  3. TaskRun 根据其依赖关系执行
  4. 收集 Task 的结果,并可供后续 Task 使用
  5. 每个 TaskRun 完成后更新 PipelineRun 状态
  6. 所有其他 Task 完成或失败后执行 "Finally" Task
  7. 所有 TaskRun 完成后,PipelineRun 完成

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

包含内嵌 Pipeline 定义的 PipelineRun

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 工作流在合理的时间范围内完成
  • 处理挂起或死锁的 Task
  • 为 Pipeline 执行的不同阶段设置不同的超时限制

原则

Timeout:

  • 在 PipelineRun 规范中使用 timeouts 字段指定(旧版 timeout 字段已弃用)
  • 应用于整个 PipelineRun 执行过程或特定部分(tasks、finally)
  • 对于 timeouts.pipeline 和 timeouts.tasks,从 PipelineRun(status.startTime)开始时计时;对于 timeouts.finally,从 finally Task(status.finallyStartTime)开始时计时
  • 超时后会导致 PipelineRun 失败
  • 必须遵循以下约束:timeouts.pipeline >= timeouts.tasks + timeouts.finally
  • 重要:如果任何子字段设置为 "0",则该部分不设超时。若要将 timeouts.tasks 或 timeouts.finally 设置为 "0",还必须将 timeouts.pipeline 设置为 "0"

Timeout 字段

  • pipeline:整个 PipelineRun 的最长持续时间
  • tasks:所有非 finally Task 的最长持续时间
  • finally:所有 finally Task 的最长持续时间

配置示例

示例 1:标准超时配置

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: build-deploy-with-timeout
spec:
  pipelineRef:
    name: build-deploy-app
  timeouts:
    pipeline: "1h"    # Total pipeline timeout
    tasks: "45m"      # Timeout for all regular tasks
    finally: "15m"    # Timeout for finally tasks
  params:
    - name: image-name
      value: my-registry/my-app:latest

示例 2:Task 和 finally 不设超时(要求 pipeline 超时设置为 0)

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: build-deploy-no-timeout
spec:
  pipelineRef:
    name: build-deploy-app
  timeouts:
    pipeline: "0"     # No overall timeout
    tasks: "0"        # No timeout for regular tasks
    finally: "0"      # No timeout for finally tasks
  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 级别为所有 Task 指定
  • 可以使用 taskRunSpecs 映射到特定 Task
  • 通过 Kubernetes Secret 提供凭据
  • 支持安全访问外部资源

配置示例

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 模板

Pod 模板用于指定一个 Pod 模板,作为配置执行每个 Task 的 Pod 的基础。

TIP

有关 Pod 模板的更多信息,请参阅 Pod 模板。

使用场景

  • 为特定硬件要求设置节点选择器
  • 为专用节点配置容忍度
  • 指定安全上下文以增强安全性
  • 在 Pod 级别设置资源限制和请求
  • 配置亲和性规则以更好地利用资源
  • 向 Pod 添加自定义注释或标签

原则

Pod 模板:

  • 应用于 PipelineRun 中的所有 Task,除非被 taskRunSpecs 覆盖
  • 遵循 Kubernetes Pod 模板规范
  • 可以由 taskRunSpecs 中针对 Task 的配置覆盖
  • 支持在 PipelineRun 的所有 Task 之间保持一致的 Pod 配置
  • 支持所有标准 Kubernetes Pod 模板字段

配置示例

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 允许通过指定 PipelineTaskRunSpec 列表来自定义 PipelineRun 中单个 TaskRun 的配置,从而为每个 Task 设置 ServiceAccountName、Pod 模板、computeResources 和 Metadata。

使用场景

  • 为不同 Task 应用不同的 ServiceAccount,以实现精细化访问控制
  • 设置特定于 Task 的 Pod 模板,以满足不同的资源或安全要求
  • 配置特定于 Task 的元数据,以便更好地组织和跟踪
  • 覆盖特定 Task 的全局 PipelineRun 配置
  • 为 Pipeline 的不同阶段应用不同的计算资源或节点选择器

原则

TaskRunSpecs:

  • 覆盖为整个 Pipeline 设置的 Pod 模板
  • 支持对 Task 执行环境进行精细控制
  • 可用于满足特定的安全、资源或调度要求
  • 支持为 Pipeline 的不同阶段使用不同配置
  • 支持所有标准 Kubernetes Pod 模板规范
  • 可以与全局 PipelineRun 配置结合使用

配置字段

每个 TaskRunSpec 支持以下字段:

  • pipelineTaskName:要应用该配置的 Pipeline Task 名称
  • serviceAccountName:此特定 Task 要使用的 ServiceAccount
  • podTemplate:特定于此 Task 的 Pod 模板配置
  • computeResources:此 Task 的计算资源要求(请求和限制),覆盖 Task 规范中定义的默认值
  • metadata:TaskRun 的元数据配置

配置示例

示例 1:包含 ServiceAccount 和 Pod 模板的基本 TaskRunSpecs

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:包含高级 Pod 配置的 TaskRunSpecs

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 模板

TaskRunSpecs 可以覆盖在 PipelineRun 级别设置的全局 Pod 模板:

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:覆盖特定 Task 的 computeResources

使用 taskRunSpecs[].computeResources 为单个 Task 分配不同的 CPU/内存配额,覆盖 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"
NOTE

taskRunSpecs 中的 computeResources 是 Beta 功能,需要在 Tekton 功能标志 ConfigMap 中设置 enable-api-fields: beta(或 alpha)。在平台的默认安装中,enable-api-fields 已设置为 beta,因此该功能开箱即用 — 只有在手动将该标志设置为 stable 时,才需要调整该标志。

Workspaces

Workspaces 允许在 Pipeline 中的 Task 之间共享数据。

使用场景

  • 在构建和测试 Task 之间共享源代码
  • 将构建产物传递给部署 Task
  • 在多个 Task 之间共享配置文件
  • 在 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 状态管理

监控执行状态

PipelineRun 的 status 字段提供了执行进度的详细信息:

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"

这会立即终止所有正在运行的 TaskRun,并且不会执行待处理的 Task 或 finally Task。

优雅地停止 PipelineRun

要优雅地停止 PipelineRun,同时允许执行 finally Task:

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

这会完成当前正在运行的 Task,但不会启动新的 Task,finally Task 除外。

参考资料