imjasonh/migrating-knative-build.md

## migrating-knative-build.md

      
    Raw
  

              migrating-knative-build.md
            
          
    Migrating from Knative Build

This doc describes a process for users who are familiar with Knative Build and
BuildTemplate 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 a
Pipeline, and provide additional flexibility and reusability.


Knative
Tekton


Build
TaskRun


BuildTemplate
Task


ClusterBuildTemplate
ClusterTask


Important differences


All steps must have a name. Step statuses are not reported in a
TaskRun's status in the same order they're specified in the spec, so the
name is used to associate the status with the step.


BuildTemplaate parameters are moved inside Task's input.params field, and
parameter placeholder strings (e.g., ${FOO}) must be specified like
${input.parameters.FOO}.


Tasks must specify input.resources if they need to operate on a resource
(e.g., source from a Git repo). BuildTemplates did not specify input
resource requirements, and just assumed whatever 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 a
git-type resource named foo, the source will be cloned into
/workspace/foo -- make sure to either set workingdir: /workspace/foo in
the 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 where
resources are
mounted
for more information.

TaskRuns which specify a PipelineResource to satisfy a Task's
input.resources can do so either by referencing an existing
PipelineResource resource in its resourceRef, or by fully specifying the
resource in its resourceSpec.


Because of how steps are serialized without relying on init containers, steps
must specify a command. This field can be a list of strings, so instead of
specifying args: ['foo', 'bar'] and assuming the image's entrypoint (e.g.,
/bin/entrypoint) as before, you can specify command: ['/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/v1alpha1
kind: Task
metadata:
  name: go-test
spec:
  inputs:
    params:
    - name: TARGET
      description: The Go target to test
      default: ./...

    # The Task must operate on some source, e.g., in a Git repo.
    resources:
    - name: source
      type: git

  steps:
  - name: go-test  # <-- the step must specify a name.
    image: golang
    workingdir: /workspace/source  # <-- set workingdir
    command: ['go', 'test', '${inputs.params.TARGET}']  # <-- specify inputs.params.TARGET

Build -> TaskRun

Given this example Build which instantiates and runs the above
BuildTemplate:
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/v1alpha1
kind: TaskRun
metadata:
  name: example-run
spec:
  taskRef:
    name: go-test
  inputs:
    params:
    - name: TARGET
      value: ./path/to/test/...
    resources:
    - name: source
      resourceSpec:
        type: git
        params:
        - name: url
          value: https://github.com/my-user/my-repo
Knative	Tekton
Build	TaskRun
BuildTemplate	Task
ClusterBuildTemplate	ClusterTask