Skip to content

Commit 963aa40

Browse files
XinruZhangtekton-robot
XinruZhang
authored and
tekton-robot
committed
TEP-0114: Migration Doc for Custom Task Beta Promotion
Prior to this commit, we don't have docs for how to migrate custom task from alpha version to beta. This commits bridge the gap and updates runs.md, customruns.md and pipelines.md to keep the related instruction up-to-date.
1 parent f9021b1 commit 963aa40

File tree

4 files changed

+294
-13
lines changed

4 files changed

+294
-13
lines changed

‎docs/customruns.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ weight: 800
2626

2727
# Overview
2828

29-
*`CustomRun` is the `Beta` version of [`Run`](runs.md).*
29+
*We are promoting Custom Task from [`v1alpha1.Run`](runs.md) to `v1beta1.CustomRun`, please refer to the [migration doc](migrating-v1alpha1.Run-to-v1beta1.CustomRun.md) for details.*
3030

3131
A `CustomRun` allows you to instantiate and execute a [Custom
3232
Task](https://github.com/tektoncd/community/blob/main/teps/0002-custom-tasks.md),

‎docs/migrating-v1alpha1.Run-to-v1beta1.CustomRun.md

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
<!--
2+
---
3+
linkTitle: "Migrating from v1alpha1.Run to v1beta1.CustomRun"
4+
weight: 4000
5+
---
6+
-->
7+
8+
# Migrating from v1alpha1.Run to v1beta1.CustomRun
9+
10+
This document describes how to migrate from `v1alpha1.Run` and `v1beta1.CustomRun`
11+
- [Changes to fields](#changes-to-fields)
12+
- [Changes to the specification](#changes-to-the-specification)
13+
- [Changes to the reference](#changes-to-the-reference)
14+
- [Support `PodTemplate` in Custom Task Spec](#support-podtemplate-in-custom-task-spec)
15+
- [Changes to implementation requirements](#changes-to-implementation-instructions)
16+
- [Status Reporting](#status-reporting)
17+
- [Cancellation](#cancellation)
18+
- [Timeout](#timeout)
19+
- [Retries & RetriesStatus](#4-retries--retriesstatus)
20+
- [New feature flag `custom-task-version` for migration](#new-feature-flag-custom-task-version)
21+
22+
## Changes to fields
23+
24+
Comparing `v1alpha1.Run` with `v1beta1.CustomRun`, the following fields have been changed:
25+
26+
| Old field | New field |
27+
| ---------------------- | ------------------|
28+
| `spec.spec` | [`spec.customSpec`](#changes-to-the-specification) |
29+
| `spec.ref` | [`spec.customRef`](#changes-to-the-reference) |
30+
| `spec.podTemplate` | removed, see [this section](#support-podtemplate-in-custom-task-spec) if you still want to support it|
31+
32+
33+
### Changes to the specification
34+
35+
In `v1beta1.CustomRun`, the specification is renamed from `spec.spec` to `spec.customSpec`.
36+
37+
```yaml
38+
# before (v1alpha1.Run)
39+
apiVersion: tekton.dev/v1alpha1
40+
kind: Run
41+
metadata:
42+
name: run-with-spec
43+
spec:
44+
spec:
45+
apiVersion: example.dev/v1alpha1
46+
kind: Example
47+
spec:
48+
field1: value1
49+
field2: value2
50+
# after (v1beta1.CustomRun)
51+
apiVersion: tekton.dev/v1beta1
52+
kind: CustomRun
53+
metadata:
54+
name: customrun-with-spec
55+
spec:
56+
customSpec:
57+
apiVersion: example.dev/v1beta1
58+
kind: Example
59+
spec:
60+
field1: value1
61+
field2: value2
62+
```
63+
64+
### Changes to the reference
65+
66+
In `v1beta1.CustomRun`, the specification is renamed from `spec.ref` to `spec.customRef`.
67+
68+
```yaml
69+
# before (v1alpha1.Run)
70+
apiVersion: tekton.dev/v1alpha1
71+
kind: Run
72+
metadata:
73+
name: run-with-reference
74+
spec:
75+
ref:
76+
apiVersion: example.dev/v1alpha1
77+
kind: Example
78+
name: my-example
79+
---
80+
# after (v1beta1.CustomRun)
81+
apiVersion: tekton.dev/v1beta1
82+
kind: CustomRun
83+
metadata:
84+
name: customrun-with-reference
85+
spec:
86+
customRef:
87+
apiVersion: example.dev/v1beta1
88+
kind: Example
89+
name: my-customtask
90+
```
91+
92+
### Support `PodTemplate` in Custom Task Spec
93+
94+
`spec.podTemplate` is removed in `v1beta1.CustomRun`. You can support that field in your own custom task spec if you want to. For example:
95+
96+
```yaml
97+
apiVersion: tekton.dev/v1beta1
98+
kind: CustomRun
99+
metadata:
100+
name: customrun-with-podtemplate
101+
spec:
102+
customSpec:
103+
apiVersion: example.dev/v1beta1
104+
kind: Example
105+
spec:
106+
podTemplate:
107+
securityContext:
108+
runAsUser: 1001
109+
```
110+
111+
## Changes to implementation instructions
112+
We've changed four implementation instructions. Note that `status reporting` is the only required instruction to follow, others are recommendations.
113+
114+
### Status Reporting
115+
116+
You **MUST** report `v1beta1.CustomRun` as `Done` (set its `Conditions.Succeeded` status as `True` or `False`) **ONLY** when you want Pipeline Controller consider it as finished.
117+
118+
For example, if the `CustomRun` failed, while it still has remaining `retries`. If you want pipeline controller to continue watching its status changing, you **MUST NOT** mark it as `Done`. Otherwise, the `PipelineRun` controller may consider it as finished.
119+
120+
Here are statuses that indicating the `CustomRun` is done.
121+
```yaml
122+
Type: Succeeded
123+
Status: False
124+
Reason: TimedOut
125+
```
126+
```yaml
127+
Type: Succeeded
128+
Status: True
129+
Reason: Succeeded
130+
```
131+
132+
### Cancellation
133+
134+
Custom Task implementors are responsible for implementing `cancellation` to **support pipelineRun level timeouts and cancellation**. If a Custom Task implementor does not support cancellation via `customRun.spec.status`, `PipelineRun` can not timeout within the specified interval/duration and can not be cancelled as expected upon request.
135+
136+
It is recommended to update the `CustomRun` status as following, once noticing `customRun.Spec.Status` is updated to `RunCancelled`
137+
138+
```yaml
139+
Type: Succeeded
140+
Status: False
141+
Reason: CustomRunCancelled
142+
```
143+
144+
### Timeout
145+
146+
We recommend `customRun.Timeout` to be set for each retry attempt instead of all retries. That's said, if one `CustomRun` execution fails on `Timeout` and it has remaining retries, the `CustomRun` controller SHOULD NOT set the status of that `CustomRun` as `False`. Instead, it SHOULD initiate another round of execution.
147+
148+
### 4. Retries & RetriesStatus
149+
150+
We recommend you use `customRun.Spec.Retries` if you want to implement the `retry` logic for your `Custom Task`, and archive history `customRun.Status` in `customRun.Status.RetriesStatus`.
151+
152+
Say you started a `CustomRun` by setting the following condition:
153+
```yaml
154+
Status:
155+
Conditions:
156+
- Type: Succeeded
157+
Status: Unknown
158+
Reason: Running
159+
```
160+
Now it failed for some reasons but has remaining retries, instead of setting Conditions as failed on TimedOut:
161+
```yaml
162+
Status:
163+
Conditions:
164+
- Type: Succeeded
165+
Status: False
166+
Reason: Failed
167+
```
168+
We **recommend** you to do archive the failure status to `customRun.Status.retriesStatus`, and keep setting `customRun.Status` as `Unknown`:
169+
```yaml
170+
Status:
171+
Conditions:
172+
- Type: Succeeded
173+
Status: Unknown
174+
Reason: "xxx"
175+
RetriesStatus:
176+
- Conditions:
177+
- Type: Succeeded
178+
Status: False
179+
Reason: Failed
180+
```
181+
182+
183+
## New feature flag `custom-task-version` for migration
184+
185+
You can use `custom-task-version` to control whether `v1alpha1.Run` or `v1beta1.CustomRun` should be created when a `Custom Task` is specified in a `Pipeline`. The feature flag currently supports two values: `v1alpha1` and `v1beta1`.
186+
187+
We'll change its default value per the following timeline:
188+
- v0.43.*: default to `v1alpha1`.
189+
- v0.44.*: switch the default to `v1beta1`
190+
- v0.47.*: remove the feature flag, stop supporting creating `v1alpha1.Run`
191+
192+
193+
[cancel-pr]: https://github.com/tektoncd/pipeline/blob/main/docs/pipelineruns.md#cancelling-a-pipelinerun
194+
[gracefully-cancel-pr]: (https://github.com/tektoncd/pipeline/blob/main/docs/pipelineruns.md#gracefully-cancelling-a-pipelinerun)

‎docs/pipelines.md

Lines changed: 98 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,10 @@ weight: 400
5858
- [Specifying matrix](#specifying-matrix)
5959
- [Specifying workspaces](#specifying-workspaces-1)
6060
- [Using `Results`](#using-results-1)
61+
- [Specifying `Timeout`](#specifying-timeout)
62+
- [Specifying `Retries`](#specifying-retries)
6163
- [Limitations](#limitations)
64+
- [Known Custom Tasks](#known-custom-tasks)
6265
- [Code examples](#code-examples)
6366

6467
## Overview
@@ -1564,17 +1567,18 @@ no `runAfter` can be specified in `finally` tasks.
15641567

15651568
## Using Custom Tasks
15661569

1570+
We are promoting Custom Task from `v1alpha1` to `v1beta1`. Starting from `v0.43.0`, Pipeline Controller is able to create either `v1alpha1` or `v1beta1` Custom Task gated by a feature flag `custom-task-version`, defaulting to `v1alpha1`. You can set `custom-task-version` to `v1alpha1` or `v1beta1` to control which version to create.
1571+
1572+
We'll switch the default value of `custom-task-version` to `v1beta1` in release v0.44.0, and remove the flag as well as the entire alpha version in release v0.47.0. See the [migration doc](migrating-v1alpha1.Run-to-v1beta1.CustomRun.md) for details.
1573+
15671574
[Custom Tasks](https://github.com/tektoncd/community/blob/main/teps/0002-custom-tasks.md)
15681575
can implement behavior that doesn't correspond directly to running a workload in a `Pod` on the cluster.
15691576
For example, a custom task might execute some operation outside of the cluster and wait for its execution to complete.
15701577

1571-
A PipelineRun starts a custom task by creating a [`Run`](https://github.com/tektoncd/pipeline/blob/main/docs/runs.md) instead of a `TaskRun`.
1578+
A `PipelineRun` starts a custom task by creating a [`Run`](https://github.com/tektoncd/pipeline/blob/main/docs/runs.md)/[`CustomRun`](https://github.com/tektoncd/pipeline/blob/main/docs/customruns.md) instead of a `TaskRun`.
15721579
In order for a custom task to execute, there must be a custom task controller running on the cluster
1573-
that is responsible for watching and updating `Run`s which reference their type.
1574-
If no such controller is running, those `Run`s will never complete and Pipelines using them will time out.
1575-
1576-
Custom tasks are an **_experimental alpha feature_** and should be expected to change
1577-
in breaking ways or even be removed.
1580+
that is responsible for watching and updating `Run/CustomRun`s which reference their type.
1581+
If no such controller is running, those `Run/CustomRun`s will never complete and Pipelines using them will time out.
15781582

15791583
### Specifying the target Custom Task
15801584

@@ -1590,7 +1594,7 @@ spec:
15901594
kind: Example
15911595
```
15921596

1593-
This creates a `Run` of a custom task of type `Example` in the `example.dev` API group with the version `v1alpha1`.
1597+
This creates a `Run/CustomRun` of a custom task of type `Example` in the `example.dev` API group with the version `v1alpha1`.
15941598

15951599
You can also specify the `name` of a custom task resource object previously defined in the cluster.
15961600

@@ -1612,6 +1616,7 @@ some default behavior for executing unnamed tasks.
16121616

16131617
### Specifying a Custom Task Spec in-line (or embedded)
16141618

1619+
**For `v1alpha1.Run`**
16151620
```yaml
16161621
spec:
16171622
tasks:
@@ -1624,13 +1629,28 @@ spec:
16241629
field2: value2
16251630
```
16261631

1627-
If the custom task controller supports the in-line or embedded task spec, this will create a `Run` of a custom task of
1632+
**For `v1beta1.CustomRun`**
1633+
```yaml
1634+
spec:
1635+
tasks:
1636+
- name: run-custom-task
1637+
taskSpec:
1638+
apiVersion: example.dev/v1alpha1
1639+
kind: Example
1640+
customSpec:
1641+
field1: value1
1642+
field2: value2
1643+
```
1644+
1645+
If the custom task controller supports the in-line or embedded task spec, this will create a `Run/CustomRun` of a custom task of
16281646
type `Example` in the `example.dev` API group with the version `v1alpha1`.
16291647

16301648
If the `taskSpec` is not supported, the custom task controller should produce proper validation errors.
16311649

16321650
Please take a look at the
1633-
[developer guide for custom controllers supporting `taskSpec`.](runs.md#developer-guide-for-custom-controllers-supporting-spec)
1651+
developer guide for custom controllers supporting `taskSpec`:
1652+
- [guidance for `Run`](runs.md#developer-guide-for-custom-controllers-supporting-spec)
1653+
- [guidance for `CustomRun`](customruns.md#developer-guide-for-custom-controllers-supporting-customspec)
16341654

16351655
`taskSpec` support for `pipelineRun` was designed and discussed in
16361656
[TEP-0061](https://github.com/tektoncd/community/blob/main/teps/0061-allow-custom-task-to-be-embedded-in-pipeline.md)
@@ -1707,12 +1727,79 @@ Consult the documentation of the custom task that you are using to determine whe
17071727
If the custom task produces results, you can reference them in a Pipeline using the normal syntax,
17081728
`$(tasks.<task-name>.results.<result-name>)`.
17091729

1730+
### Specifying `Timeout`
1731+
1732+
#### `v1alpha1.Run`
1733+
If the custom task supports it as [we recommended](runs.md#developer-guide-for-custom-controllers-supporting-timeout), you can provide `timeout` to specify the maximum running time of a `CustomRun` (including all retry attempts or other operations).
1734+
1735+
#### `v1beta1.CustomRun`
1736+
If the custom task supports it as [we recommended](customruns.md#developer-guide-for-custom-controllers-supporting-timeout), you can provide `timeout` to specify the maximum running time of one `CustomRun` execution.
1737+
1738+
```yaml
1739+
spec:
1740+
tasks:
1741+
- name: run-custom-task
1742+
timeout: 2s
1743+
taskRef:
1744+
apiVersion: example.dev/v1alpha1
1745+
kind: Example
1746+
name: myexample
1747+
```
1748+
1749+
Consult the documentation of the custom task that you are using to determine whether it supports `Timeout`.
1750+
1751+
### Specifying `Retries`
1752+
If the custom task supports it, you can provide `retries` to specify how many times you want to retry the custom task.
1753+
1754+
```yaml
1755+
spec:
1756+
tasks:
1757+
- name: run-custom-task
1758+
retries: 2
1759+
taskRef:
1760+
apiVersion: example.dev/v1alpha1
1761+
kind: Example
1762+
name: myexample
1763+
```
1764+
1765+
Consult the documentation of the custom task that you are using to determine whether it supports `Retries`.
1766+
17101767
### Limitations
17111768

17121769
Pipelines do not support the following items with custom tasks:
17131770
* Pipeline Resources
1714-
* [`retries`](#using-the-retries-field)
1715-
* [`timeout`](#configuring-the-failure-timeout)
1771+
1772+
### Known Custom Tasks
1773+
1774+
We try to list as many known Custom Tasks as possible here so that users can easily find what they want. Please feel free to share the Custom Task you implemented in this table.
1775+
1776+
#### v1beta1.CustomRun
1777+
1778+
| Custom Task | Description |
1779+
|:---|:--- |
1780+
| [Wait Task Beta][wait-task-beta] | Waits a given amount of time before succeeding, specified by an input parameter named duration. Support `timeout` and `retries`. |
1781+
1782+
#### v1alpha1.Run
1783+
1784+
| Custom Task | Description |
1785+
|:---|:--- |
1786+
| [Pipeline Loops][pipeline-loops]| Runs a `Pipeline` in a loop with varying `Parameter` values.
1787+
| [Common Expression Language][cel]| Provides Common Expression Language support in Tekton Pipelines.
1788+
| [Wait][wait]| Waits a given amount of time, specified by a `Parameter` named "duration", before succeeding.
1789+
| [Approvals][approvals]| Pauses the execution of `PipelineRuns` and waits for manual approvals.
1790+
| [Pipelines in Pipelines][pipelines-in-pipelines]| Defines and executes a `Pipeline` in a `Pipeline`.
1791+
| [Task Group][task-group]| Groups `Tasks` together as a `Task`.
1792+
| [Pipeline in a Pod][pipeline-in-pod]| Runs `Pipeline` in a `Pod`.
1793+
1794+
[pipeline-loops]: https://github.com/tektoncd/experimental/tree/f60e1cd8ce22ed745e335f6f547bb9a44580dc7c/pipeline-loops
1795+
[task-loops]: https://github.com/tektoncd/experimental/tree/f60e1cd8ce22ed745e335f6f547bb9a44580dc7c/task-loops
1796+
[cel]: https://github.com/tektoncd/experimental/tree/f60e1cd8ce22ed745e335f6f547bb9a44580dc7c/cel
1797+
[wait]: https://github.com/tektoncd/experimental/tree/f60e1cd8ce22ed745e335f6f547bb9a44580dc7c/wait-task
1798+
[approvals]: https://github.com/automatiko-io/automatiko-approval-task/tree/71da90361dff9444146d52d0a6e2b542d4bf4edc
1799+
[task-group]: https://github.com/openshift-pipelines/tekton-task-group/tree/39823f26be8f59504f242a45b9f2e791d4b36e1c
1800+
[pipelines-in-pipelines]: https://github.com/tektoncd/experimental/tree/f60e1cd8ce22ed745e335f6f547bb9a44580dc7c/pipelines-in-pipelines
1801+
[pipeline-in-pod]: https://github.com/tektoncd/experimental/tree/f60e1cd8ce22ed745e335f6f547bb9a44580dc7c/pipeline-in-pod
1802+
[wait-task-beta]: https://github.com/tektoncd/pipeline/tree/a127323da31bcb933a04a6a1b5dbb6e0411e3dc1/test/custom-task-ctrls/wait-task-beta
17161803

17171804
## Code examples
17181805

‎docs/runs.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ weight: 800
2121

2222
# Overview
2323

24-
*We've released the Beta version of `Run`: `CustomRun`, check [this page](customruns.md) for details.*
24+
*We are promoting Custom Task from `v1alpha1.Run` to [`v1beta1.CustomRun`](customruns.md), please refer to the [migration doc](migrating-v1alpha1.Run-to-v1beta1.CustomRun.md) for details.*
2525

2626
A `Run` allows you to instantiate and execute a [Custom
2727
Task](https://github.com/tektoncd/community/blob/main/teps/0002-custom-tasks.md),

0 commit comments

Comments
 (0)