TEP-0075(object params and results) promoted to stable

Pipeline 0.46 introduced object params and results. This commit is promoting TEP-0075 to stable such that these features can be used by the task authors and pipeline authors in a cluster when enable-api-fields is alpha,beta or stable. Signed-off-by: Yongxuan Zhang [email protected]
tektoncd · Jan 5, 2024 · fe47c9b · fe47c9b
1 parent 8ad2da9
commit fe47c9b
Show file tree

Hide file tree

Showing 28 changed files with 80 additions and 615 deletions.
diff --git a/docs/additional-configs.md b/docs/additional-configs.md
@@ -334,7 +334,6 @@ Features currently in "beta" are:
 | Feature                                                                                               | Proposal                                                                                                 | Alpha Release                                                        | Beta Release                                                         | Individual Flag               |
 |:------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------|:---------------------------------------------------------------------|:------------------------------|
 | [Array Results and Array Indexing](pipelineruns.md#specifying-parameters)                             | [TEP-0076](https://github.com/tektoncd/community/blob/main/teps/0076-array-result-types.md)              | [v0.38.0](https://github.com/tektoncd/pipeline/releases/tag/v0.38.0) | [v0.45.0](https://github.com/tektoncd/pipeline/releases/tag/v0.45.0) |                               |
-| [Object Parameters and Results](pipelineruns.md#specifying-parameters)                                | [TEP-0075](https://github.com/tektoncd/community/blob/main/teps/0075-object-param-and-result-types.md)   |                                                                      | [v0.46.0](https://github.com/tektoncd/pipeline/releases/tag/v0.46.0) |                               |
 | [Remote Tasks](./taskruns.md#remote-tasks) and [Remote Pipelines](./pipelineruns.md#remote-pipelines) | [TEP-0060](https://github.com/tektoncd/community/blob/main/teps/0060-remote-resolution.md)               |                                                                      | [v0.41.0](https://github.com/tektoncd/pipeline/releases/tag/v0.41.0) |                               |
 | [`Provenance` field in Status](pipeline-api.md#provenance)                                            | [issue#5550](https://github.com/tektoncd/pipeline/issues/5550)                                           | [v0.41.0](https://github.com/tektoncd/pipeline/releases/tag/v0.41.0) | [v0.48.0](https://github.com/tektoncd/pipeline/releases/tag/v0.48.0) | `enable-provenance-in-status` |
 | [Isolated `Step` & `Sidecar` `Workspaces`](./workspaces.md#isolated-workspaces)                       | [TEP-0029](https://github.com/tektoncd/community/blob/main/teps/0029-step-workspaces.md)                 | [v0.24.0](https://github.com/tektoncd/pipeline/releases/tag/v0.24.0) | [v0.50.0](https://github.com/tektoncd/pipeline/releases/tag/v0.50.0) |                               |

diff --git a/docs/pipelineruns.md b/docs/pipelineruns.md
@@ -19,7 +19,7 @@ weight: 204
       - [Propagated Parameters](#propagated-parameters)
         - [Scope and Precedence](#scope-and-precedence)
         - [Default Values](#default-values)
-        - [Object Parameters](#object-parameters) 
+        - [Object Parameters](#object-parameters)
     - [Specifying custom <code>ServiceAccount</code> credentials](#specifying-custom-serviceaccount-credentials)
     - [Mapping <code>ServiceAccount</code> credentials to <code>Tasks</code>](#mapping-serviceaccount-credentials-to-tasks)
     - [Specifying a <code>Pod</code> template](#specifying-a-pod-template)
@@ -71,12 +71,12 @@ A `PipelineRun` definition supports the following fields:
   - [`params`](#specifying-parameters) - Specifies the desired execution parameters for the `Pipeline`.
   - [`serviceAccountName`](#specifying-custom-serviceaccount-credentials) - Specifies a `ServiceAccount`
     object that supplies specific execution credentials for the `Pipeline`.
-  - [`status`](#cancelling-a-pipelinerun) - Specifies options for cancelling a `PipelineRun`. 
+  - [`status`](#cancelling-a-pipelinerun) - Specifies options for cancelling a `PipelineRun`.
   - [`taskRunSpecs`](#specifying-taskrunspecs) - Specifies a list of `PipelineRunTaskSpec` which allows for setting `ServiceAccountName`, [`Pod` template](./podtemplates.md), and `Metadata` for each task. This overrides the `Pod` template set for the entire `Pipeline`.
   - [`timeout`](#configuring-a-failure-timeout) - Specifies the timeout before the `PipelineRun` fails. `timeout` is deprecated and will eventually be removed, so consider using `timeouts` instead.
   - [`timeouts`](#configuring-a-failure-timeout) - Specifies the timeout before the `PipelineRun` fails. `timeouts` allows more granular timeout configuration, at the pipeline, tasks, and finally levels
   - [`podTemplate`](#specifying-a-pod-template) - Specifies a [`Pod` template](./podtemplates.md) to use as the basis for the configuration of the `Pod` that executes each `Task`.
-  - [`workspaces`](#specifying-workspaces) - Specifies a set of workspace bindings which must match the names of workspaces declared in the pipeline being used. 
+  - [`workspaces`](#specifying-workspaces) - Specifies a set of workspace bindings which must match the names of workspaces declared in the pipeline being used.
 
 [kubernetes-overview]:
   https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields
@@ -233,7 +233,7 @@ spec:
 apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
 kind: PipelineRun
 metadata:
-  name: pipelinerun 
+  name: pipelinerun
 spec:
   pipelineRef:
     name: pipeline
@@ -275,9 +275,9 @@ go through the complexity of checking each `Pipeline` and providing only the req
 
 > :seedling: **`enum` is an [alpha](additional-configs.md#alpha-features) feature.** The `enable-param-enum` feature flag must be set to `"true"` to enable this feature.
 
-If a `Parameter` is guarded by `Enum` in the `Pipeline`, you can only provide `Parameter` values in the `PipelineRun` that are predefined in the `Param.Enum` in the `Pipeline`. The `PipelineRun` will fail with reason `InvalidParamValue` otherwise. 
+If a `Parameter` is guarded by `Enum` in the `Pipeline`, you can only provide `Parameter` values in the `PipelineRun` that are predefined in the `Param.Enum` in the `Pipeline`. The `PipelineRun` will fail with reason `InvalidParamValue` otherwise.
 
-Tekton will also the validate the `param` values passed to any referenced `Tasks` (via `taskRef`) if `Enum` is specified for the `Task`. The `PipelineRun` will fail with reason `InvalidParamValue` if `Enum` validation is failed for any of the `PipelineTask`. 
+Tekton will also the validate the `param` values passed to any referenced `Tasks` (via `taskRef`) if `Enum` is specified for the `Task`. The `PipelineRun` will fail with reason `InvalidParamValue` if `Enum` validation is failed for any of the `PipelineTask`.
 
 You can also specify `Enum` in an embedded `Pipeline` in a `PipelineRun`. The same `Param` validation will be executed in this scenario.
 
@@ -579,43 +579,41 @@ status:
 
 ##### Object Parameters
 
-Object params is a [beta feature](./additional-configs.md#beta-features).
-
 When using an inlined spec, object parameters from the parent `PipelineRun` will also be
 propagated to any inlined specs without needing to be explicitly defined. This
 allows authors to simplify specs by automatically propagating top-level
 parameters down to other inlined resources.
 When propagating object parameters, scope and precedence also holds as shown below.
- 
+
 ```yaml
-apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1 
-kind: PipelineRun              
+apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
+kind: PipelineRun
 metadata:
-  generateName: pipelinerun-object-param-result 
+  generateName: pipelinerun-object-param-result
 spec:
   params:
-    - name: gitrepo            
-      value:                   
-        url: abc.com           
-        commit: sha123         
-  pipelineSpec:                
-    tasks:                     
-      - name: task1            
-        params:                
-          - name: gitrepo      
+    - name: gitrepo
+      value:
+        url: abc.com
+        commit: sha123
+  pipelineSpec:
+    tasks:
+      - name: task1
+        params:
+          - name: gitrepo
             value:
-              branch: main     
-              url: xyz.com     
+              branch: main
+              url: xyz.com
         taskSpec:
           steps:
-            - name: write-result            
-              image: bash      
-              args: [          
-                "echo",        
-                "--url=$(params.gitrepo.url)",  
+            - name: write-result
+              image: bash
+              args: [
+                "echo",
+                "--url=$(params.gitrepo.url)",
                 "--commit=$(params.gitrepo.commit)",
                 "--branch=$(params.gitrepo.branch)",
-              ]      
+              ]
 ```
 
 resolves to
@@ -650,7 +648,7 @@ spec:
           - --commit=$(params.gitrepo.commit)
           - --branch=$(params.gitrepo.branch)
           image: bash
-          name: write-result   
+          name: write-result
 status:
   completionTime: "2022-09-08T17:22:01Z"
   conditions:
@@ -784,7 +782,7 @@ spec:
             args:
               - echo "1001" | tee $(results.uid.path)
     - name: show-uid
-      # params: 
+      # params:
       #   - name: uid
       #     value: $(tasks.add-uid.results.uid)
       taskSpec:
@@ -885,7 +883,7 @@ metadata:
 spec:
   pipelineRef:
     name: mypipeline
-  taskRunTemplate: 
+  taskRunTemplate:
     podTemplate:
       securityContext:
         runAsNonRoot: true
@@ -1006,7 +1004,7 @@ spec:
     name: pipeline-name
   taskRunSpecs:
     - pipelineTaskName: task-name
-      metadata: 
+      metadata:
         annotations:
           vault.hashicorp.com/agent-inject-secret-foo: "/path/to/foo"
           vault.hashicorp.com/role: role-name
@@ -1020,7 +1018,7 @@ spec:
     name: pipeline-name
   taskRunSpecs:
     - pipelineTaskName: task-name
-      metadata: 
+      metadata:
         labels:
           app: cloudevent
 ```
@@ -1110,23 +1108,23 @@ spec:
     tasks:
     - name: fetch-secure-data
       # workspaces:
-      #   - name: shared-data 
+      #   - name: shared-data
       taskSpec:
         # workspaces:
-        #   - name: shared-data 
+        #   - name: shared-data
         steps:
         - name: fetch-and-write-secure
           image: ubuntu
           script: |
             echo hi >> $(workspaces.shared-data.path)/recipe.txt
     - name: print-the-recipe
       # workspaces:
-      #   - name: shared-data 
+      #   - name: shared-data
       runAfter:
         - fetch-secure-data
       taskSpec:
         # workspaces:
-        #   - name: shared-data 
+        #   - name: shared-data
         steps:
         - name: print-secrets
           image: ubuntu
@@ -1259,7 +1257,7 @@ spec:
   - name: fetch-and-write
     image: ubuntu
     script: |
-      echo $(workspaces.shared-data.path)      
+      echo $(workspaces.shared-data.path)
 ---
 apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
 kind: PipelineRun
@@ -1432,7 +1430,7 @@ If you set the timeout to 0, the `PipelineRun` fails immediately upon encounteri
 Your `PipelineRun`'s `status` field can contain the following fields:
 
 - Required:
-  - `status` - Most relevant, `status.conditions`, which contains the latest observations of the `PipelineRun`'s state. [See here](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#typical-status-properties) for information on typical status properties. 
+  - `status` - Most relevant, `status.conditions`, which contains the latest observations of the `PipelineRun`'s state. [See here](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#typical-status-properties) for information on typical status properties.
   - `startTime` - The time at which the `PipelineRun` began executing, in [RFC3339](https://tools.ietf.org/html/rfc3339) format.
   - `completionTime` - The time at which the `PipelineRun` finished executing, in [RFC3339](https://tools.ietf.org/html/rfc3339) format.
   - [`pipelineSpec`](pipelines.md#configuring-a-pipeline) - The exact `PipelineSpec` used when starting the `PipelineRun`.

diff --git a/docs/pipelines.md b/docs/pipelines.md
@@ -301,8 +301,8 @@ spec:
 If the `Param` value passed in by `PipelineRun` is **NOT** in the predefined `enum` list, the `PipelineRun` will fail with reason `InvalidParamValue`.
 
 If a `PipelineTask` references a `Task` with `enum`, the `enums` specified in the Pipeline `spec.params` (pipeline-level `enum`) must be
-a **subset** of the `enums` specified in the referenced `Task` (task-level `enum`). An empty pipeline-level `enum` is invalid 
-in this scenario since an empty `enum` set indicates a "universal set" which allows all possible values. The same rules apply to `Pipelines` with embbeded `Tasks`. 
+a **subset** of the `enums` specified in the referenced `Task` (task-level `enum`). An empty pipeline-level `enum` is invalid
+in this scenario since an empty `enum` set indicates a "universal set" which allows all possible values. The same rules apply to `Pipelines` with embbeded `Tasks`.
 
 In the below example, the referenced `Task` accepts `v1` and `v2` as valid values, the `Pipeline` further restricts the valid value to `v1`.
 
@@ -1280,7 +1280,7 @@ Sharing `Results` between `Tasks` in a `Pipeline` happens via
 a `Result` and another receives it as a `Parameter` with a variable such as
 `$(tasks.<task-name>.results.<result-name>)`. Pipeline support two new types of
 results and parameters: array `[]string` and object `map[string]string`.
-Array and Object result is a beta feature and can be enabled by setting `enable-api-fields` to `alpha` or `beta`.
+Array result is a beta feature and can be enabled by setting `enable-api-fields` to `alpha` or `beta`.
 
 | Result Type | Parameter Type | Specification                                    | `enable-api-fields` |
 |-------------|----------------|--------------------------------------------------|---------------------|
@@ -1375,7 +1375,7 @@ results:
 
 For an end-to-end example, see [`Results` in a `PipelineRun`](../examples/v1/pipelineruns/pipelinerun-results.yaml).
 
-Object result and array result are beta features,
+Array result is a beta feature,
 see [`Array and Object Results` in a `PipelineRun`](../examples/v1/pipelineruns/beta/pipeline-emitting-results.yaml).
 
 ```yaml

diff --git a/docs/taskruns.md b/docs/taskruns.md
@@ -304,10 +304,10 @@ status:
     reason: Succeeded
     status: "True"
     type: Succeeded
-  ... 
+  ...
   steps:
   - container: step-default
-    ...  
+    ...
   taskSpec:
     steps:
     - image: ubuntu
@@ -317,8 +317,6 @@ status:
 ```
 
 #### Propagated Object Parameters
-Object params is a [beta feature](./additional-configs.md#beta-features).
-
 When using an inlined `taskSpec`, object parameters from the parent `TaskRun` will be
 available to the `Task` without needing to be explicitly defined.
 
@@ -438,13 +436,13 @@ spec:
 apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
 kind: TaskRun
 metadata:
-  name: taskrun 
+  name: taskrun
 spec:
   taskRef:
     name: task
   computeResources:
     requests:
-      cpu: 1 
+      cpu: 1
     limits:
       cpu: 2
 ```
@@ -524,21 +522,21 @@ workspaces down to other inlined resources.
 **Workspace substutions will only be made for `commands`, `args` and `script` fields of `steps`, `stepTemplates`, and `sidecars`.**
 
 ```yaml
-apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1 
-kind: TaskRun                  
+apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
+kind: TaskRun
 metadata:
   generateName: propagating-workspaces-
 spec:
-  taskSpec:                    
-    steps:                     
-      - name: simple-step      
-        image: ubuntu          
-        command:               
-          - echo               
-        args:                  
+  taskSpec:
+    steps:
+      - name: simple-step
+        image: ubuntu
+        command:
+          - echo
+        args:
           - $(workspaces.tr-workspace.path)
-  workspaces:                  
-  - emptyDir: {}               
+  workspaces:
+  - emptyDir: {}
     name: tr-workspace
 ```
 
@@ -564,32 +562,32 @@ status:
 
 ##### Propagating Workspaces to Referenced Tasks
 
-Workspaces can only be propagated to `embedded` task specs, not `referenced` Tasks. 
+Workspaces can only be propagated to `embedded` task specs, not `referenced` Tasks.
 
 ```yaml
-apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1 
-kind: Task                     
+apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
+kind: Task
 metadata:
   name: workspace-propagation
 spec:
   steps:
-    - name: simple-step        
-      image: ubuntu            
-      command:                 
-        - echo                 
-      args:                    
+    - name: simple-step
+      image: ubuntu
+      command:
+        - echo
+      args:
         - $(workspaces.tr-workspace.path)
 ---
-apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1 
+apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
 kind: TaskRun
 metadata:
   generateName: propagating-workspaces-
 spec:
-  taskRef:                     
+  taskRef:
     name: workspace-propagation
-  workspaces:                  
-  - emptyDir: {}               
-    name: tr-workspace 
+  workspaces:
+  - emptyDir: {}
+    name: tr-workspace
 ```
 
 Upon execution, the above `TaskRun` will fail because the `Task` is referenced and workspace is not propagated. It must be explicitly defined in the `spec` of the defined `Task`.
@@ -788,7 +786,7 @@ The `status` field defines the observed state of `TaskRun`
 ### The `status` field
 - Required:
   - `status` - The most relevant information about the TaskRun's state. This field includes:
-    - `status.conditions`, which contains the latest observations of the `TaskRun`'s state. [See here](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#typical-status-properties) for information on typical status properties. 
+    - `status.conditions`, which contains the latest observations of the `TaskRun`'s state. [See here](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#typical-status-properties) for information on typical status properties.
   - `podName` - Name of the pod containing the containers responsible for executing this `task`'s `step`s.
   - `startTime` - The time at which the `TaskRun` began executing, conforms to [RFC3339](https://tools.ietf.org/html/rfc3339) format.
   - `completionTime` - The time at which the `TaskRun` finished executing, conforms to [RFC3339](https://tools.ietf.org/html/rfc3339) format.
@@ -802,11 +800,11 @@ The `status` field defines the observed state of `TaskRun`
     - `featureFlags`: Identifies the feature flags used during the `TaskRun`.
   - `steps` - Contains the `state` of each `step` container.
   - `retriesStatus` - Contains the history of `TaskRun`'s `status` in case of a retry in order to keep record of failures. No `status` stored within `retriesStatus` will have any `date` within as it is redundant.
-  
+
   - [`sidecars`](tasks.md#using-a-sidecar-in-a-task) - This field is a list. The list has one entry per `sidecar` in the manifest. Each entry represents the imageid of the corresponding sidecar.
   - `spanContext` - Contains tracing span context fields.
-  
-  
+
+
 
 ## Monitoring execution status
 
@@ -860,7 +858,7 @@ False    | TaskRunImagePullFailed | n/a
 
 When a `TaskRun` changes status, [events](events.md#taskruns) are triggered accordingly.
 
-The name of the `Pod` owned by a `TaskRun`  is univocally associated to the owning resource. 
+The name of the `Pod` owned by a `TaskRun`  is univocally associated to the owning resource.
 If a `TaskRun` resource is deleted and created with the same name, the child `Pod` will be created with the same name
 as before. The base format of the name is `<taskrun-name>-pod`. The name may vary according to the logic of
 [`kmeta.ChildName`](https://pkg.go.dev/github.com/knative/pkg/kmeta#ChildName). In case of retries of a `TaskRun`