Skip to content

Latest commit

 

History

History
393 lines (321 loc) · 16.2 KB

0114-custom-tasks-beta.md

File metadata and controls

393 lines (321 loc) · 16.2 KB
status title creation-date last-updated authors see-also
implemented
Custom Tasks Beta
2022-07-12
2022-12-12
@jerop
@XinruZhang
TEP-0002
TEP-0061
TEP-0069
TEP-0071
TEP-0096
TEP-0105
TEP-0121

TEP-0114: Custom Tasks Beta

Summary

The aim of this TEP is to promote Custom Tasks, which are used to extensibility in Tekton Pipelines, from alpha to beta.

Motivation

TEP-0002: Custom Tasks introduced Custom Tasks which allow users to extend the functionality of Tekton Pipelines. Users implement controllers that watch for Runs that implement their types of Custom Tasks.

Runs is in v1alpha1. Runs and PipelineResources are the only remaining types in v1alpha1 - see TEP-0105 tep-0105 for more details on v1alpha1.

Use of Custom Tasks in Pipelines is also gated behind feature flags: either enable-custom-tasks needs to be set to "true" or enable-api-fields needs to be set to "alpha".

Custom Tasks have been available since v0.19.0 of Tekton Pipelines released in December 2020. Many Custom Tasks have been created to extend Tekton Pipelines functionality, including but not limited to:

  • Task Loops: Runs a Task in a loop with varying Parameter values.
  • Pipeline Loops: Runs a Pipeline in a loop with varying Parameter values.
  • Common Expression Language: Provides Common Expression Language support in Tekton Pipelines.
  • Wait: Waits a given amount of time, specified by a Parameter named "duration", before succeeding.
  • Approvals: Pauses the execution of PipelineRuns and waits for manual approvals.
  • Pipelines in Pipelines: Defines and executes a Pipeline in a Pipeline.
  • Task Group: Groups Tasks together as a Task.
  • Pipeline in a Pod: Runs Pipeline in a Pod.

As discussed in TEP-0096, Custom Tasks are critical for extensibility in Tekton Pipelines, as such promoting Custom Tasks to beta is a blocker for releasing v1 of Tekton Pipelines.

Proposal

In this section, we scope the promotion of Custom Tasks to beta. The work in required must be done, while the work in optional may be done.

Required

The work scoped here are blockers for promotion.

API Changes

v1alpha1 to v1beta1 + Run to CustomRun

Move v1alpha1.Run to v1beta1.CustomRun.

The migration from v1alpha1 to v1beta1 provides an opportunity to rename Runs to CustomRuns. Reasons for the name change as discussed in tektoncd/pipelines#5005 and API WG meeting include.:

  • PipelineRuns execute Pipelines and TaskRuns execute Tasks, so it is consistent for CustomRuns to execute CustomTasks.
  • The current name Runs may suggest that it's an interface that PipelineRuns and TaskRuns implement.
References and Specifications

Clarify references and specifications.

Today, embedded specs are in Run.Spec.Spec. We propose aligning the embedded specs with the rest of the API such that it's CustomRun.Spec.CustomSpec.

# before
apiVersion: tekton.dev/v1alpha1
kind: Run
metadata:
  name: run-with-spec
spec:
  spec:
    apiVersion: example.dev/v1alpha1
    kind: Example
    spec:
      field1: value1
      field2: value2
# after
apiVersion: tekton.dev/v1beta1
kind: CustomRun
metadata:
  name: customrun-with-spec
spec:
  customSpec:
    apiVersion: example.dev/v1beta1
    kind: Example
    spec:
      field1: value1
      field2: value2

Today, references are in Run.Spec.Ref. We propose aligning the references with the rest of the API such that it's CustomRun.Spec.CustomRef.

# before
apiVersion: tekton.dev/v1alpha1
kind: Run
metadata:
  name: run-with-reference
spec:
  ref:
    apiVersion: example.dev/v1alpha1
    kind: Example
    name: my-example
---
# after
apiVersion: tekton.dev/v1beta1
kind: CustomRun
metadata:
  name: customrun-with-reference
spec:
  customRef:
    apiVersion: example.dev/v1beta1
    kind: Example
    name: my-customtask

Note that the API for TaskRuns and PipelineRuns is:

apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: pipelinerun-with-ref
spec:
  pipelineRef:
    name: my-pipeline
---
apiVersion: tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: taskrun-with-reference
spec:
  taskRef:
    name: my-task
---
apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: pipelinerun-with-spec
spec:
  pipelineSpec:
    params:
      - name: param1
    tasks:
      - name: my-task
---
apiVersion: tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: taskrun-with-spec
spec:
  taskSpec:
    params:
      - name: param1
    steps:
      - name: my-step

Simplifying all the references to use ref and embedded specifications to use spec is out of scope for this TEP. That work is tracked in tektoncd/pipeline#5138.

Remove Pod Template

Remove podTemplate field that assumes and implies that all Custom Tasks create Pods.

Note that the goal of Custom Tasks, as defined in TEP-0002, is to support non-Pod Task implementations. If a specific Custom Task implementation creates Pods, that Custom Task can have a Pod template field in its own specification.

Feature Gates
New Feature Flag custom-task-version

Support both v1alpha1.Run and v1beta1.CustomRun for four long term support (LTS) releases. So that custom task implementors and end users are able to fully test and migrate Custom Task from v1alpha1 to v1beta1.

Create a new feature flag custom-task-version to allow end users to choose which version of custom task to be created out of a PipelineTask. We set the default feature flag value to v1alpha1 in the first LTS release, and switch to v1beta1 in the following three LTS releases.

Say we start to support v1beta1.CustomRun in LTS release X, and set default value of custom-task-version to v1alpha1. In the LTS release X+1, we switch the default value to v1beta1. In the LTS release X+4, we remove the feature flag, and only support v1beta1.

Existing Feature Gates

Remove guarding of Custom Tasks behind enable-custom-tasks and enable-api-fields feature gates.

When TEP-0096: Pipelines V1 API is implemented to add V1 API, Custom Tasks will be gated behind feature gate enable-api-fields being set to "beta" - this is out of scope for this TEP (in scope for TEP-0096).

Cancellation

The Custom Task is responsible for implementing cancellation to support PipelineRun level timeouts and cancellation. If the Custom Task implementor does not support cancellation via .spec.status, Pipeline can not timeout within the specified interval/duration and can not be cancelled as expected upon request.

Pipeline Controller sets the spec.Status and spec.StatusMessage to signal CustomRuns about the Cancellation, while CustomRun controller updates its status.conditions as following once noticed the change on spec.Status.

Pipeline Signal CustomRun.Spec.Status CustomRun.Spec.StatusMessage CustomRun.Status.Conditions
Cancelling
Gracefully Cancelling		 RunCancelled CustomRun cancelled as the PipelineRun it belongs to has been cancelled. Type: Succeeded
Status:False
Reason:CustomRunCancelled
Pipeline timeouts RunCancelled CustomRun cancelled as the PipelineRun it belongs to has timed out. Type: Succeeded
Status:False
Reason:CustomRunCancelled

Documentation

Expand the documentation for Custom Tasks and Runs.

Testing

Improve the test coverage for Custom Tasks and Runs.

Writing end-to-end tests for Custom Tasks and Runs has been difficult because we don't have Custom Tasks controllers in Tekton Pipelines. We propose adding a simple Custom Task controller in Tekton Pipelines that's used only for tests. This could be a version of the Wait Custom Task or CEL Custom Task. We'd import this Custom Task into Tekton Pipelines to avoid a dependency on the Tekton Experimental. This Custom Task will not be packaged with the Tekton Pipelines release - it's only intended for testing in Tekton Pipelines.

Optional

The work scoped here are nice-to-have ahead of the promotion - they are not blockers.

Authoring Custom Tasks

Improve the user experience of authoring Custom Tasks and their controllers.

Implementing Custom Tasks and their controllers can be difficult for new users of the feature. We can improve the authoring experience through:

  • providing SDK or boilerplate for getting started - this enhancement is proposed in TEP-0071.
  • providing a guide for authoring Custom Tasks and their controllers, including security recommendations such as scoping permissions.

Sharing Custom Tasks

Make it easy to share and discover Custom Tasks.

Discovering Custom Tasks is difficult because some exist in the experimental repository in Tekton and others are contributors' own repositories - this makes it hard to share and reuse Custom Tasks. The Tekton Hub is the platform for users to discover and share Tekton resources. We propose that the Hub supports Custom Tasks.

Custom Tasks in Tekton Hub

This is an overview of a potential solution for supporting Custom Tasks in the Hub and its CLI. Further details will be discussed in these issues - tektoncd/community#667 and tektoncd/cli#1623 - and in its own TEP if needed.

To support Custom Tasks in the Tekton Hub, we will add customtasks.yaml that will be used to list Custom Tasks to be surfaced in the Hub, in the same way that config.yaml is used for Catalogs with Tasks and Pipelines.

Each entry in customtasks.yaml will specify a Custom Task surfaced in the Hub, for example:

custom-tasks:
  
  - name: approval
    org: automatiko-io
    type: community
    provider: github
    url: https://github.com/automatiko-io/automatiko-approval-task
    revision: main
    categories: 
      - deployment
      - automation
  
  - name: task-group
    org: openshift-pipelines
    type: community
    provider: github
    url: github.com/openshift-pipelines/tekton-task-group
    revision: main
    categories:
      - storage 
      
  - name: cel
    org: tektoncd
    type: official
    provider: github
    url: github.com/tektoncd/cel
    revision: main
    tags:
      - language

We will require that the listed Custom Tasks must have README.md documenting its installation and functionality, which will be surfaced in the Hub. The Hub CLI will support Custom Tasks that are surfaced in the Hub:

$ tkn hub install custom task approval
$ tkn hub install custom-task cel

The Hub should fetch and surface the releases of the Custom Tasks, e.g TaskGroup has release v0.1.1:

$ tkn hub install custom-task task-group --version v0.1.1

For further details, see tektoncd/community#523, tektoncd/community#667, and tektoncd/cli#1623.

References