Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Merged
merged 1 commit into from
Jan 5, 2024
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion docs/additional-configs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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) | |
Expand Down
78 changes: 38 additions & 40 deletions docs/pipelineruns.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -233,7 +233,7 @@ spec:
apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: PipelineRun
metadata:
name: pipelinerun
name: pipelinerun
spec:
pipelineRef:
name: pipeline
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -885,7 +883,7 @@ metadata:
spec:
pipelineRef:
name: mypipeline
taskRunTemplate:
taskRunTemplate:
podTemplate:
securityContext:
runAsNonRoot: true
Expand Down Expand Up @@ -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
Expand All @@ -1020,7 +1018,7 @@ spec:
name: pipeline-name
taskRunSpecs:
- pipelineTaskName: task-name
metadata:
metadata:
labels:
app: cloudevent
```
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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`.
Expand Down
8 changes: 4 additions & 4 deletions docs/pipelines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`.

Expand Down Expand Up @@ -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` |
|-------------|----------------|--------------------------------------------------|---------------------|
Expand Down Expand Up @@ -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
Expand Down
68 changes: 33 additions & 35 deletions docs/taskruns.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -304,10 +304,10 @@ status:
reason: Succeeded
status: "True"
type: Succeeded
...
...
steps:
- container: step-default
...
...
taskSpec:
steps:
- image: ubuntu
Expand All @@ -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.

Expand Down Expand Up @@ -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
```
Expand Down Expand Up @@ -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
```

Expand All @@ -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`.
Expand Down Expand Up @@ -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.
Expand All @@ -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

Expand Down Expand Up @@ -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`
Expand Down
Loading