TEP-0100: Embedded TaskRuns and Runs Status in PipelineRuns [Proposal]

In [TEP-0100], we described the challenges caused by embedding the complete `TaskRun` and `Run` status in `PipelineRuns`: performance degradation, memory bloat, and lack of extensibility. In this change we add the proposal to reduce the amount of information stored about the status of `TaskRuns` and `Runs` to only the names and the overall status in order to improve performance, reduce memory bloat and improve extensibility. We also mark the TEP as implementable. Co-authored-by: Lee Bernick <leebernick@google.com>
tektoncd · Feb 1, 2022 · 90e5de7 · 90e5de7
1 parent d3b2856
commit 90e5de7
Show file tree

Hide file tree

Showing 2 changed files with 296 additions and 9 deletions.
diff --git a/teps/0100-embedded-taskruns-and-runs-status-in-pipelineruns.md b/teps/0100-embedded-taskruns-and-runs-status-in-pipelineruns.md
@@ -1,15 +1,16 @@
 ---
-status: proposed
+status: implementable
 title: Embedded TaskRuns and Runs Status in PipelineRuns
 creation-date: '2022-01-24'
-last-updated: '2022-01-29'
+last-updated: '2022-01-31'
 authors:
 - '@lbernick'
 - '@jerop'
 see-also:
 - TEP-0021
 - TEP-0056
 - TEP-0090
+- TEP-0096
 ---
 
 # TEP-0100: Embedded TaskRuns and Runs Status in PipelineRuns
@@ -26,7 +27,19 @@ see-also:
  - [PipelineRun Status](#pipelinerun-status)
  - [Owner References and Labels](#owner-references-and-labels)
  - [Tekton Results API](#tekton-results-api)
-- [Open Questions](#open-questions)
+- [Proposal](#proposal)
+ - [API Changes](#api-changes)
+ - [Example](#example)
+ - [Beta API](#beta-api)
+ - [V1 API](#v1-api)
+ - [JSON keys](#json-keys)
+ - [Tekton Projects](#tekton-projects)
+ - [Tekton Results](#tekton-results)
+ - [Tekton Dashboard](#tekton-dashboard)
+ - [Tekton Chains](#tekton-chains)
+- [Alternatives](#alternatives)
+ - [Use Map](#use-map)
+ - [Discussion](#discussion)
 - [References](#references)
 <!-- /toc -->
 
@@ -171,12 +184,277 @@ In addition to grouping related resources, Tekton Results provides long term sto
 of `PipelineRuns`, `TaskRuns` and `Runs` away from the runtime storage in etcd.
 Read more in [TEP-0021][tep-0021].
 
-## Open Questions
+## Proposal
 
-* [Qn #1][qn-1]: What fields will no longer be available? What do we lose from the optimizations?
- We will discuss this in the proposal.
-* [Qn #2][qn-1]: What does an example status look like?
- We will provide examples in the proposal.
+The `PipelineRunStatus` should contain the names and overall status (`ConditionSucceeded`)
+of its `TaskRuns` and `Runs`. Users and tools can find the complete status of `TaskRuns`
+and `Runs` in the cluster. Moreover, they can rely on [Tekton Results](#tekton-results-api)
+and [Owner References and Labels](#owner-references-and-labels) to identify related objects.
+
+### API Changes
+
+1. Rename the existing structs that embed the complete status of `TaskRuns` and `Runs`:
+ * `PipelineRunTaskRunStatus` to `PipelineRunTaskRunEmbeddedStatus`
+ * `PipelineRunRunStatus` to `PipelineRunRunEmbeddedStatus`
+
+2. Introduce two new structs to store the minimal status of `TaskRuns` and `Runs` in the
+`PipelineRun` status, with the names and overall status only:
+
+```go
+type PipelineRunTaskRunStatus struct {
+ TaskRunName string `json:"taskRunName,omitempty"`
+ duckv1beta1.Status `json:",inline"`
+}
+
+type PipelineRunRunStatus struct {
+ RunName string `json:"runName,omitempty"`
+ duckv1beta1.Status `json:",inline"`
+}
+```
+
+3. Add the new fields to [`PipelineRunStatusFields`](#pipelinerun-status) as follows:
+
+```go
+type PipelineRunStatusFields struct {
+ ...
+ TaskRuns map[string]*PipelineRunTaskRunEmbeddedStatus `json:"taskRuns,omitempty"`
+ TaskRunsStatus []PipelineRunTaskRunStatus `json:"taskRunsStatus,omitempty"`
+ Runs map[string]*PipelineRunRunEmbeddedStatus `json:"runs,omitempty"`
+ RunsStatus []PipelineRunRunStatus `json:"runsStatus,omitempty"`
+ ...
+}
+```
+
+The existing fields providing the complete `TaskRun` and `Runs` are maps with the resource
+names as keys. However, the new fields are sub-objects instead of maps as recommended by the
+[Kubernetes API conventions][subobjects].
+
+4. Following Tekton’s deprecation policy, remove the old structs from `PipelineRunStatusFields`.
+
+```go
+type PipelineRunStatusFields struct {
+ ...
+ TaskRunsStatus []PipelineRunTaskRunStatus `json:"taskRunsStatus,omitempty"`
+ RunsStatus []PipelineRunRunStatus `json:"runsStatus,omitempty"`
+ ...
+}
+```
+
+See the [Beta API](#beta-api) and [V1 API](#v1-api) sections below for more information on the
+migration plan.
+
+#### Example
+
+This is an example `PipelineRun` status as provided in the [documentation][example]:
+
+```yaml
+apiVersion: tekton.dev/v1beta1
+kind: PipelineRun
+metadata:
+ ...
+spec:
+ ...
+status:
+ completionTime: "2020-05-04T02:19:14Z"
+ conditions:
+ - lastTransitionTime: "2020-05-04T02:19:14Z"
+ message: "Tasks Completed: 4, Skipped: 0"
+ reason: Succeeded
+ status: "True"
+ type: Succeeded
+ startTime: "2020-05-04T02:00:11Z"
+ taskRuns:
+ triggers-release-nightly-build:
+ pipelineTaskName: build
+ status:
+ completionTime: "2020-05-04T02:10:49Z"
+ conditions:
+ - lastTransitionTime: "2020-05-04T02:10:49Z"
+ message: All Steps have completed executing
+ reason: Succeeded
+ status: "True"
+ type: Succeeded
+ podName: triggers-release-nightly-build-pod
+ resourcesResult:
+ - key: commit
+ resourceRef:
+ name: git-source-triggers
+ value: 9ab5a1234166a89db352afa28f499d596ebb48db
+ startTime: "2020-05-04T02:05:07Z"
+ steps:
+ - container: step-build
+ imageID: docker-pullable://golang@sha256:a90f2671330831830e229c3554ce118009681ef88af659cd98bfafd13d5594f9
+ name: build
+ terminated:
+ containerID: docker://6b6471f501f59dbb7849f5cdde200f4eeb64302b862a27af68821a7fb2c25860
+ exitCode: 0
+ finishedAt: "2020-05-04T02:10:45Z"
+ reason: Completed
+ startedAt: "2020-05-04T02:06:24Z"
+```
+
+Taking the above example, this will be the new minimal `PipelineRun` status:
+
+```yaml
+apiVersion: tekton.dev/v1beta1
+kind: PipelineRun
+metadata:
+ ...
+spec:
+ ...
+status:
+ completionTime: "2020-05-04T02:19:14Z"
+ conditions:
+ - lastTransitionTime: "2020-05-04T02:19:14Z"
+ message: "Tasks Completed: 4, Skipped: 0"
+ reason: Succeeded
+ status: "True"
+ type: Succeeded
+ startTime: "2020-05-04T02:00:11Z"
+ taskRunsStatus:
+ - taskRunName: triggers-release-nightly-build
+ conditions:
+ - lastTransitionTime: "2020-05-04T02:10:49Z"
+ message: All Steps have completed executing
+ reason: Succeeded
+ status: "True"
+ type: Succeeded
+```
+
+#### Beta API
+
+Because the `PipelineRun` status is part of the [Tekton Pipelines API][api-definition],
+this API change is not backwards compatible. To support migration, we will add a new 
+behavior flag - `disable-embedded-status` - used to configure whether `PipelineRuns`
+should contain the embedded status or minimal status of its `TaskRuns` and `Runs`.
+
+Following our [policy][behavior-flags] on updating behavior flags:
+* The `disable-embedded-status` flag will be *false* by default.
+* After 9 months in v1beta1, the `disable-embedded-status` flag will be flipped to *true* by default.
+* As soon as the next release in v1beta1, this flag will be removed as well as the embedded status fields.
+
+#### V1 API
+
+In V1, we will have the minimal status of `TaskRuns` and `Runs` in the `PipelineRun`.
+
+```go
+type PipelineRunStatusFields struct {
+ StartTime *metav1.Time `json:"startTime,omitempty"`
+ CompletionTime *metav1.Time `json:"completionTime,omitempty"`
+ TaskRunsStatus []PipelineRunTaskRunStatus `json:"taskRunsStatus,omitempty"`
+ RunsStatus []PipelineRunRunStatus `json:"runsStatus,omitempty"`
+ PipelineResults []PipelineRunResult `json:"pipelineResults,omitempty"`
+ PipelineSpec *PipelineSpec `json:"pipelineSpec,omitempty"`
+ SkippedTasks []SkippedTask `json:"skippedTasks,omitempty"`
+}
+```
+The embedded status of `TaskRuns` and `Runs` will not be available in `PipelineRuns`.
+Read more about V1 in [TEP-0096: Pipelines V1 API][tep-0096].
+
+#### JSON keys
+
+The JSON struct tags defined on Kubernetes CRDs are used to serialize and deserialize
+instances of those CRDs (see [JSON and Go][json-and-go] for more information on how
+struct tags affect serialization and deserialization). We can't reuse the existing JSON
+keys `taskRuns` and `runs` without breaking serialization/deserialization for existing
+`PipelineRuns`. The keys can be reused once we move to a V1 API by writing a conversion
+webhook, but it is easier to simply not reuse the keys.
+
+### Tekton Projects
+
+#### Tekton Results
+
+As described in the [background section](#tekton-results-api), the Results API enables
+users to bundle `TaskRuns` and `Runs` to their parent `PipelineRuns`. It also provides
+long term storage of resources. Users can rely on [Tekton Results][results-api] to map
+`TaskRuns` and `Runs` to provide the mapping that was available in embedded statuses.
+Note that Results API is still in Alpha, but progress is being made towards Beta - we
+estimate that the Results API will be in Beta by the time we remove the embedded status.
+
+#### Tekton Dashboard
+
+[Tekton Dashboard][dashboard] shows the status the `TaskRuns` and `Runs` of a given
+`PipelineRun`, this should be unaffected. We expect the load on the Dashboard to
+reduce and its performance to improve, given that the `PipelineRuns` would not be
+reacting to the updates in `Steps`.
+
+#### Tekton Chains
+
+[Tekton Chain][chains] observes `TaskRuns` and signed them directly, they don't depend
+on the embedded status in `PipelineRun` status, so they should be unaffected. When
+Tekton Chains starts to sign `PipelineRuns`, as proposed in [TEP-0084][tep-0084],
+we are exploring creating a single attestation record upon completion of a `PipelineRun`
+that includes everything - `TaskRuns`, `PipelineRun`, and `event-payload` - instead of
+a record for each of them. We will ensure that the proposal in TEP-0084 aligns with the
+changes to `PipelineRuns` proposed in this TEP.
+
+
+### Design Evaluation
+
+1. **API conventions**: This design complies with the [Kubernetes API conventions][subobjects]
+ by using sub-objects instead of maps.
+2. **Simplicity**: This design simplifies the `PipelineRun` status by providing the minimum
+ information and updates needed from `TaskRuns` and `Runs`.
+3. **Reusability**: This design encourages reuse of existing components, such as Owner References
+ and Tekton Results, by removing the duplication caused by embedded statuses.
+4. **Flexibility**: This design improves the extensibility of Tekton Pipelines to support upcoming
+ features that create multiple `TaskRuns`, `Runs` or `PipelineRuns` from a single `PipelineTask`.
+5. **Conformance**: This design impact the conformance surface through changes to the `PipelineRun`
+ interface. The changes are backwards incompatible but will be introduced in a backwards compatible
+ manner first with migration instructions and deprecation warnings.
+
+## Alternatives
+
+### Use Map
+
+Use maps for the new fields, as we do with the existing fields:
+
+```go
+type PipelineRunStatusFields struct {
+ ...
+ TaskRuns map[string]*PipelineRunTaskRunEmbeddedStatus `json:"taskRuns,omitempty"`
+ TaskRunsStatus map[string]*PipelineRunTaskRunStatus `json:"taskRunsStatus,omitempty"`
+ Runs map[string]*PipelineRunRunEmbeddedStatus `json:"runs,omitempty"`
+ RunsStatus map[string]*PipelineRunRunStatus `json:"runsStatus,omitempty"`
+ ...
+}
+```
+
+Taking the [example above](#example), this would be the `PipelineRun` status:
+
+```yaml
+apiVersion: tekton.dev/v1beta1
+kind: PipelineRun
+metadata:
+ ...
+spec:
+ ...
+status:
+ completionTime: "2020-05-04T02:19:14Z"
+ conditions:
+ - lastTransitionTime: "2020-05-04T02:19:14Z"
+ message: "Tasks Completed: 4, Skipped: 0"
+ reason: Succeeded
+ status: "True"
+ type: Succeeded
+ startTime: "2020-05-04T02:00:11Z"
+ taskRunStatus:
+ triggers-release-nightly-build:
+ conditions:
+ - lastTransitionTime: "2020-05-04T02:10:49Z"
+ message: All Steps have completed executing
+ reason: Succeeded
+ status: "True"
+ type: Succeeded
+```
+
+#### Discussion
+
+While this approach is consistent with existing code, it does not comply with the
+[Kubernetes API conventions][subobjects] that recommend against maps.
+The [main problem][why-subobjects] with maps is:
+> The crux of maps is that it isn't clear to the user what "left hand side strings"
+> are "magic keywords" in the config system/API vs. which are user data.
 
 ## References
 
@@ -192,10 +470,19 @@ Read more in [TEP-0021][tep-0021].
 [tep-0056]: https://github.com/tektoncd/community/blob/main/teps/0056-pipelines-in-pipelines.md
 [tep-0090]: https://github.com/tektoncd/community/blob/main/teps/0090-matrix.md
 [tep-0021]: https://github.com/tektoncd/community/blob/main/teps/0021-results-api.md
+[tep-0096]: https://github.com/tektoncd/community/blob/main/teps/0096-pipelines-v1-api.md
 [issue-3140]: https://github.com/tektoncd/pipeline/issues/3140
 [issue-3792]: https://github.com/tektoncd/pipeline/issues/3792
 [api-wg]: https://docs.google.com/document/d/17PodAxG8hV351fBhSu7Y_OIPhGTVgj6OJ2lPphYYRpU/edit#heading=h.esbaqjpyouim
 [pipelinerunstatus]: https://github.com/tektoncd/pipeline/blob/411d033c5e4bf3409f01b175531cbc1a0a75fadb/pkg/apis/pipeline/v1beta1/pipelinerun_types.go#L290-L296
 [pipelinerunstatusfields]: https://github.com/tektoncd/pipeline/blob/411d033c5e4bf3409f01b175531cbc1a0a75fadb/pkg/apis/pipeline/v1beta1/pipelinerun_types.go#L393-L423
 [results-api]: https://github.com/tektoncd/results
 [qn-1]: https://github.com/tektoncd/community/pull/606#discussion_r792860152
+[subobjects]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#lists-of-named-subobjects-preferred-over-maps
+[behavior-flags]: https://github.com/tektoncd/community/blob/main/teps/0033-tekton-feature-gates.md#promoting-behavior-flags
+[api-definition]: https://github.com/tektoncd/pipeline/blob/main/api_compatibility_policy.md#alpha-beta-and-ga
+[json-and-go]: https://go.dev/blog/json
+[why-subobjects]: https://github.com/kubernetes/kubernetes/issues/2004#issuecomment-60641437
+[example]: https://github.com/tektoncd/pipeline/blob/411d033c5e4bf3409f01b175531cbc1a0a75fadb/docs/pipelineruns.md#monitoring-execution-status
+[chains]: https://github.com/tektoncd/chains
+[dashboard]: https://github.com/tektoncd/dashboard
diff --git a/teps/README.md b/teps/README.md
@@ -235,4 +235,4 @@ This is the complete list of Tekton teps:
 |[TEP-0094](0094-configuring-resources-at-runtime.md) | Configuring Resources at Runtime | implementable | 2021-11-29 |
 |[TEP-0096](0096-pipelines-v1-api.md) | Pipelines V1 API | proposed | 2021-12-13 |
 |[TEP-0098](0098-workflows.md) | Workflows | proposed | 2021-12-06 |
-|[TEP-0100](0100-embedded-taskruns-and-runs-status-in-pipelineruns.md) | Embedded TaskRuns and Runs Status in PipelineRuns | proposed | 2022-01-29 |
+|[TEP-0100](0100-embedded-taskruns-and-runs-status-in-pipelineruns.md) | Embedded TaskRuns and Runs Status in PipelineRuns | implementable | 2022-01-31 |