Migrating from Knative Build

This doc describes a process for users who are familiar with Knative Build andBuildTemplate resources to migrate to Tekton TaskRuns and Tasks, respectively.

Tekton’s resources are heavily influenced by Knative’s Build-related resources,with some additional features that enable them to be chained together inside aPipeline, and provide additional flexibility and reusability.

Important differences

• All steps must have a name.

• BuildTemplateparametersare moved inside Task’s input.params field, and parameter placeholderstrings (e.g., ${FOO}) must be specified like $(input.parameters.FOO)(see variable substitution).

• Tasks must specifyinput.resourcesif they need to operate on a resource (e.g., source from a Git repo).BuildTemplates did not specify input resource requirements, and just assumedwhatever source was available.

• Input resources must specify a name, which is the directory within/workspace where the resource’s source will be placed. So if you specify agit-type resource named foo, the source will be cloned into/workspace/foo – make sure to either set workingDir: /workspace/foo inthe Task’s steps, or at least be aware that source will not be cloned into/workspace as was the case with Knative Builds. See Controlling whereresources aremountedfor more information.

• TaskRuns which specify a PipelineResource to satisfy a Task’s input.resourcescan do so either by referencing an existing PipelineResource resource in itsresourceRef, or by fully specifying the resource in itsresourceSpec.

• Because of how steps are serialized without relying on init containers, stepsshould specify a command instead ofentrypointand args. If the image’s entrypoint isn’t defined, Tekton will attemptto determine the image’s entrypoint. This field can be a list of strings,so instead of specifying args: ['foo', 'bar'] and assuming the image’sentrypoint (e.g., /bin/entrypoint) as before, you can specifycommand: ['/bin/entrypoint', 'foo, bar'].

Example

BuildTemplate -> Task

Given this example BuildTemplate which runs go test*:

apiVersion: build.knative.dev/v1alpha1
kind: BuildTemplate
metadata:
  name: go-test
spec:
  parameters:
  - name: TARGET
    description: The Go target to test
    default: ./...
  steps:
  - image: golang
    args: ['go', 'test', '${TARGET}']

*This is just an example BuildTemplate, for illustration purposes only.

This is the equivalent Task:

apiVersion: tekton.dev/v1beta1
kind: Task
metadata:
  name: go-test
spec:
  params:
  - name: TARGET
    description: The Go target to test
    default: ./...
  # The Task must operate on some source, e.g., in a Git repo.
  resources:
    inputs:
    - name: source
      type: git
  steps:
  - name: go-test  # <-- the step must specify a name.
    image: golang
    workingDir: /workspace/source  # <-- set workingdir
    command: ['go', 'test', '$(params.TARGET)']  # <-- specify params.TARGET

Build -> TaskRun

Given this example Build which instantiates and runs the aboveBuildTemplate:

apiVersion: build.knative.dev/v1alpha1
kind: Build
metadata:
  name: go-test
spec:
  source:
    git:
      url: https://github.com/my-user/my-repo
      revision: master
  template:
    name: go-test
    arguments:
    - name: TARGET
      value: ./path/to/test/...

This is the equivalent TaskRun:

apiVersion: tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: example-run
spec:
  taskRef:
    name: go-test
  params:
  - name: TARGET
    value: ./path/to/test/...
  resources:
    inputs:
    - name: source
      resourceSpec:
        type: git
        params:
        - name: url
          value: https://github.com/my-user/my-repo