企业官网建设流程全解析

• 云原生
• CI/CD
• DevOps
• 后端

导读：本文以 Tekton Pipeline 的 API 参考文档为核心，系统梳理云原生流水线中Pipeline、Task、PipelineRun、TaskRun、Run/CustomRun、ResolutionRequest、StepAction与VerificationPolicy等核心资源的类型定义、字段语义与版本演进。你将掌握tekton.dev与resolution.tekton.dev两个 API 组共 6 个包的资源结构、参数/结果/工作区/超时等关键字段的默认值与校验规则，并能基于仓库中的源码与 CRD 文件准确编写与阅读 Pipeline 清单。

一、API 包总览：六个版本化包的职责划分

Tekton Pipeline 的 API 被划分为两个 API 组（Group），并在各自组内按稳定性提供多个版本。文档中给出的完整包清单如下：

从源码结构看，该仓库在 pkg/apis/pipeline/v1、pkg/apis/pipeline/v1beta1、pkg/apis/pipeline/v1alpha1、pkg/apis/resolution/v1beta1 与 pkg/apis/resolution/v1alpha1 目录中分别维护各版本的 Go 类型定义，并通过 pkg/apis/pipeline/register.go 与 pkg/apis/resolution/register.go 完成 Scheme 注册。CRD 清单位于 config/300-crds 目录（如 300-pipeline.yaml、300-task.yaml、300-resolutionrequest.yaml）。

关键版本策略：

• tekton.dev/v1是稳定版本，仓库中的Pipeline、Task、PipelineRun、TaskRun定义标注了+kubebuilder:storageversion，即作为存储版本使用；
• tekton.dev/v1beta1中的同名资源已标记 Deprecated（如Deprecated: Please use v1.Pipeline instead.），保留仅为兼容旧客户端；
• tekton.dev/v1alpha1中的PipelineResource已废弃（Deprecated: Unused, preserved only for backwards compatibility），Run已被 v1beta1 的CustomRun取代；
• resolution.tekton.dev/v1beta1是 ResolutionRequest 的存储版本（见 pkg/apis/resolution/v1beta1/resolution_request_types.go 中+kubebuilder:storageversion标注）。

二、ResolutionRequest：远程资源解析请求的类型定义

ResolutionRequest是一个用于“请求某个 Tekton 资源（如 pipeline.yaml）内容”的对象，其文档定义同时存在于resolution.tekton.dev/v1alpha1与resolution.tekton.dev/v1beta1两个版本中。

2.1 顶层对象

apiVersion: resolution.tekton.dev/v1beta1 # 或 v1alpha1 kind: ResolutionRequest metadata: # 复用 Kubernetes ObjectMeta name: my-resolution namespace: my-namespace spec: # ResolutionRequestSpec，可选 params: [] url: "" # 仅 v1beta1 提供，alpha 稳定性级别 status: # ResolutionRequestStatus，可选 data: "" refSource: {}

字段说明：

2.2 ResolutionRequestSpec：两版本的关键差异

• v1alpha1：仅一个字段params，类型为object (keys:string, values:string)，即“运行时属性”，传给 resolver 以确定如何解析被请求的资源，例如仓库 URL、commit SHA、文件路径、认证类型等。
• v1beta1：params的类型升级为[Param](#param)数组（复用 tekton 的Param结构，见 pkg/apis/pipeline/v1/param_types.go），并新增url字段——运行时传给 resolver 的 URL。文档明确标注该字段目前处于ALPHA 稳定性级别，受 alpha API 兼容性策略约束（对应仓库 api_compatibility_policy.md）。

源码佐证：在 pkg/apis/resolution/v1beta1/resolution_request_types.go 中，ResolutionRequestSpec.Params的类型正是[]pipelinev1.Param，并新增了URL string字段。

2.3 ResolutionRequestStatus 与 StatusFields

ResolutionRequestStatus内嵌了ResolutionRequestStatusFields，其字段包括：

其中RefSource的字段为：

• uri：构建定义来源的标识，如https://github.com/tektoncd/catalog；
• digest：URI 指定内容的密码学摘要集合，如{"sha1": "f99d13e554ffcb696dee719fa85b695cb5b0f428"}；
• entryPoint：构建的入口点，通常是构建定义文件的路径或文件内目标标签，如task/git-clone/0.10/git-clone.yaml。

实用提示：ResolutionRequest 与resolver机制配合使用。在PipelineRef/TaskRef中可以通过ResolverRef指定resolver: git等名称并传参，从而从 Git 仓库、OCI Bundle、Hub 等远程位置拉取 Pipeline 或 Task 定义。详见仓库文档 resolution.md、git-resolver.md 与 tekton-bundle-contracts.md。

三、tekton.dev/v1：稳定版核心资源

3.1 Pipeline 与 PipelineSpec

Pipeline描述要执行的一组 Tasks，以及上游 Task 输出如何作为下游 Task 输入。顶层字段为apiVersion: tekton.dev/v1、kind: Pipeline、metadata、spec。

PipelineSpec（见 pkg/apis/pipeline/v1/pipeline_types.go）字段：

PipelineResult由name、type（取值string/array/object，默认string，其中 array 与 object 为 alpha 特性）、description与value（从底层步骤取值表达式）组成。

PipelineTask是 Pipeline 的执行单元，关键字段包括：

• name：任务在 Pipeline 上下文中的名称，与from、runAfter一起决定执行顺序；
• taskRef/taskSpec：引用已有 Task 或内联定义 Task（taskSpec可通过disable-inline-spec特性开关禁用）；
• when：WhenExpressions 守卫表达式，全部求值为 true 才执行；
• retries：Task 失败（ConditionSucceeded 为 False）时的重试次数；
• runAfter：强制执行顺序的任务名列表；
• params/matrix：传入参数与基于数组参数扇出任务的 Matrix 声明；
• workspaces：Pipeline 工作区到 Task 工作区的映射；
• timeout：TaskRun 超时，默认 1 小时，格式遵循 Go 的ParseDuration（如1h30m）；
• pipelineRef/pipelineSpec：alpha 字段，需将enable-api-fields特性开关设为alpha，用于将嵌套 Pipeline 作为子 PipelineRun 执行；
• onError：continue（PipelineTask 失败后继续执行 DAG 其余部分）或stopAndFail（失败即停止并失败整个 PipelineRun）。

3.2 PipelineRun 与 PipelineRunSpec

PipelineRun代表一次 Pipeline 执行：它向 Pipeline 提供参数等输入，并捕获 Task 执行的操作属性（如 service account、tolerations）。创建 PipelineRun 会为引用的 Pipeline 中的 Tasks 创建 TaskRuns。

PipelineRunSpec字段：

TimeoutFields 粒度超时（注意约束Timeouts.pipeline >= Timeouts.tasks + Timeouts.finally）：

PipelineRunStatus包含observedGeneration、conditions、annotations、startTime、completionTime、results（PipelineRunResult 数组）、pipelineSpec（实例化运行时使用的确切 spec）、skippedTasks、childReferences（子 TaskRun/Run 的名称、PipelineTask 名与 API 版本/类型）、finallyStartTime（所有非 finally 任务完成、仅执行 finally 任务的时间点）、provenance（软件工件构建方式的关键认证元数据，供 Tekton Chains 采集）与spanContext（链路追踪 span 上下文）。

其中ChildStatusReference用于指向 PipelineRun 内各 TaskRun 与 Run 的状态，字段为name、displayName、pipelineTaskName与whenExpressions；SkippedTask记录因 when 表达式求值为 false 而跳过的任务及其SkippingReason。

SkippingReason 完整取值表（用于诊断任务为何被跳过）：

3.3 Task、TaskSpec 与 Step

Task表示按顺序执行的一组步骤（steps），运行时由提供输入参数与资源的 TaskRun 触发。

TaskSpec字段：

Step 字段（v1 稳定版）：name、displayName、image、command（entrypoint 数组，不经过 shell 执行）、args、workingDir、envFrom、env、computeResources、volumeMounts、volumeDevices、imagePullPolicy（Always/Never/IfNotPresent，:latest默认 Always，否则 IfNotPresent）、securityContext、script（可执行文件内容，非空时不能同时有 command，args 会传给脚本）、timeout（Step 超时，默认永不超时）、workspaces（alpha 字段，声明独占访问的 Task 工作区）、onError（continue/stopAndFail）、stdoutConfig/stderrConfig（StepOutputConfig，可将 stdout/stderr 复制到容器本地文件系统的path）、ref（引用已有 StepAction）、params、results（StepResult 数组，内联 Step 时可写入$(step.results.resultName.path)；引用 StepAction 时不能使用，改用 StepAction 声明的结果）、when（StepWhenExpressions）。

Sidecar 与 Step 的差异：Sidecar 拥有与 Step 几乎相同的数据结构，但没有超时能力，另含ports、livenessProbe、readinessProbe、startupProbe、lifecycle、stdin、stdinOnce、tty等容器级字段。

ParamSpec / ParamType / ParamValue：参数支持三种类型string（默认）、array、object；ParamSpec支持default（未提供输入值时的默认值）与enum（允许值的枚举，设置后执行输入校验，未设置则不校验）；properties用于支撑 key-value 对象的 JSON Schema 属性定义。ParamValue在 JSON 反序列化时可同时接受单个字符串或字符串数组。

3.4 TaskRun 与 TaskRunSpec

TaskRun代表单次 Task 执行，是 Task 中步骤实际运行的方式。

TaskRunSpec字段：debug（TaskRunDebug 断点配置：breakpoints.onFailure可在步骤失败时暂停、beforeSteps指定暂停前的步骤列表）、params、serviceAccountName、taskRef/taskSpec（二者至多指定一个）、status（取消 TaskRun）、statusMessage、retries（失败重试次数）、timeout（单次重试尝试超时，默认 1 小时）、podTemplate、workspaces、stepSpecs/sidecarSpecs（alpha 特性，按名称覆盖步骤/边车的 computeResources）、computeResources、managedBy（不可变）。

TaskRunStatus的字段包括：podName（执行步骤的 Pod 名）、startTime、completionTime、steps（StepState 数组，报告各 step 容器的 waiting/running/terminated 状态与 results、provenance、inputs/outputs 工件）、retriesStatus（重试历史，用于留存失败记录）、results（TaskRunResult 数组）、artifacts（输入输出工件集合，inputs/outputs各为 Artifact 数组，Artifact 含name、values（digest 与 uri）与buildOutput标记）、sidecars、taskSpec（实例化时反引用后的确切 spec）、provenance、spanContext。

3.5 工作区（Workspace）体系

• WorkspaceDeclaration（Task 声明）：name、description、mountPath（覆盖挂载目录）、readOnly（默认 false 可写）、optional（默认 false 即必需）；
• PipelineWorkspaceDeclaration（Pipeline 声明）：name、description、optional；
• WorkspaceBinding（运行期绑定）：name、subPath、volumeClaimTemplate（控制器为每个 PipelineRun 创建唯一 PVC）、persistentVolumeClaim、emptyDir、configMap、secret、projected、csi（后两者二选一约束适用于 PVC 与 emptyDir）；
• WorkspacePipelineTaskBinding（Pipeline 到 Task 的映射）：name（Task 声明名）、workspace（Pipeline 声明名）、subPath；
• WorkspaceUsage（Step/Sidecar 独占访问）：name、mountPath（覆盖 Task 声明中的 mountPath）。

四、tekton.dev/v1beta1：过渡版本与 CustomRun

tekton.dev/v1beta1包中的Pipeline、PipelineRun、Task、TaskRun均标注Deprecated: Please use v1.* instead.，字段与 v1 基本一致，但保留了以下 v1 中已移除或改名的历史字段：

• PipelineRef.bundle/TaskRef.bundle：Tekton Bundle URL 引用，已废弃，改用ResolverRef+ bundles resolver，字段保留仅为 Go 客户端向后兼容，不再使用；
• PipelineRunSpec.resources/timeout：resources为废弃的 PipelineResource 绑定；timeout已废弃，改用timeouts.pipeline；
• PipelineRunStatus.taskRuns/runs（map 形式）：自 v0.45.0 起不再填充，改用childReferences；
• TaskRunSpec.stepOverrides/sidecarOverrides：对应 v1 的stepSpecs/sidecarSpecs；
• TaskSpec.resources（TaskResources）：废弃的 PipelineResource 声明；
• Provenance.configSource：废弃，改用refSource。

CustomRun 是 v1beta1 包新增的核心资源，用于执行自定义 Task（Custom Task）：

CustomRunSpec字段：customRef（TaskRef）、customSpec（EmbeddedCustomRunSpec 内嵌自定义任务定义）、params、status（取消）、statusMessage、retries（向自定义任务传播重试计数）、serviceAccountName、timeout（自定义任务超时）、workspaces。

CustomRunStatus状态消息常量包括：CustomRun cancelled as the PipelineRun it belongs to has been cancelled.与CustomRun cancelled as the PipelineRun it belongs to has timed out.。

历史对应：v1alpha1 中的Run表示单次自定义任务执行，其RunSpec字段（ref、spec、params、status、statusMessage、retries、serviceAccountName、podTemplate、timeout、workspaces）与 CustomRun 高度相似，CustomRun 是其演进版本。迁移指南见 migrating-v1alpha1.Run-to-v1beta1.CustomRun.md。

五、tekton.dev/v1alpha1：遗留资源与安全/复用能力

该包包含 4 种资源类型：

5.1 PipelineResource（废弃）

PipelineResource描述 Task 的输入或输出资源，文档明确标注Deprecated: Unused, preserved only for backwards compatibility，无控制器为其工作。PipelineResourceSpec字段为description、type、params（ResourceParam）、secrets（SecretParam）。

5.2 Run（废弃，被 CustomRun 取代）

如前所述，Run用于执行自定义任务，RunSpecStatus仅定义RunCancelled一个取值。

5.3 StepAction：步骤复用单元

StepAction表示 Step 的可执行组件，Step 只能从集群内或通过远程解析引用它。StepActionSpec字段：description、image、command、args、env、script（非空时不能有 command，args 传给脚本）、workingDir、params（ParamSpecs，除非声明默认值否则需在 Steps 中提供）、results（StepResult 数组）、securityContext（StepAction 中的设置优先于 Task 中的值）、volumeMounts。

在Step.ref（Ref 结构）中可以引用 StepAction：Ref字段为name与ResolverRef（支持从 Git 等远程位置引用）。StepAction的 v1beta1 版本存在于tekton.dev/v1beta1包中。实践示例见 examples/v1/taskruns/stepaction.yaml 与 examples/v1/taskruns/stepaction-params.yaml。

5.4 VerificationPolicy：资源签名验证策略

VerificationPolicy定义验证 Tekton 资源的规则，可将“资源来源”映射到“公钥列表”，在验证资源时使用对应的公钥。

VerificationPolicySpec字段：

ResourcePattern.pattern的文档示例：GitHub 资源https://github.com/tektoncd/catalog.git、https://github.com/tektoncd/*；Bundle 资源gcr.io/tekton-releases/catalog/upstream/git-clone、gcr.io/tekton-releases/catalog/upstream/*；Hub 资源https://artifacthub.io/*。

Authority包含name与key（KeyRef）；KeyRef支持secretRef（引用存有密钥的 Secret）、data（内联公钥）、kms（KMS URL，目前尚未支持）与hashAlgorithm（默认sha256，可选sha224/sha256/sha384/sha512）。

深入阅读：该机制与 pkg/trustedresources 包（含 verifier 与 verify 逻辑）及 docs/trusted-resources.md 配合使用；CRD 定义见 config/300-crds/300-verificationpolicy.yaml，密钥测试数据位于 test/trustedresources-keys。

六、tekton.dev/unversioned：非版本化的 Volumes

该包仅包含Volumes类型，其底层类型为 Kubernetes 的Volume（API v1），被EmbeddedTask与TaskSpec引用。它完整继承了 Kubernetes 的卷类型体系，包括hostPath、emptyDir、secret、configMap、persistentVolumeClaim、nfs、projected、csi、ephemeral、image等。

值得关注的是较新的卷类型语义：

• ephemeral：生命周期与 Pod 绑定，适用于仅 Pod 运行期间需要的卷、需要快照恢复/容量跟踪、由 storage class 指定驱动并支持动态供应的场景；Pod 同时可以使用临时卷与持久卷；
• image：将 OCI 对象（容器镜像或工件）拉取并挂载到 kubelet 主机，按Always/Never/IfNotPresent拉取策略解析，只读（ro）且不可执行（noexec）挂载；1.33 之前不支持 subPath 挂载。

七、跨版本通用类型速查

以下类型在多个版本包中重复出现，字段语义保持一致：

• Param / ParamSpec / ParamValue / Params / ParamType / ParamSpecs：参数体系，类型为string/array/object；
• ResultsType：区分string、array、object结果类型（注意与用于判定 RunResult 是否来自 task result 的 ResultType 不同）；
• WhenExpression / WhenExpressions：字段input、operator、values（非空数组）、cel（CEL 表达式，可选），所有表达式需为 true 才执行守卫任务；
• Provenance / RefSource / ConfigSource：远程构建定义的来源元数据，v1beta1 中ConfigSource已废弃，统一为RefSource（uri、digest、entryPoint），Provenance.featureFlags记录运行期使用的特性开关；
• TimeoutFields：Pipeline 级pipeline/tasks/finally三档超时；
• OnErrorType（Step 级）：stopAndFail/continue；
• PipelineTaskOnErrorType（PipelineTask 级）：stopAndFail/continue；
• Artifact / ArtifactValue / Artifacts：工件输入输出记录，含digest（按 Algorithm 映射）与uri；
• RetriesStatus：重试历史，内联TaskRunStatusFields且不再重复记录时间。

八、如何在仓库中印证与使用这些 API

1. 类型定义源头：各版本的 Go 类型集中在 pkg/apis/pipeline/v1、pkg/apis/pipeline/v1beta1、pkg/apis/pipeline/v1alpha1，例如Pipeline/PipelineSpec/PipelineTask见 pkg/apis/pipeline/v1/pipeline_types.go，ResolutionRequest见 pkg/apis/resolution/v1beta1/resolution_request_types.go；
2. CRD 声明：config/300-crds 下的 300-*.yaml 是各资源在集群中的最终结构声明（OpenAPI v3 schema）；
3. 可运行示例：examples/v1/pipelineruns 与 examples/v1/taskruns 提供了大量实战清单，覆盖 params、results、workspaces、when 表达式、matrix、stepaction、sidecar、超时覆盖等全部文档字段的用法；
4. 行为校验：各类型对应的*_validation.go与*_test.go（如 pkg/apis/pipeline/v1/pipeline_validation_test.go）印证了文档中 Validation 列的约束（如Timeouts.pipeline >= tasks + finally、values非空、taskRef与taskSpec互斥等）；
5. 运行与查看：通过kubectl apply提交上述 CR 清单，用kubectl get/kubectl describe观察status中的 conditions、results、skippedTasks、childReferences 等字段。

结语

Tekton Pipeline 通过tekton.dev与resolution.tekton.dev两组 API、多个版本化的包，把“流水线定义（Pipeline/Task）”“运行实例（PipelineRun/TaskRun/Run/CustomRun）”“远程解析（ResolutionRequest/ResolverRef）”“复用单元（StepAction）”与“安全信任（VerificationPolicy）”完整地纳入了 Kubernetes 声明式体系。理解每个包的职责、稳定级别与字段语义，是编写可长期维护的 CI/CD 清单、排查运行状态以及评估版本迁移影响的前提。建议新资源一律使用tekton.dev/v1与resolution.tekton.dev/v1beta1，遗留字段仅用于兼容旧客户端。

• 云原生
• CI/CD
• DevOps
• 后端