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 时:
- Tekton 验证 PipelineRun 规范
- Tekton 为 Pipeline 中的每个 Task 创建 TaskRun
- TaskRun 根据其依赖关系执行
- 收集 Task 的结果,并可供后续 Task 使用
- 每个 TaskRun 完成后更新 PipelineRun 状态
- 所有其他 Task 完成或失败后执行 "Finally" Task
- 所有 TaskRun 完成后,PipelineRun 完成
PipelineRun 状态
PipelineRun 状态提供有关执行的详细信息:
- 总体状态(Running、Succeeded、Failed 等)
- 开始时间和完成时间
- 各个 TaskRun 的状态
- Task 结果
- 失败原因(如适用)
- 用于访问日志的 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 的基础。
使用场景
- 为特定硬件要求设置节点选择器
- 为专用节点配置容忍度
- 指定安全上下文以增强安全性
- 在 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 除外。
参考资料