Migrating From Tekton v1alpha1 to Tekton v1beta1

This document describes the differences between v1alpha1 Tekton entities and their v1beta1 counterparts. It also describes how to replace the supported types of PipelineResources with Tasks from the Tekton Catalog of equivalent functionality.

Changes to fields

In Tekton v1beta1, the following fields have been changed:

Old field New field
spec.inputs.params spec.params
spec.inputs Removed from Tasks
spec.outputs Removed from Tasks
spec.inputs.resources spec.resources.inputs
spec.outputs.resources spec.resources.outputs

Changes to input parameters

In Tekton v1beta1, input parameters have been moved from spec.inputs.params to spec.params.

For example, consider the following v1alpha1 parameters:

# 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

The above parameters are now represented as follows in 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

Replacing PipelineResources with Tasks

PipelineResources remained in alpha while the other resource kinds were promoted to beta. Since then, PipelineResources have been deprecated. We encourage users to use Tasks and other replacement features instead of PipelineResources. Read more about the deprecation in TEP-0074.

More on the reasoning and what’s left to do in Why aren’t PipelineResources in Beta?.

To ease migration away from PipelineResources some types have an equivalent Task in the Catalog. To use these replacement Tasks you will need to combine them with your existing Tasks via a Pipeline.

For example, if you were using this Task which was fetching from git and building with Kaniko:

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

To do the same thing with the git catalog Task and the kaniko Task you will need to combine them in a Pipeline.

For example this Pipeline uses the Kaniko and git catalog Tasks:

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
  # If you want you can add a Task that uses the IMAGE_DIGEST from the kaniko task
  # via $(tasks.build-image.results.IMAGE_DIGEST) - this was a feature we hadn't been
  # able to fully deliver with the Image PipelineResource!

Note that the image PipelineResource is gone in this example (replaced with a result), and also that now the Task doesn’t need to know anything about where the files come from that it builds from.

Replacing a git resource

You can replace a git resource with the git-clone Catalog Task.

Replacing a pullrequest resource

You can replace a pullrequest resource with the pullrequest Catalog Task.

Replacing a gcs resource

You can replace a gcs resource with the gcs Catalog Task.

Replacing an image resource

Since the image resource is simply a way to share the digest of a built image with subsequent Tasks in your Pipeline, you can use Task results to achieve equivalent functionality.

For examples of replacing an image resource, see the following Catalog Tasks:

Replacing a cluster resource

You can replace a cluster resource with the kubeconfig-creator Catalog Task.

Replacing a cloudEvent resource

You can replace a cloudEvent resource with the CloudEvent Catalog Task.

Changes to PipelineResources

In Tekton v1beta1, PipelineResources have been moved from spec.input.resources and spec.output.resources to spec.resources.inputs and spec.resources.outputs, respectively.

For example, consider the following v1alpha1 definition:

# 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

The above definition becomes the following in 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