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 |
-
All
steps
must have aname
. Step statuses are not reported in a TaskRun'sstatus
in the same order they're specified in thespec
, so thename
is used to associate thestatus
with the step. -
BuildTemplaate
parameters
are moved inside Task'sinput.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 agit
-type resource namedfoo
, the source will be cloned into/workspace/foo
-- make sure to either setworkingdir: /workspace/foo
in the Task'ssteps
, 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 itsresourceRef
, or by fully specifying the resource in itsresourceSpec
.
- TaskRuns which specify a PipelineResource to satisfy a Task's
-
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 specifyingargs: ['foo', 'bar']
and assuming the image's entrypoint (e.g.,/bin/entrypoint
) as before, you can specifycommand: ['/bin/entrypoint', 'foo, bar']
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
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
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:
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 TektonTask
"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).