Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?

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
@Justin2997

This comment has been minimized.

Copy link

Justin2997 commented Apr 25, 2019

Hi, this that mean that Knative Build will be deprecated in the near future? Thanks !

@evankanderson

This comment has been minimized.

Copy link

evankanderson commented Apr 26, 2019

I don't think Knative Build will be deprecated until there is a clear criteria approved at a TOC meeting for "equivalent implementation" which would be recommended as a replacement.

At a minimum, I expect that this would include some degree of implementation and upgrade stability, and might also include requirements on minimum/maximum kubernetes dependencies and management. (For example, if we knew that Knative was going to be helm-installed, we might require that any replacement fit in well with a helm install. This is a hypothetical, not concrete, requirement.)

@RichieEscarez

This comment has been minimized.

Copy link

RichieEscarez commented May 8, 2019

Hi Jason,

Sorry, I've been very disconnected lately as my focus was solely getting the website up but my reaction is the same - "do we all need to migrate and does that mean the Build component is going away".

To help new users or others who have not kept up with all the changes happening in Build (like myself), can you please add more about "When" and "Why" someone would want to (or need to maybe?), migrate to Tekton. Here are some questions or points that I think would help users:

  • Why migrate to Tekton, what benefit does it provide?
  • Are there any limitations (one way or the other)?
  • Does the migration path apply to only specific to certain versions of the Build component?
  • Why and/or when you should stay on and keep using Knative Build.

Regarding the flow of the docs, I think that the list of important differences would do better if each bullet (or set of bullets) is/are a part of the corresponding task? For example, convert the combination of a bullet in the "important differences" list with the corresponding example, into a specific task. This would tie that important info to a necessary change, and provide context at each step.

For example, you could combine the following bullet and example:

"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."
+
"BuildTemplate -> Task" example
=>
The task might be: "Converting a Knative BuildTemplate into a Tekton Task"

Last suggestions is about adding more cross links between the related topics? For example, a statement about what Tekton is, why to migrate to it, and a link to this topic from the Knative build overview topic (if and when you start that review for the Knative docs).

@duglin

This comment has been minimized.

Copy link

duglin commented May 15, 2019

2nd bullet: s/BuildTemplaate/BuildTemplate/

In the final TaskRun, are resource names unique for all resources or just within the scope of its resourceSpec.type ?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.