PipelineRuns

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

为什么需要 PipelineRuns

CI/CD 工作流挑战

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

  • 工作流编排:需要按特定顺序协调多个 Task
  • 资源协调:需要跨多个 Task 管理资源
  • 数据共享:需要在工作流中的 Task 之间共享数据
  • 执行跟踪:需要跟踪整个工作流的进度
  • 错误处理:需要在 Task 和工作流两个层面处理失败
  • 可审计性:需要保留所有工作流执行的记录

Tekton 的解决方案

Tekton PipelineRuns 通过以下方式解决这些挑战:

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

优势

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

场景

PipelineRun 在多种场景中都很有用,包括:

  • 原生应用 CI/CD:构建、测试和部署原生应用
  • Infrastructure as Code:对基础设施进行 provisioning 和管理
  • 发布管理:协调复杂的发布流程
  • 定时工作流:按计划运行工作流
  • 事件驱动工作流:响应外部事件触发工作流

约束和限制

  • 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 限制

原则

Timeout 具有以下特性:

  • 在 PipelineRun 规范中使用 timeouts 字段指定(旧的 timeout 字段已弃用)
  • 应用于整个 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:所有非 finally Task 的最大持续时间
  • finally:所有 finally Task 的最大持续时间

配置示例

示例 1:标准 timeout 配置

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: build-deploy-with-timeout
spec:
  pipelineRef:
    name: build-deploy-app
  timeouts:
    pipeline: "1h"    # 总 pipeline timeout
    tasks: "45m"      # 所有常规 Task 的 timeout
    finally: "15m"    # finally Task 的 timeout
  params:
    - name: image-name
      value: my-registry/my-app:latest

示例 2:tasks 和 finally 不设置 timeout(要求 pipeline timeout 为 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"        # 不设置常规 Task 的 timeout
    finally: "0"      # 不设置 finally Task 的 timeout
  params:
    - name: image-name
      value: my-registry/my-app:latest

注意:

  • 示例 1 满足约束:pipeline (1h) >= tasks (45m) + finally (15m)
  • 示例 2 展示了如何通过将所有值设置为 "0" 来禁用 timeout

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 Template

Pod Template 允许指定一个 Pod template,作为执行每个 Task 的 Pod 配置基础。

TIP

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

使用场景

  • 为特定硬件需求设置 node selector
  • 为专用节点配置 toleration
  • 指定 security context 以增强安全性
  • 在 Pod 层级设置资源限制和请求
  • 配置 affinity 规则以提高资源利用率
  • 为 Pod 添加自定义 annotation 或 label

原则

Pod Template:

  • 除非被 taskRunSpecs 覆盖,否则会应用于 PipelineRun 中的所有 Task
  • 遵循 Kubernetes Pod template 规范
  • 可被 taskRunSpecs 中针对 Task 的配置覆盖
  • 让 PipelineRun 中所有 Task 的 Pod 配置保持一致
  • 支持所有标准 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
    # PipelineRun 中所有 Task 的全局 Pod template
    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 template、computeResources 和 Metadata。

使用场景

  • 为不同 Task 应用不同的 ServiceAccount,以实现细粒度访问控制
  • 为特定 Task 设置专用 Pod template,以满足不同的资源或安全要求
  • 为特定 Task 配置 metadata,以便更好地组织和跟踪
  • 覆盖全局 PipelineRun 配置,针对特定 Task 进行调整
  • 为 Pipeline 的不同阶段应用不同的 compute resources 或 node selector

原则

TaskRunSpecs:

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

配置字段

每个 TaskRunSpec 支持以下字段:

  • pipelineTaskName:要应用配置的 Pipeline task 名称
  • serviceAccountName:该特定 Task 使用的 ServiceAccount
  • podTemplate:该 Task 专用的 Pod template 配置
  • computeResources:该 Task 的 compute resource 要求(requests 和 limits),会覆盖 Task spec 中定义的默认值
  • metadata:TaskRun 的 metadata 配置

配置示例

示例 1:带 ServiceAccount 和 Pod Template 的基础 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:带 Metadata 配置的 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 可以覆盖在 PipelineRun 层级设置的全局 Pod template:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: override-global-template
spec:
  pipelineRef:
    name: build-deploy-app
  taskRunTemplate:
    serviceAccountName: default
    # 所有 Task 的全局 Pod template
    podTemplate:
      nodeSelector:
        disktype: ssd
      tolerations:
      - key: "general"
        operator: "Equal"
        value: "pipeline"
        effect: "NoSchedule"
  # 针对 Task 的覆盖配置
  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/memory 配额, 并覆盖 Task spec 中定义的任何默认值:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: pipeline-run-with-compute-resources
spec:
  pipelineRef:
    name: build-test-deploy
  taskRunSpecs:
    - pipelineTaskName: build
      # 为资源密集型 build 步骤分配更多资源
      computeResources:
        requests:
          cpu: "1"
          memory: "2Gi"
        limits:
          cpu: "2"
          memory: "4Gi"
    - pipelineTaskName: test
      # 为 test 步骤使用更轻量的资源
      computeResources:
        requests:
          cpu: "500m"
          memory: "512Mi"
        limits:
          cpu: "1"
          memory: "1Gi"
NOTE

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

Workspaces

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

使用场景

  • 在 build 和 test Task 之间共享源代码
  • 将构建产物传递给部署 Task
  • 在多个 Task 之间共享配置文件
  • 在 Pipeline 执行之间持久化数据

原则

Workspaces:

  • 在 Pipeline 中声明,并在 PipelineRun 中绑定
  • 可由多种 volume 类型支持(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 除外。

参考资料