From 246948aa80623db3cbaaa97bbd74126177586a99 Mon Sep 17 00:00:00 2001 From: Jason Hall Date: Tue, 11 Jun 2019 11:00:27 -0400 Subject: [PATCH 1/2] Add first draft of Knative Build migration guide This covers basic differences between Knative resources and the equivalents in Tekton This does not yet cover deployment of Knative apps using Tekton. --- docs/migrating-from-knative-build.md | 143 +++++++++++++++++++++++++++ 1 file changed, 143 insertions(+) create mode 100644 docs/migrating-from-knative-build.md diff --git a/docs/migrating-from-knative-build.md b/docs/migrating-from-knative-build.md new file mode 100644 index 00000000000..b7681a8ea64 --- /dev/null +++ b/docs/migrating-from-knative-build.md @@ -0,0 +1,143 @@ +# Migrating from [Knative Build](https://github.com/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](https://github.com/tektoncd/pipeline/blob/master/docs/tasks.md#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 +``` From 73ef5584419de16d5197b93f59985f46b7ce0db6 Mon Sep 17 00:00:00 2001 From: Jason Hall Date: Thu, 11 Jul 2019 16:48:23 -0400 Subject: [PATCH 2/2] Address review comments --- docs/migrating-from-knative-build.md | 39 ++++++++++++++++------------ 1 file changed, 22 insertions(+), 17 deletions(-) diff --git a/docs/migrating-from-knative-build.md b/docs/migrating-from-knative-build.md index b7681a8ea64..c37867959aa 100644 --- a/docs/migrating-from-knative-build.md +++ b/docs/migrating-from-knative-build.md @@ -15,17 +15,18 @@ Pipeline, and provide additional flexibility and reusability. ## 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. +* All `steps` must have a `name`. -* BuildTemplaate `parameters` are moved inside Task's `input.params` field, and - parameter placeholder strings (e.g., `${FOO}`) must be specified like - `${input.parameters.FOO}`. +* BuildTemplate + [`parameters`](https://github.com/tektoncd/pipeline/blob/master/docs/tasks.md#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. +* Tasks must specify + [`input.resources`](https://github.com/tektoncd/pipeline/blob/master/docs/tasks.md#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 @@ -36,16 +37,20 @@ Pipeline, and provide additional flexibility and reusability. resources are mounted](https://github.com/tektoncd/pipeline/blob/master/docs/tasks.md#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`. + +* 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`](https://github.com/tektoncd/pipeline/blob/master/docs/taskruns.md#providing-resources). * 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']` + should specify a `command` instead of + [`entrypoint`](https://github.com/tektoncd/pipeline/blob/master/docs/container-contract.md#entrypoint) + and `args`. If the image's `entrypoint` isn't defined, Tekton will attempt + to determine the image's entrypoint. 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