From a9f5544aa561bd4836d46d8c3e77d10d5f5d3a16 Mon Sep 17 00:00:00 2001 From: Jason Hall Date: Thu, 3 Jun 2021 09:58:32 -0400 Subject: [PATCH] SHIP-0003: Tekton Custom Task --- ships/0003-tekton-custom-task.md | 121 +++++++++++++++++++++++++++++++ 1 file changed, 121 insertions(+) create mode 100644 ships/0003-tekton-custom-task.md diff --git a/ships/0003-tekton-custom-task.md b/ships/0003-tekton-custom-task.md new file mode 100644 index 0000000..b4df724 --- /dev/null +++ b/ships/0003-tekton-custom-task.md @@ -0,0 +1,121 @@ + + +--- +title: tekton-custom-task +authors: + - "@imjasonh" +reviewers: + - "@adambkaplan" + - "@sbose78" + - "@qu1queee" +approvers: + - "@adambkaplan" + - "@sbose78" + - "@qu1queee" +creation-date: 2021-06-03 +last-updated: 2021-06-03 +status: provisional +--- + +# Tekton Custom Task + +## Release Signoff Checklist + +- [ ] Enhancement is `implementable` +- [x] Design details are appropriately documented from clear requirements +- [x] Test plan is defined +- [x] Graduation criteria for dev preview, tech preview, GA +- [ ] User-facing documentation is created in [docs](/docs/) + +## Open Questions [optional] + +TBD + +## Summary + +Implement a Tekton Custom Task controller that watches for Tekton `Run` objects that reference a Shipwright `Build` resource by name. +When such a `Run` object is created, create a `BuildRun` referencing the referenced `Build`, and as the `BuildRun` progresses, update the `Run` status accordingly. + +## Motivation + +Implementing a Custom Task controller has two main benefits: + +1. This will allow us to integrate Shipwright with Tekton Triggers in a future change. + The Custom Task is necessary here because Tekton Triggers is only designed to create Tekton resources, and not arbitrary non-Tekton resources such as a `BuildRun`. +1. This will allow users to integrate Shipwright Builds in their Tekton Pipelines. + This would enable them to, for example, run unit tests before calling Shipwright to build a container image, or to test, scan or deploy an image produced by Shipwright. + +Because Shipwright already necessarily requires Tekton to be installed, this change should not incur any additional dependencies on users or operators. + +### Goals + +A Shipwright installation should be able to watch and react to Tekton `Run` objects by creating `BuildRun`s, and update the `Run` status with the `BuildRun`'s status. + +This behavior should be documented and demoable, and tested to guard against regressions. + +### Non-Goals + +Shipwright should not require or recommend any particular integration with a Tekton pipeline, only take advantage of features provided by Tekton to integrate with a pipeline. + +## Proposal + +### Implementation Notes + +Add a reconciler to the Shipwright Build controller that watches for Tekton `Run` objects that reference a Shipwright `Build`. + +The reconciler should handle timeouts and cancellations. +In the future, when BuildRuns support parameterization, the reconciler should also support `Run` parameters by passing them through. + +The core implementation of this controller has been prototyped in https://github.com/imjasonh/build-task, using a reconciler based on knative/pkg. +If we want to integrate this into Shipwright's existing controller, we might want to port that to controller-runtime to remain consistent with Shipwright's existing implementation. + +Tekton added support for `Run`s in [version 0.19.0](https://github.com/tektoncd/pipeline/releases/tag/v0.19.0), released December 2020. +As of the latest Tekton release, running Custom Tasks in a Pipeline requires opting in to the alpha feature gate, but Shipwright can enable the controller regardless. + +### Test Plan + +In addition to unit tests, add end-to-end tests that cover this behavior: + +1. create a `Run` directly and check that a `BuildRun` is created; check that the `Run` status is updated when the `BuildRun` executes. +1. create a `PipelineRun` that references such a `Run`, and check that the `PipelineRun` progresses and creates a `BuildRun`. + +### Release Criteria + +**Note:** *Section not required until targeted at a release.* + +#### Upgrade Strategy [if necessary] + +Currently, Tekton Custom Task `Run` resources have the `v1alpha1` API version. +In the future, we should expect these to graduate to `v1beta1` and eventually `v1`. + +The shape of the `Run` resource is fairly small and not expected to grow in breaking ways. + +### Risks and Mitigations + +Integrating with Custom Tasks requires the Shipwright controller to have permission to view and update the status of _all `Run` resources_, even those that don't reference Shipwright `Build`s. +This is due to limitations in Kubernetes RBAC -- there's no way to request access to only `Run` objects that reference `Build`s. +As a result, a bug or exploit of the Shipwright controller could lead to unexpected or malicious behavior in the user's cluster. + +## Drawbacks + +This integration presents a somewhat convoluted semi-circular dependency between Shipwright and Tekton. +A Tekton `PipelineRun` executes a `Run` that tells Shipwright to create a `BuildRun`, which executes by creating a Tekton `TaskRun` under the hood. + +Because Custom Tasks are alpha, most Tekton pipeline visualization UIs don't have good support for showing the status of `Run`s, and this will extend to Shipwright builds in a Tekton pipeline execution. +By having more stable Custom Task implementations in the wild, this should encourage better support in these UIs. + +## Alternatives + +We could try to encourage Tekton Triggers to support creating arbitrary external types; they've been (rightfully, I think) resistant to this in the past. + +## Infrastructure Needed [optional] + +None. + +## Implementation History + +TBD