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 时:
- 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 限制
原则
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 配置基础。
使用场景
- 为特定硬件需求设置 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 除外。
参考资料