Skip to content

Instantly share code, notes, and snippets.

@imjasonh

imjasonh/0002-custom-tasks.md

Last active October 28, 2021 05:44
Show Gist options
  • Star 1 You must be signed in to star a gist
  • Fork 1 You must be signed in to fork a gist
  • Save imjasonh/b2520dd81b8b08c16ef1eb6b2fdfb07b to your computer and use it in GitHub Desktop.
Save imjasonh/b2520dd81b8b08c16ef1eb6b2fdfb07b to your computer and use it in GitHub Desktop.
Download ZIP
Raw
0002-custom-tasks.md

TEP-0002: Enable Custom Tasks

aka non-Pod Tasks, "duck-typed" Tasks 🦆

Summary

Enable integrators to define new "custom" Task types as CRDs, which can be run by creating a new CustomTaskRun object (a CRD type which Tekton will define and own). Custom Task authors must also implement a reconciling controller which watches for creations of CustomTaskRun objects which reference their type, and which eventually updates its status to signal task completion.

To achieve this, Tekton will define a new type, CustomTaskRun, first in v1alpha1, with the intention of iterating and, if there's support, bringing this functionality to v1beta1 and eventually v1. Tekton will also implement support for this new type in the PipelineRun CRD controller, as well as document the contract for integrating with this new type, and providing examples and Go helper methods that integrators can consume if their controllers are implemented in Go.

Motivation

Allow integrators to implement new functionality that doesn't directly map to Tekton's current idea of a Task and TaskRun (i.e., a collection of containers running on a compute node).

Some examples include (non-exhaustive):

  • wait for a period of time without having to schedule a container that just sleeps, wasting compute resources
  • wait for an external event to occur, e.g., a manual approval
  • execute some operation outside of the cluster (e.g., a cloud service, a macOS/mobile build farm) and wait for its execution to complete
  • execute another (sub-)Pipeline and wait for it to complete
  • enable matrix parameter expression -- e.g., succinctly express a Task that executes with args A,B,C (defined at config-time)
  • enable looping execution of sub-Tasks -- e.g., express that a Task should be repeatedly run until some state is reached (signalled at run-time)
  • ...and in general, support a model where integrators can implement their own execution types

Goals

  1. Allow non-Pod Task implementations to be built and integrated into "core" Tekton Pipelines.

  2. Implement a handful of commonly-requested features (e.g., wait, approval) as example Custom Tasks in tektoncd/experimental, to demonstrate the contract and act as a working example for future integrators.

  3. Provide Go packages to help integrators perform common operations required by the Custom Task implementation contract.

Non-Goals

  1. Provide any Custom Task implementations as "official" or "first-party" integrations. Some may be added in a future change, but for now the goal is just to support any third-party integrations, and let the user install them themselves, or let distributors include them in their distribution if they prefer to.

  2. As with (1), we don't intend to support any Custom Tasks with any special behavior in the tkn CLI or the Tekton Dashboard project. As with (1), this may be considered in a future change.

  3. Provide any helper libraries for non-Go reconcilers. If sufficient demand for non-Go languages emerges, we may consider helper libraries for them, but at this time we consider this unlikely.

Requirements

  • Add a new CRD type, CustomTaskRun, which will be instantiated when a Pipeline is run that contains taskRefs which have an apiVersion that is not tekton.dev/* -- taskRefs that reference Tasks and ClusterTasks will be unaffected.
  • Implement and document the Custom Task integration contract (i.e., integrators should update the CustomTaskRun's .status.conditions to signal completion)
  • Implement and document optional cancellation and timeout behavior of CustomTaskRuns.
  • Provide a package of helper functions.

Proposal

User Stories (optional)

Story 1

Story 2

Notes/Constraints/Caveats (optional)

Risks and Mitigations

Design Details

Test Plan

In order to test correct handling of Custom Tasks in the PipelineRun controller, simple e2e tests could install a simple Wait type and controller (only used for testing), and assert that a Pipeline that references that Wait type runs component Tasks with some approriate period of time between them.

Other future experimental types and controllers (in tektoncd/experimental) should be accompanied by unit tests and e2e tests along the same lines.

Drawbacks

This requires integrators to write CRD types and controllers in order to implement their Custom Task types. This is not a trivial requirement; CRD support means understanding CRD semantics (reconciliation, watching, validation, conversion, etc.); custom controllers require installation, monitoring, possibly master-election, etc.

Alternatives

  1. Provide first-party support for things like long waits, approvals, Pipelines-in-Pipelines, in an ad-hoc tightly-coupled manner.

  2. As in previous iterations of this design (documented more fully in the Google Doc), require implementors to define and support two CRD types, instead of one.

Infrastructure Needed (optional)

None.

Upgrade & Migration Strategy (optional)

TBD. At this time, the proposal only covers adding new a type and documentating the contract. If changes to the types or contract are deemed necessary in the future, in response to feedback, then an upgrade/migration strategy might be necessary.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment