From 000c4858e241312df89caca311a028be7ab1d166 Mon Sep 17 00:00:00 2001 From: Chuang Wang Date: Tue, 26 Jul 2022 13:41:24 -0700 Subject: [PATCH] [TEP-0075] Add variable usage and links to examples in docs. - Added instructions on how object variables can be used on Pipeline and Task level. - Added links to example yaml files in `docs/tasks.md`. --- docs/tasks.md | 23 ++++++++++------------- docs/variables.md | 3 +++ 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/tasks.md b/docs/tasks.md index 91e73248b92..8f7a6eaaf2b 100644 --- a/docs/tasks.md +++ b/docs/tasks.md @@ -527,14 +527,12 @@ For example, `foo.Is-Bar_` is a valid parameter name for string or array type, b Each declared parameter has a `type` field, which can be set to `string`, `array` or `object` (alpha feature). - `object` type -`object` type is useful in cases where users want to group related parameters. For example, an object parameter called `gitrepo` can contain both the `url` and the `commmit` to group related information. +`object` type is useful in cases where users want to group related parameters. For example, an object parameter called `gitrepo` can contain both the `url` and the `commmit` to group related information. See the [TaskRun example](../examples/v1beta1/taskruns/alpha/object-param-result.yaml) and the [PipelineRun example](../examples/v1beta1/pipelineruns/alpha/pipeline-object-param-and-result.yaml) in which object parameters are used. > NOTE: > - `object` param is an `alpha` feature and gated by the `alpha` feature flag. > - `object` param must specify the `properties` section to define the schema i.e. what keys are available for this object param. See how to define `properties` section in the following example and the [TEP-0075](https://github.com/tektoncd/community/blob/main/teps/0075-object-param-and-result-types.md#defaulting-to-string-types-for-values). - > - When using object in variable replacement, users can only access its individual key ("child" member) of the object by its name i.e. `$(params.gitrepo.url)`. Using an entire object as a value is only allowed when the value is also an object. See more details about using object param from the [TEP-0075](https://github.com/tektoncd/community/blob/main/teps/0075-object-param-and-result-types.md#using-objects-in-variable-replacement). - - + > - When using object in variable replacement, users can only access its individual key ("child" member) of the object by its name i.e. `$(params.gitrepo.url)`. Using an entire object as a value is only allowed when the value is also an object like [this example](https://github.com/tektoncd/pipeline/blob/55665765e4de35b3a4fb541549ae8cdef0996641/examples/v1beta1/pipelineruns/alpha/pipeline-object-param-and-result.yaml#L64-L65). See more details about using object param from the [TEP-0075](https://github.com/tektoncd/community/blob/main/teps/0075-object-param-and-result-types.md#using-objects-in-variable-replacement). - `array` type `array` type is useful in cases where the number of compilation flags being supplied to a task varies throughout the `Task's` execution. @@ -542,9 +540,10 @@ Each declared parameter has a `type` field, which can be set to `string`, `array - `string` type If not specified, the `type` field defaults to `string`. When the actual parameter value is supplied, its parsed type is validated against the `type` field. -The following example illustrates the use of `Parameters` in a `Task`. The `Task` declares two input parameters named `flags` -(of type `array`) and `someURL` (of type `string`), and uses them in the `steps.args` list. You can expand parameters of type `array` -inside an existing array using the star operator. In this example, `flags` contains the star operator: `$(params.flags[*])`. +The following example illustrates the use of `Parameters` in a `Task`. The `Task` declares 3 input parameters named `gitrepo` (of type `object`), `flags` +(of type `array`) and `someURL` (of type `string`). These parameters are used in the `steps.args` list + - For `object` parameter, you can only use individual members (aka keys). + - You can expand parameters of type `array` inside an existing array using the star operator. In this example, `flags` contains the star operator: `$(params.flags[*])`. **Note:** Input parameter values can be used as variables throughout the `Task` by using [variable substitution](#using-variable-substitution). @@ -569,9 +568,6 @@ spec: - name: foo.bar description: "the name contains dot character" default: "test" - results: - - name: echo-output - description: "successful echo" steps: - name: do-the-clone image: some-git-image @@ -591,9 +587,10 @@ spec: ] - name: echo-param image: bash - script: | - set -e - echo $(params["foo.bar"]) | tee $(results.echo-output.path) + args: [ + "echo", + "$(params['foo.bar'])", + ] ``` The following `TaskRun` supplies the value for the parameter `gitrepo`, `flags` and `someURL`: diff --git a/docs/variables.md b/docs/variables.md index 8822015fd4d..ace4bd5a348 100644 --- a/docs/variables.md +++ b/docs/variables.md @@ -25,6 +25,8 @@ For instructions on using variable substitutions see the relevant section of [th | `params.[i]` | Get the i-th element of param array. This is alpha feature, set `enable-api-fields` to `alpha` to use it.| | `params[''][i]` | (see above) | | `params[""][i]` | (see above) | +| `params.[*]` | Get the value of the whole object param. This is alpha feature, set `enable-api-fields` to `alpha` to use it.| +| `params..` | Get the value of an individual child of an object param. This is alpha feature, set `enable-api-fields` to `alpha` to use it. | | `tasks..results.` | The value of the `Task's` result. Can alter `Task` execution order within a `Pipeline`.) | | `tasks..results.[i]` | The ith value of the `Task's` array result. Can alter `Task` execution order within a `Pipeline`.) | | `tasks..results.[*]` | The array value of the `Task's` result. Can alter `Task` execution order within a `Pipeline`. Cannot be used in `script`.) | @@ -51,6 +53,7 @@ For instructions on using variable substitutions see the relevant section of [th | `params.[i]` | Get the i-th element of param array. This is alpha feature, set `enable-api-fields` to `alpha` to use it.| | `params[''][i]` | (see above) | | `params[""][i]` | (see above) | +| `params..` | Get the value of an individual child of an object param. This is alpha feature, set `enable-api-fields` to `alpha` to use it. | | `resources.inputs..path` | The path to the input resource's directory. | | `resources.outputs..path` | The path to the output resource's directory. | | `results..path` | The path to the file where the `Task` writes its results data. |