企业官网建设流程全解析

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

本文是一份面向 Tekton Pipelines 使用者的实战迁移指南，系统梳理从tekton.dev/v1alpha1升级到tekton.dev/v1beta1时涉及的所有字段变更、输入参数位置调整，以及已被移除的PipelineResources的完整替代方案。读完本文，你将能够对照仓库中的 CRD 定义与源码实现，把存量Task、TaskRun、Pipeline清单逐项改写成v1beta1语法，并学会用 CatalogTask与TaskResults 替换git、pullrequest、gcs、image、cluster等各类PipelineResource，完成平滑迁移。

迁移背景：v1alpha1 与 v1beta1 的关系

Tekton Pipelines 将Task、TaskRun、Pipeline、PipelineRun等核心 CRD 从v1alpha1提升到了稳定的v1beta1，API 路径也随之从tekton.dev/v1alpha1变为tekton.dev/v1beta1。v1beta1带来了更规范、更统一的字段组织方式，并为后续向v1演进铺平了道路。

需要特别注意的是：PipelineResources没有随其他 CRD 一起进入 beta，其支持级别始终停留在 Alpha，并且后来被正式弃用、最终移除。仓库中的 docs/pipelineresources.md 明确指出："PipelineResourcesremained in alpha while the other resource kinds were promoted to beta. Since then,PipelineResourceshave been removed." 因此在从v1alpha1迁移到v1beta1时，除了调整字段位置，更核心的工作是把PipelineResources替换为功能等价的Task组合。

字段变更总览

在 Tektonv1beta1中，以下字段发生了变更或移除：

从上表可以看出，v1beta1的字段组织原则是去扁平化、语义归位：参数直接属于spec.params，资源统一收敛到spec.resources下并区分inputs/outputs。

输入参数迁移：从spec.inputs.params到spec.params

在 Tektonv1beta1中，输入参数已从spec.inputs.params移动到spec.params，Task与TaskRun两侧都需要同步修改。

例如，以下v1alpha1参数定义：

# Task.yaml (v1alpha1) spec: inputs: params: - name: ADDR description: Address to curl. type: string # TaskRun.yaml (v1alpha1) spec: inputs: params: - name: ADDR value: https://example.com/foo.json

在v1beta1中应改写成：

# Task.yaml (v1beta1) spec: params: - name: ADDR description: Address to curl. type: string # TaskRun.yaml (v1beta1) spec: params: - name: ADDR value: https://example.com/foo.json

从源码结构看，这一变更同样体现在类型定义上：在 pkg/apis/pipeline/v1beta1/task_types.go 中，TaskSpec直接声明了Params []Param字段（同时保留了Resources *TaskResources但标注为Deprecated，仅用于向后兼容）；而 pkg/apis/pipeline/v1beta1/pipeline_types.go 中PipelineTask的Resources *PipelineTaskResources也同样标注为 "Deprecated: Unused, preserved only for backwards compatibility"。这些注释表明v1beta1已经把参数提升为一级字段，而资源字段只是为兼容历史清单而保留的过渡形态。

迁移时的实操要点：

• Task中的params支持type（string、array等）与可选的default默认值；TaskRun中的params只需name与value。
• 在steps中引用参数时，$(params.ADDR)的引用语法在v1beta1中保持不变，无需改动 step 内的变量表达式。
• 检查Pipeline中tasks[].params的写法：v1beta1中为$(params.xxx)形式，若旧清单使用了$(inputs.params.xxx)形式，需要一并替换为$(params.xxx)。

PipelineResources 字段迁移：spec.resources.inputs与spec.resources.outputs

在 Tektonv1beta1中，PipelineResources已从spec.inputs.resources和spec.outputs.resources分别移动到spec.resources.inputs和spec.resources.outputs。

例如，考虑以下v1alpha1定义：

# Task.yaml (v1alpha1) spec: inputs: resources: - name: skaffold type: git outputs: resources: - name: baked-image type: image # TaskRun.yaml (v1alpha1) spec: inputs: resources: - name: skaffold resourceSpec: type: git params: - name: revision value: v0.32.0 - name: url value: https://github.com/GoogleContainerTools/skaffold outputs: resources: - name: baked-image resourceSpec: - type: image params: - name: url value: gcr.io/foo/bar

上述定义在v1beta1中变为：

# Task.yaml (v1beta1) spec: resources: inputs: - name: src-repo type: git outputs: - name: baked-image type: image # TaskRun.yaml (v1beta1) spec: resources: inputs: - name: src-repo resourceSpec: type: git params: - name: revision value: main - name: url value: https://github.com/tektoncd/pipeline outputs: - name: baked-image resourceSpec: - type: image params: - name: url value: gcr.io/foo/bar

关于上述示例的几点说明：

• Task一侧只需声明资源的name与type；TaskRun一侧通过resourceRef（引用已存在的PipelineResource实例）或resourceSpec（内联声明资源参数）完成绑定。
• 上述TaskRun输出示例中的resourceSpec实际应为单个 spec 对象（而非数组），历史文档写法存在笔误，实际迁移时请以仓库 config/300-crds 下的 CRD schema 为准。
• 在steps中引用资源路径或属性的变量语法保持不变，例如$(resources.inputs.src-repo.url)、$(resources.outputs.baked-image.path)。

值得注意的是，这些resources相关类型在v1beta1源码中已被系统性标记为废弃：TaskResources、TaskRunResources、PipelineTaskResources、PipelineResourceBinding等结构体均位于 pkg/apis/pipeline/v1beta1/resource_types.go，并逐一带有 "Deprecated: Unused, preserved only for backwards compatibility" 注释。这意味着v1beta1表面上还接受spec.resources写法，但官方已不推荐继续使用，最终在v1中被彻底删除。

用 Tasks 替代 PipelineResources

PipelineResources之所以被移除，其深层原因在 docs/resources.md 中有完整论述，归纳起来包括：

• 行为不透明：它们以"注入 Task Steps + 卷配置 + 控制器内类型专属代码"的混合方式实现，出错时难以定位是否与PipelineResource相关；
• 难以调试：多个资源类型会在 Task 的 Steps 之前注入额外 Steps，用户很难手动插入 Steps 检查运行前状态；
• 类型太少：仅有的六种类型远不能覆盖实际场景；
• 可扩展性与Task高度重合：可定义的 Steps、参数、结果、跨 Task 共享数据（workspaces）都是Task已经具备的能力；
• 降低 Task 复用性：Task一旦绑定具体资源类型（如git），就无法接受功能等价的gcs资源，尽管二者本质都是"从远端拉取文件到磁盘"。

结论是：与其保留一套半成品 CRD，不如直接用Task、Workspaces、Results这些 beta 级能力组合出等价功能。为此，docs/pipelineresources.md 给出了"用 CatalogTask组合替换"的完整范例。例如，一个用git资源拉取代码并用 Kaniko 构建镜像的旧式Task：

apiVersion: tekton.dev/v1alpha1 kind: Task metadata: name: build-push-kaniko spec: inputs: resources: - name: workspace type: git params: - name: pathToDockerFile description: The path to the dockerfile to build default: /workspace/workspace/Dockerfile - name: pathToContext description: The build context used by Kaniko default: /workspace/workspace outputs: resources: - name: builtImage type: image steps: - name: build-and-push image: gcr.io/kaniko-project/executor:v0.17.1 env: - name: "DOCKER_CONFIG" value: "/tekton/home/.docker/" args: - --dockerfile=$(inputs.params.pathToDockerFile) - --destination=$(outputs.resources.builtImage.url) - --context=$(inputs.params.pathToContext) - --oci-layout-path=$(inputs.resources.builtImage.path) securityContext: runAsUser: 0

迁移后，你需要把"拉代码"和"构建镜像"拆成两个独立Task，通过Pipeline与共享workspace串起来：

apiVersion: tekton.dev/v1beta1 kind: Pipeline metadata: name: kaniko-pipeline spec: params: - name: git-url - name: git-revision - name: image-name - name: path-to-image-context - name: path-to-dockerfile workspaces: - name: git-source tasks: - name: fetch-from-git taskRef: name: git-clone params: - name: url value: $(params.git-url) - name: revision value: $(params.git-revision) workspaces: - name: output workspace: git-source - name: build-image taskRef: name: kaniko params: - name: IMAGE value: $(params.image-name) - name: CONTEXT value: $(params.path-to-image-context) - name: DOCKERFILE value: $(params.path-to-dockerfile) workspaces: - name: source workspace: git-source # 如果愿意，还可以让后续 Task 通过 # $(tasks.build-image.results.IMAGE_DIGEST) 消费构建产物的摘要—— # 这是 Image PipelineResource 时代一直没能完整交付的能力！

这个例子有两点关键变化值得体会：

1. image资源消失了——镜像摘要通过Task的result传递，见下文；
2. 现在的Task完全不需要关心代码从哪里来，输入输出都通过workspace解耦，可复用性大幅提升。

各类型 PipelineResource 的替代方案

用TaskResults 替代image资源

image资源的本质，只是把"构建出的镜像摘要"在 Pipeline 的后续Task之间共享。在v1beta1中这一需求直接用TaskResults 即可实现：

• 构建类 Task（如 Kaniko）把镜像摘要写入results；
• 后续 Task 通过$(tasks.<task-name>.results.<result-name>)引用该摘要。

相关实现可在 pkg/apis/pipeline/v1beta1/result_types.go 中看到TaskResult与PipelineTaskResult的类型定义，v1beta1已把 Results 作为一等公民纳入 API。旧文档中反复强调的"$(tasks.build-image.results.IMAGE_DIGEST)是 Image PipelineResource 未能完整交付的特性"，正说明 Results 方案在功能上比旧机制更完整。

替换时需要配套的 CRD 与控制器行为

所有替换方案都依赖 Catalog 中的现成Task，以及workspaces（共享数据）、results（传递结果）等v1beta1原生能力。如果你的环境仍运行较旧的控制器版本，请先升级到支持v1beta1的 Tekton Pipelines 控制器版本，再执行上述迁移。

迁移注意事项与向前看

v1beta1 中的兼容性处理

从源码可以确认，v1beta1对历史字段做了"软兼容"：在 pkg/apis/pipeline/v1beta1/task_conversion.go 中，Task.ConvertTo在向v1转换时会通过serializeResources把废弃的resources序列化写入tekton.dev/v1beta1Resources注解，保证旧字段信息不丢失。换句话说：

• v1beta1能解析spec.resources，但该字段被标记为 Deprecated；
• 迁移到v1时这些字段会被收纳进注解，而不再作为spec的一部分。

因此建议你在迁移到v1beta1时就直接完成PipelineResources的替换，而不是把替换工作拖延到v1。

从 v1beta1 到 v1 的下一步

迁移完成v1beta1后，未来还要面对v1版本。仓库中的 docs/migrating-v1beta1-to-v1.md 列出了后续变更，其中与本文直接相关的包括：

• task.spec.resources、taskrun.spec.resources、pipeline.spec.resources、pipelinerun.spec.resources在v1中已从各 CRD 中移除；
• taskRun.status.taskResults变为taskRun.status.results，pipelineRun.status.pipelineResults变为pipelineRun.status.results；
• taskRef.bundle/pipelineRef.bundle被 Bundle Resolver 取代，ClusterTask被clusterresolver 取代。

也就是说，在v1beta1阶段完成PipelineResources的替换，是为v1铺平道路的关键一步。

延伸阅读

• docs/pipelineresources.md：PipelineResources移除声明与各 Catalog Task 替代方案详述
• docs/resources.md：PipelineResources为何停留在 Alpha 并被弃用的完整论证
• docs/migrating-v1beta1-to-v1.md：v1beta1到v1的后续迁移清单
• pkg/apis/pipeline/v1beta1/resource_types.go：v1beta1中资源相关类型的废弃标注源码
• pkg/apis/pipeline/v1beta1/task_conversion.go：v1beta1向v1转换时的资源序列化逻辑
• config/300-crds：Task、TaskRun、Pipeline、PipelineRun的 CRD 定义，迁移时以其中的 schema 为准

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