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 are remaining in alpha while the other resource kinds are promoted to beta.

At some point this feature in its current form could be redesigned, replaced, deprecated or removed entirely, and until this has been resolved, we encourage people to use Tasks instead of PipelineResources when they can.

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.

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: master
          - name: url
            value: https://github.com/tektoncd/pipeline
    outputs:
    - name: baked-image
      resourceSpec:
      - type: image
        params:
        - name: url
          value: gcr.io/foo/bar