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 yongxuanzhang@google.com

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) | |

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`.

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 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` |
 |-------------|----------------|--------------------------------------------------|---------------------|

docs/tasks.md

@@ -860,7 +860,7 @@ The stored results can be used [at the `Task` level](./pipelines.md#passing-one-
 or [at the `Pipeline` level](./pipelines.md#emitting-results-from-a-pipeline).
 
 #### Emitting Object `Results`
-Emitting a task result of type `object` is a `beta` feature implemented based on the
+Emitting a task result of type `object` is implemented based on the
 [TEP-0075](https://github.com/tektoncd/community/blob/main/teps/0075-object-param-and-result-types.md#emitting-object-results).
 You can initialize `object` results from a `task` using JSON escaped string. For example, to assign the following data to an object result:
 

pkg/apis/pipeline/v1/pipeline_validation.go

@@ -94,12 +94,6 @@ func (ps *PipelineSpec) Validate(ctx context.Context) (errs *apis.FieldError) {
 // have "enable-api-fields" set to "alpha" or "beta".
 func (ps *PipelineSpec) ValidateBetaFields(ctx context.Context) *apis.FieldError {
  var errs *apis.FieldError
- // Object parameters
- for i, p := range ps.Params {
- if p.Type == ParamTypeObject {
- errs = errs.Also(config.ValidateEnabledAPIFields(ctx, "object type parameter", config.BetaAPIFields).ViaFieldIndex("params", i))
- }
- }
  // Indexing into array parameters
  arrayParamIndexingRefs := ps.GetIndexingReferencesToArrayParams()
  if len(arrayParamIndexingRefs) != 0 {
@@ -109,7 +103,7 @@ func (ps *PipelineSpec) ValidateBetaFields(ctx context.Context) *apis.FieldError
  for i, result := range ps.Results {
  switch result.Type {
  case ResultsTypeObject:
- errs = errs.Also(config.ValidateEnabledAPIFields(ctx, "object results", config.BetaAPIFields).ViaFieldIndex("results", i))
+ // stable feature
  case ResultsTypeArray:
  errs = errs.Also(config.ValidateEnabledAPIFields(ctx, "array results", config.BetaAPIFields).ViaFieldIndex("results", i))
  case ResultsTypeString:

pkg/apis/pipeline/v1/pipeline_validation_test.go

@@ -4221,43 +4221,6 @@ func TestPipelineWithBetaFields(t *testing.T) {
  TaskRef: &TaskRef{ResolverRef: ResolverRef{Resolver: "bar", Params: Params{{}}}},
  }},
  },
- }, {
- name: "object params",
- spec: PipelineSpec{
- Params: []ParamSpec{
- {Name: "first-param", Type: ParamTypeObject, Properties: map[string]PropertySpec{}},
- },
- Tasks: []PipelineTask{{
- Name: "foo",
- TaskRef: &TaskRef{Name: "foo"},
- }},
- },
- }, {
- name: "object params in Tasks",
- spec: PipelineSpec{
- Tasks: []PipelineTask{{
- Name: "valid-pipeline-task",
- TaskSpec: &EmbeddedTask{TaskSpec: TaskSpec{
- Steps: []Step{{Image: "busybox", Script: "echo hello"}},
- Params: []ParamSpec{{Name: "my-object-param", Type: ParamTypeObject, Properties: map[string]PropertySpec{}}},
- }},
- }},
- },
- }, {
- name: "object params in Finally",
- spec: PipelineSpec{
- Tasks: []PipelineTask{{
- Name: "foo",
- TaskRef: &TaskRef{Name: "foo"},
- }},
- Finally: []PipelineTask{{
- Name: "valid-finally-task",
- TaskSpec: &EmbeddedTask{TaskSpec: TaskSpec{
- Steps: []Step{{Image: "busybox", Script: "echo hello"}},
- Params: []ParamSpec{{Name: "my-object-param", Type: ParamTypeObject, Properties: map[string]PropertySpec{}}},
- }},
- }},
- },
  }, {
  name: "array results",
  spec: PipelineSpec{
@@ -4293,41 +4256,6 @@ func TestPipelineWithBetaFields(t *testing.T) {
  }},
  }},
  },
- }, {
- name: "object results",
- spec: PipelineSpec{
- Tasks: []PipelineTask{{
- Name: "valid-pipeline-task",
- TaskRef: &TaskRef{Name: "foo-task"},
- }},
- Results: []PipelineResult{{Name: "my-object-result", Type: ResultsTypeObject, Value: *NewStructuredValues("$(tasks.valid-pipeline-task.results.foo[*])")}},
- },
- }, {
- name: "object results in Tasks",
- spec: PipelineSpec{
- Tasks: []PipelineTask{{
- Name: "valid-pipeline-task",
- TaskSpec: &EmbeddedTask{TaskSpec: TaskSpec{
- Steps: []Step{{Image: "busybox", Script: "echo hello"}},
- Results: []TaskResult{{Name: "my-object-result", Type: ResultsTypeObject, Properties: map[string]PropertySpec{}}},
- }},
- }},
- },
- }, {
- name: "object results in Finally",
- spec: PipelineSpec{
- Tasks: []PipelineTask{{
- Name: "valid-pipeline-task",
- TaskRef: &TaskRef{Name: "foo-task"},
- }},
- Finally: []PipelineTask{{
- Name: "valid-finally-task",
- TaskSpec: &EmbeddedTask{TaskSpec: TaskSpec{
- Steps: []Step{{Image: "busybox", Script: "echo hello"}},
- Results: []TaskResult{{Name: "my-object-result", Type: ResultsTypeObject, Properties: map[string]PropertySpec{}}},
- }},
- }},
- },
  }}
  for _, tt := range tts {
  t.Run(tt.name, func(t *testing.T) {