From bba77ff444b1d82add0f9c1ceee9347275eb1884 Mon Sep 17 00:00:00 2001 From: Dibyo Mukherjee Date: Fri, 6 Oct 2023 17:08:02 -0400 Subject: [PATCH] [TEP-0131] Update Conformance Spec for v1 api types This commit updates the initial api spec from TEP-012 with changes from the conformance policy defined in TEP-131 including: - Using v1 resources instead of v1beta1 types - Conformance specs for Tasks, Pipelines and PipelineRuns in addition to TaskRun - Removes HTTP API requirement from conformance spec, instead the spec is defined in terms of JSON/YAML resources that can be consumed via an API - The RECOMMENDED profile now includes support for taskRefs and pipelineRefs Signed-off-by: Dibyo Mukherjee --- docs/api-spec.md | 636 +++++++++++++++++++++++++++++++---------------- 1 file changed, 423 insertions(+), 213 deletions(-) diff --git a/docs/api-spec.md b/docs/api-spec.md index abe94c89dcb..874b8f41058 100644 --- a/docs/api-spec.md +++ b/docs/api-spec.md @@ -1,40 +1,64 @@ # Tekton Pipelines API Specification -- [Abstract](#abstract) -- [Background](#background) -- [Modifying This Specification](#modifying-this-specification) -- [Resource Overview](#resource-overview) - * [`TaskRun`](#-taskrun-) -- [Detailed Resources - v1beta1](#detailed-resources---v1beta1) - * [`TaskRun`](#-taskrun--1) - + [Metadata](#metadata) - + [Spec](#spec) - + [Status](#status) -- [Status Signalling](#status-signalling) -- [Listing Resources](#listing-resources) -- [Detailed Resource Types - v1beta1](#detailed-resource-types---v1beta1) - * [`ContainerStateRunning`](#containerstaterunning) - * [`ContainerStateWaiting`](#containerstatewaiting) - * [`ContainerStateTerminated`](#containerstateterminated) - * [`EnvVar`](#envvar) - * [`Param`](#param) - * [`ParamSpec`](#paramspec) - * [`ParamValue`](#paramvalue) - * [`Step`](#step) - * [`StepState`](#stepstate) - * [`TaskResult`](#taskresult) - * [`TaskRunResult`](#taskrunresult) - * [`TaskSpec`](#taskspec) - * [`WorkspaceBinding`](#workspacebinding) - * [`WorkspaceDeclaration`](#workspacedeclaration) +- [Tekton Pipelines API Specification](#tekton-pipelines-api-specification) + - [Abstract](#abstract) + - [Background](#background) + - [Modifying This Specification](#modifying-this-specification) + - [Resource Overview - v1](#resource-overview---v1) + - [`Task`](#task) + - [`Pipeline`](#pipeline) + - [`TaskRun`](#taskrun) + - [`PipelineRun`](#pipelinerun) + - [Detailed Resource Types - `v1`](#detailed-resource-types---v1) + - [TypeMeta](#typemeta) + - [ObjectMeta](#objectmeta) + - [TaskSpec](#taskspec) + - [ParamSpec](#paramspec) + - [ParamType](#paramtype) + - [Step](#step) + - [Sidecar](#sidecar) + - [SecurityContext](#securitycontext) + - [TaskResult](#taskresult) + - [ResultsType](#resultstype) + - [PipelineSpec](#pipelinespec) + - [PipelineTask](#pipelinetask) + - [TaskRef](#taskref) + - [ResolverRef](#resolverref) + - [Param](#param) + - [ParamValue](#paramvalue) + - [PipelineResult](#pipelineresult) + - [TaskRunSpec](#taskrunspec) + - [TaskRunStatus](#taskrunstatus) + - [Condition](#condition) + - [StepState](#stepstate) + - [ContainerState](#containerstate) + - [`ContainerStateRunning`](#containerstaterunning) + - [`ContainerStateWaiting`](#containerstatewaiting) + - [`ContainerStateTerminated`](#containerstateterminated) + - [TaskRunResult](#taskrunresult) + - [SidecarState](#sidecarstate) + - [PipelineRunSpec](#pipelinerunspec) + - [PipelineRef](#pipelineref) + - [PipelineRunStatus](#pipelinerunstatus) + - [PipelineRunResult](#pipelinerunresult) + - [ChildStatusReference](#childstatusreference) + - [TimeoutFields](#timeoutfields) + - [WorkspaceDeclaration](#workspacedeclaration) + - [WorkspacePipelineTaskBinding](#workspacepipelinetaskbinding) + - [PipelineWorkspaceDeclaration](#pipelineworkspacedeclaration) + - [WorkspaceBinding](#workspacebinding) + - [EnvVar](#envvar) + - [Status Signalling](#status-signalling) ## Abstract -The Tekton Pipelines platform provides common abstractions for describing and executing container-based, run-to-completion workflows, typipcally in service of CI/CD scenarios. This document describes the structure, lifecycle and management of Tekton resources in the context of the [Kubernetes Resource Model](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/architecture/resource-management.md). An understanding of the Kubernetes API interface and the capabilities of [Kubernetes Custom Resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) is assumed. +The Tekton Pipelines platform provides common abstractions for describing and executing container-based, run-to-completion workflows, typically in service of CI/CD scenarios. The Tekton Conformance Policy defines the requirements that Tekton implementations must meet to claim conformance with the Tekton API. [TEP-0131](https://github.com/tektoncd/community/blob/main/teps/0131-tekton-conformance-policy.md) lay out details of the policy itself. -This document does not define the [runtime contract](https://tekton.dev/docs/pipelines/container-contract/) nor prescribe specific implementations of supporting services such as access control, observability, or resource management. +According to the policy, Tekton implementations can claim Conformance on GA Primitives, thus, all API Spec in this doc is for Tekton V1 APIs. Implementations are only required to provide resource management (i.e. CRUD APIs) for Runtime Primitives (TaskRun and PipelineRun). For Authoring-time Primitives (Task and Pipeline), supporting CRUD APIs is not a requirement but we recommend referencing them in runtime types (e.g. from git, catalog, within the cluster etc.) + +This document describes the structure, and lifecycle of Tekton resources. This document does not define the [runtime contract](https://tekton.dev/docs/pipelines/container-contract/) nor prescribe specific implementations of supporting services such as access control, observability, or resource management. This document makes reference in a few places to different profiles for Tekton installations. A profile in this context is a set of operations, resources, and fields that are accessible to a developer interacting with a Tekton installation. Currently, only a single (minimal) profile for Tekton Pipelines is defined, but additional profiles may be defined in the future to standardize advanced functionality. A minimal profile is one that implements all of the “MUST”, “MUST NOT”, and “REQUIRED” conditions of this document. @@ -48,269 +72,455 @@ There is no formal specification of the Kubernetes API and Resource Model. This This spec is a living document, meaning new resources and fields may be added, and may transition from being OPTIONAL to RECOMMENDED to REQUIRED over time. In general a resource or field should not be added as REQUIRED directly, as this may cause unsuspecting previously-conformant implementations to suddenly no longer be conformant. These should be first OPTIONAL or RECOMMENDED, then change to be REQUIRED once a survey of conformant implementations indicates that doing so will not cause undue burden on any implementation. -## Resource Overview +## Resource Overview - v1 + +The following schema defines a set of REQUIRED or RECOMMENDED resource fields on the Tekton resource types. Whether a field is REQUIRED or RECOMMENDED is denoted in the "Requirement" column. + +Additional fields MAY be provided by particular implementations, however it is expected that most extension will be accomplished via the `metadata.labels` and `metadata.annotations` fields, as Tekton implementations MAY validate supplied resources against these fields and refuse resources which specify unknown fields. + +Tekton implementations MUST NOT require `spec` fields outside this implementation; to do so would break interoperability between such implementations and implementations which implement validation of field names. + +**NB:** All fields and resources not listed below are assumed to be **OPTIONAL**, not RECOMMENDED or REQUIRED. + +### `Task` -The Tekton Pipelines API provides a set of API resources to manage run-to-completion workflows. Those are expressed as [Kubernetes Custom Resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) +A Task is a collection of Steps that is defined and arranged in a sequential order of execution. + +| Field | Type | Requirement | Notes | +| ------------ | --------------------------- | ----------- | ---------------------------------------------- | +| `kind` | string | RECOMMENDED | Describes the type of the resource i.e. `Task` | +| `apiVersion` | string | RECOMMENDED | Schema version i.e. `v1` | +| `metadata` | [`ObjectMeta`](#objectmeta) | REQUIRED | Common metadata about a resource | +| `spec` | [`TaskSpec`](#taskspec) | REQUIRED | Defines the desired state of Task. | + +**NB:** If `kind` and `apiVersion` are not supported, an alternative method of identifying the type of resource must be supported. + +### `Pipeline` + +A Pipeline is a collection of Tasks that is defined and arranged in a specific order of execution + +| Field | Type | Requirement | Notes | +| ------------ | ------------------------------- | ----------- | -------------------------------------------------- | +| `kind` | string | RECOMMENDED | Describes the type of the resource i.e. `Pipeline` | +| `apiVersion` | string | RECOMMENDED | Schema version i.e. `v1` | +| `metadata` | [`ObjectMeta`](#objectmeta) | REQUIRED | Common metadata about a resource | +| `spec` | [`PipelineSpec`](#pipelinespec) | REQUIRED | Defines the desired state of Pipeline. | + +**NB:** If `kind` and `apiVersion` are not supported, an alternative method of identifying the type of resource must be supported. ### `TaskRun` A `TaskRun` represents an instantiation of a single execution of a `Task`. It can describe the steps of the Task directly. -Its HTTP API endpoint is `/apis/tekton.dev/v1beta1/[parent]/taskruns`, where `[parent]` can refer to any string identifying a grouping of `TaskRun`s. +| Field | Type | Requirement | Notes | +| ------------ | --------------------------------- | ----------- | ------------------------------------------------ | +| `kind` | string | RECOMMENDED | Describes the type of the resource i.e.`TaskRun` | +| `apiVersion` | string | RECOMMENDED | Schema version i.e. `v1` | +| `metadata` | [`ObjectMeta`](#objectmeta) | REQUIRED | Common metadata about a resource | +| `spec` | [`TaskRunSpec`](#taskrunspec) | REQUIRED | Defines the desired state of TaskRun | +| `status` | [`TaskRunStatus`](#taskrunstatus) | REQUIRED | Defines the current status of TaskRun | -For example, in the Kubernetes implementation `[parent]` refers to a Kubernetes namespace. Other implementations could interpret the string differently, including enabling hierarchies of resources containing `TaskRun`s, for example the API endpoint `/apis/tekton.dev/v1beta1/folders/my-folder/project/my-project/taskruns` could represent a hierarchy of "projects" that own `TaskRun`s. +**NB:** If `kind` and `apiVersion` are not supported, an alternative method of identifying the type of resource must be supported. -| HTTP Verb | Requirement | -|---------------------------|------------------| -| Create (POST) | REQUIRED | -| Patch (PATCH)* | RECOMMENDED | -| Replace (PUT)** | RECOMMENDED | -| Delete (DELETE) | OPTIONAL | -| Read (GET) | REQUIRED | -| List (GET) | REQUIRED | -| Watch (GET) | OPTIONAL | -| DeleteCollection (DELETE) | OPTIONAL | +### `PipelineRun` -\* Kubernetes only allows JSON merge patch for CRD types. It is recommended that if allowed, at least JSON Merge patch be made available. [JSON Merge Patch Spec (RFC 7386)](https://tools.ietf.org/html/rfc7386) +A `PipelineRun` represents an instantiation of a single execution of a `Pipeline`. It can describe the spec of the Pipeline directly. -\** NB: Support for cancellation depends on `Replace`. +| Field | Type | Requirement | Notes | +| ------------ | ----------------------------------------- | ----------- | ---------------------------------------------------- | +| `kind` | string | RECOMMENDED | Describes the type of the resource i.e.`PipelineRun` | +| `apiVersion` | string | RECOMMENDED | Schema version i.e. `v1` | +| `metadata` | [`ObjectMeta`](#objectmeta) | REQUIRED | Common metadata about a resource | +| `spec` | [`PipelineRunSpec`](#pipelinerunspec) | REQUIRED | Defines the desired state of PipelineRun | +| `status` | [`PipelineRunStatus`](#pipelinerunstatus) | REQUIRED | Defines the current status of PipelineRun | -## Detailed Resources - v1beta1 +**NB:** If `kind` and `apiVersion` are not supported, an alternative method of identifying the type of resource must be supported. -The following schema defines a set of REQUIRED or RECOMMENDED resource fields on the Tekton resource types. Whether a field is REQUIRED or RECOMMENDED is denoted in the "Requirement" column. +## Detailed Resource Types - `v1` -Additional fields MAY be provided by particular implementations, however it is expected that most extension will be accomplished via the `metadata.labels` and `metadata.annotations` fields, as Tekton implementations MAY validate supplied resources against these fields and refuse resources which specify unknown fields. +### TypeMeta -Tekton implementations MUST NOT require `spec` fields outside this implementation; to do so would break interoperability between such implementations and implementations which implement validation of field names. +Derived from [Kuberentes Type Meta](https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#TypeMeta) -**NB:** All fields and resources not listed below are assumed to be **OPTIONAL**, not RECOMMENDED or REQUIRED. For example, at this time, support for `PipelineRun`s and for CRUD operations on `Task`s or `Pipeline`s is **OPTIONAL**. +| Field | Type | Notes | +| ------------ | ------ | ----------------------------------------------------------------- | +| `kind` | string | A string value representing the resource this object represents. | +| `apiVersion` | string | Defines the versioned schema of this representation of an object. | -### `TaskRun` +### ObjectMeta -#### Metadata +Derived from standard Kubernetes [meta.v1/ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.18/#objectmeta-v1-meta) resource. -Standard Kubernetes [meta.v1/ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.18/#objectmeta-v1-meta) resource. +| Field Name | Field Type | Requirement | Notes | +| ------------------- | ------------------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `name` | string | REQUIRED | Mutually exclusive with the `generateName` field | +| `labels` | map | RECOMMENDED | | +| `annotations` | map | RECOMMENDED | | +| `creationTimestamp` | string | REQUIRED (see note) | `creationTimestamp` MUST be populated by the implementation, in [RFC3339](https://tools.ietf.org/html/rfc3339). The field is required for any runtimeTypes such as `TaskRun` and `PipelineRun` and RECOMMENDED for othet types. | +| `uid` | string | RECOMMENDED | | +| `resourceVersion` | string | OPTIONAL | | +| `generation` | int64 | OPTIONAL | | +| `namespace` | string | RECOMMENDED | | +| `generateName` | string | RECOMMENDED | If supported by the implementation, when `generateName` is specified at creation, it MUST be prepended to a random string and set as the `name`, and not set on the subsequent response. | -| Field Name | Field Type | Requirement | -|----------------------|--------------------|-------------| -| `name` | string | REQUIRED | -| `labels` | map | REQUIRED | -| `annotations` | map | REQUIRED | -| `creationTimestamp`* | string | REQUIRED | -| `uid` | string | RECOMMENDED | -| `resourceVersion` | string | RECOMMENDED | -| `generation` | int64 | RECOMMENDED | -| `namespace` | string | RECOMMENDED | -| `generateName`** | string | RECOMMENDED | +### TaskSpec -\* `creationTimestamp` MUST be populated by the implementation, in [RFC3339](https://tools.ietf.org/html/rfc3339). +Defines the desired state of Task -** If `generateName` is supported by the implementation, when it is specified at creation, it MUST be prepended to a random string and set as the `name`, and not set on the subsequent response. +| Field | Type | Requirement | Notes | +| ------------- | ------------------------------------------------- | ----------- | ----- | +| `description` | string | REQUIRED | | +| `params` | [][`ParamSpec`](#paramspec) | REQUIRED | | +| `steps` | [][`Step`](#step) | REQUIRED | | +| `sidecars` | [][`Sidecar`](#sidecar) | REQUIRED | | +| `results` | [][`TaskResult`](#taskresult) | REQUIRED | | +| `workspaces` | [][`WorkspaceDeclaration`](#workspacedeclaration) | REQUIRED | | -#### Spec +### ParamSpec -| Field Name | Field Type | Requirement | -|-----------------------|----------------------|-------------| -| `params` | `[]Param` | REQUIRED | -| `taskSpec` | `TaskSpec` | REQUIRED | -| `workspaces` | `[]WorkspaceBinding` | REQUIRED | -| `status` | Enum:
- `""` (default)
- `"TaskRunCancelled"` | RECOMMENDED | -| `timeout` | string (duration) | RECOMMENDED | -| `serviceAccountName`^ | string | RECOMMENDED | +Declares a parameter whose value has to be provided at runtime -^ In the Kubernetes implementation, `serviceAccountName` refers to a Kubernetes `ServiceAccount` resource that is assumed to exist in the same namespace. Other implementations MAY interpret this string differently, and impose other requirements on specified values. +| Field Name | Field Type | Requirement | Notes | +| ------------- | --------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `name` | string | REQUIRED | | +| `description` | string | REQUIRED | | +| `type` | [`ParamType`](#paramtype) | REQUIRED (see note) | The values `string` and `array` for this field are REQUIRED, and the value `object` is RECOMMENDED. | +| `properties` | map | RECOMMENDED | `PropertySpec` is a type that defines the spec of an individual key. See how to define the `properties` section in the [example](../examples/v1/taskruns/beta/object-param-result.yaml). | +| `default` | [`ParamValue`](#paramvalue) | REQUIRED | | -#### Status +### ParamType -| Field Name | Field Type | Requirement | -|-----------------------|------------------------|-------------| -| `conditions` | see [#error-signaling] | REQUIRED | -| `startTime` | string | REQUIRED | -| `completionTime`* | string | REQUIRED | -| `steps` | `[]StepState` | REQUIRED | -| `taskResults` | `[]TaskRunResult` | REQUIRED | -| `taskSpec` | `TaskSpec` | REQUIRED | -| `observedGeneration` | int64 | RECOMMENDED | +Defines the type of a parameter -\* `startTime` and `completionTime` MUST be populated by the implementation, in [RFC3339](https://tools.ietf.org/html/rfc3339). +string enum, allowed values are `string`, `array`, and `object`. Supporting `string` and `array` are required while the other types are optional for conformance. -## Status Signalling +### Step -The Tekton Pipelines API uses the [Kubernetes Conditions convention](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#typical-status-properties) to communicate status and errors to the user. +A Step is a reference to a container image that executes a specific tool on a specific input and produces a specific output. +**NB:** All other fields inherited from the [core.v1/Container](https://godoc.org/k8s.io/api/core/v1#Container) type supported by the Kubernetes implementation are **OPTIONAL** for the purposes of this spec. -`TaskRun`'s `status` field MUST have a `conditions` field, which must be a list of `Condition` objects of the following form: +| Field Name | Field Type | Requirement | Notes | +| ------------ | --------------------- | ----------- | ----- | +| `name` | string | REQUIRED | | +| `image` | string | REQUIRED | | +| `args` | []string | REQUIRED | | +| `command` | []string | REQUIRED | | +| `workingDir` | []string | REQUIRED | | +| `env` | [][`EnvVar`](#envvar) | REQUIRED | | +| `script` | string | REQUIRED | | -| Field | Type | Requirement | -|-----------------------|--------|-------------| -| `type` | string | REQUIRED | -| `status` | Enum:
- `"True"`
- `"False"`
- `"Unknown"` (default) | REQUIRED | -| `reason` | string | REQUIRED | -| `message` | string | REQUIRED | -| `severity` | Enum:
- `""` (default)
- `"Warning"`
- `"Info"` | REQUIRED | -| `lastTransitionTime`* | string | OPTIONAL | +### Sidecar -\* If `lastTransitionTime` is populated by the implementation, it must be in [RFC3339](https://tools.ietf.org/html/rfc3339). +Specifies a list of containers to run alongside the Steps in a Task. If sidecars are supported, the following fields are required: -Additionally, the resource's `status.conditions` field MUST be managed as follows to enable clients to present useful diagnostic and error information to the user. +| Field | Type | Requirement | Notes | +| ----------------- | ------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------- | +| `name` | string | REQUIRED | Name of the Sidecar specified as a DNS_LABEL. Each Sidecar in a Task must have a unique name (DNS_LABEL).Cannot be updated. | +| `image` | string | REQUIRED | [Container image name](https://kubernetes.io/docs/concepts/containers/images/#image-names) | +| `command` | []string | REQUIRED | Entrypoint array. Not executed within a shell. The image's ENTRYPOINT is used if this is not provided. | +| `args` | []string | REQUIRED | Arguments to the entrypoint. The image's CMD is used if this is not provided. | +| `script` | string | REQUIRED | Script is the contents of an executable file to execute. If Script is not empty, the Sidecar cannot have a Command or Args. | +| `securityContext` | [`SecurityContext`](#securitycontext) | REQUIRED | Defines the security options the Sidecar should be run with. | -If a resource describes that it must report a Condition of the `type` `Succeeded`, then it must report it in the following manner: +### SecurityContext -* If the `status` field is `"True"`, that means the execution finished successfully. -* If the `status` field is `"False"`, that means the execution finished unsuccessfully -- the Condition's `reason` and `message` MUST include further diagnostic information. -* If the `status` field is `"Unknown"`, that means the execution is still ongoing, and clients can check again later until the Condition's `status` reports either `"True"` or `"False"`. +All other fields derived from [core.v1/SecurityContext](https://pkg.go.dev/k8s.io/api/core/v1#SecurityContext) are OPTIONAL for the purposes of this spec. -Resources MAY report Conditions with other `type`s, but none are REQUIRED or RECOMMENDED. +| Field | Type | Requirement | Notes | +| ------------ | ---- | ----------- | ---------------------------------------------------- | +| `privileged` | bool | REQUIRED | Run the sidecar in privileged mode. Default to false | -## Listing Resources +### TaskResult -Requests to list resources specify the following fields (based on [`meta.v1/ListOptions`](https://godoc.org/k8s.io/apimachinery/pkg/apis/meta/v1#ListOptions)): +Defines a result produced by a Task -| Field Name | Field Type | Requirement | -|-------------------|------------|-------------| -| `continue` | string | REQUIRED | -| `limit` | int64 | REQUIRED | +| Field | Type | Requirement | Notes | +| ------------- | ----------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `name` | string | REQUIRED | Declares the name by which a parameter is referenced. | +| `type` | [`ResultsType`](#resultstype) | REQUIRED | Type is the user-specified type of the result. The values `string` this field is REQUIRED, and the values `array` and `object` are RECOMMENDED. | +| `description` | string | RECOMMENDED | Description of the result | +| `properties` | map | RECOMMENDED | `PropertySpec` is a type that defines the spec of an individual key. See how to define the `properties` section in the [example](../examples/v1/taskruns/beta/object-param-result.yaml). | -List responses have the following fields (based on [`meta.v1/ListMeta`](https://godoc.org/k8s.io/apimachinery/pkg/apis/meta/v1#ListMeta)): +### ResultsType -| Field Name | Field Type | Requirement | -|----------------------|------------|-------------| -| `continue` | string | REQUIRED | -| `items` | `[]Object` | REQUIRED | -| `remainingItemCount` | int64 | REQUIRED | -| `apiVersion` | string
(`"tekton.dev/v1beta1"`) | REQUIRED | -| `kind` | string
(e.g., `"ObjectList"`) | REQUIRED | +ResultsType indicates the type of a result. -**NB:** All other fields inherited from [`ListOptions`] or [`ListMeta`]supported by the Kubernetes implementation (e.g., `fieldSelector`, `labelSelector`) are **OPTIONAL** for the purposes of this spec. +string enum, Allowed values are `string`, `array`, and `object`. Supporting `string` is required while the other types are optional for conformance. -**NB:** The sort order of items returned by list requests is unspecified at this time. +### PipelineSpec -## Detailed Resource Types - v1beta1 +Defines a pipeline -### `ContainerStateRunning` +| Field | Type | Requirement | Notes | +| ------------ | ----------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------ | +| `params` | [][`ParamSpec`](#paramspec) | REQUIRED | Params declares a list of input parameters that must be supplied when this Pipeline is run. | +| `tasks` | [][`PipelineTask`](#pipelinetask) | REQUIRED | Tasks declares the graph of Tasks that execute when this Pipeline is run. | +| `results` | [][`PipelineResult`](#pipelineresult) | REQUIRED | Values that this pipeline can output once run. | +| `finally` | [][`PipelineTask`](#pipelinetask) | REQUIRED | The list of Tasks that execute just before leaving the Pipeline | +| `workspaces` | [][`PipelineWorkspaceDeclaration`](#pipelineworkspacedeclaration) | REQUIRED | Workspaces declares a set of named workspaces that are expected to be provided by a PipelineRun. | + +### PipelineTask + +PiplineTask defines a task in a Pipeline, passing inputs from both `Params`` and from the output of previous tasks. + +| Field | Type | Requirement | Notes | +| ------------ | ----------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `name` | string | REQUIRED | The name of this task within the context of a Pipeline. Used as a coordinate with the from and runAfter fields to establish the execution order of tasks relative to one another. | +| `taskRef` | [`TaskRef`](#taskref) | RECOMMENDED | TaskRef is a reference to a task definition. Mutually exclusive with TaskSpec | +| `taskSpec` | [`TaskSpec`](#taskspec) | REQUIRED | TaskSpec is a specification of a task. Mutually exclusive with TaskRef | +| `runAfter` | []string | REQUIRED | RunAfter is the list of PipelineTask names that should be executed before this Task executes. (Used to force a specific ordering in graph execution.) | +| `params` | [][`Param`](#param) | REQUIRED | Declares parameters passed to this task. | +| `workspaces` | [][`WorkspacePipelineTaskBinding`](#workspacepipelinetaskbinding) | REQUIRED | Workspaces maps workspaces from the pipeline spec to the workspaces declared in the Task. | +| `timeout` | int64 | REQUIRED | Time after which the TaskRun times out. Setting the timeout to 0 implies no timeout. There isn't a default max timeout set. | + +### TaskRef + +Refers to a Task. Tasks should be referred either by a name or by using the Remote Resolution framework. + +| Field | Type | Requirement | Notes | +| ---------- | ------------------- | ----------- | ----------------------- | +| `name` | string | RECOMMENDED | Name of the referent. | +| `resolver` | string | RECOMMENDED | A field of ResolverRef. | +| `params` | [][`Param`](#param) | RECOMMENDED | A field of ResolverRef. | + +### ResolverRef -| Field Name | Field Type | Requirement | -|--------------|------------|-------------| -| `startedAt`* | string | REQUIRED | +| Field | Type | Requirement | Notes | +| ---------- | ------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------- | +| `resolver` | string | RECOMMENDED | Resolver is the name of the resolver that should perform resolution of the referenced Tekton resource, such as "git". | +| `params` | [][`Param`](#param) | RECOMMENDED | Contains the parameters used to identify the referenced Tekton resource. | -\* `startedAt` MUST be populated by the implementation, in [RFC3339](https://tools.ietf.org/html/rfc3339). +### Param + +Provides a value for the named paramter. + +| Field | Type | Requirement | Notes | +| ------- | --------------------------- | ----------- | ----- | +| `name` | string | REQUIRED | | +| `value` | [`ParamValue`](#paramvalue) | REQUIRED | | + +### ParamValue + +A `ParamValue` may be a string, a list of string, or a map of string to string. + +### PipelineResult + +| Field | Type | Requirement | Notes | +| ------- | ----------------------------- | ----------- | ----- | +| `name` | string | REQUIRED | | +| `type` | [`ResultsType`](#resultstype) | REQUIRED | | +| `value` | [`ParamValue`](#paramvalue) | REQUIRED | | + +### TaskRunSpec + +| Field | Type | Requirement | Notes | +| --------------------- | --------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `params` | [][`Param`](#param) | REQUIRED | | +| `taskRef` | [`TaskRef`](#taskref) | REQUIRED | | +| `taskSpec` | [`TaskSpec`](#taskspec) | REQUIRED | | +| `workspaces` | [][`WorkspaceBinding`](#workspacebinding) | REQUIRED | | +| `timeout` | string (duration) | REQUIRED | Time after which one retry attempt times out. Defaults to 1 hour. | +| `status` | Enum:
- `""` (default)
- `"TaskRunCancelled"` | RECOMMENDED | | +| `serviceAccountName`^ | string | RECOMMENDED | In the Kubernetes implementation, `serviceAccountName` refers to a Kubernetes `ServiceAccount` resource that is assumed to exist in the same namespace. Other implementations MAY interpret this string differently, and impose other requirements on specified values. | + +### TaskRunStatus + +| Field | Type | Requirement | Notes | +| -------------------- | ----------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------- | +| `conditions` | [][`Condition`](#condition) | REQUIRED | Condition type `Succeeded` MUST be populated. See [Status Signalling](#status-signalling) for details. Other types are OPTIONAL | +| `startTime` | string | REQUIRED | MUST be populated by the implementation, in [RFC3339](https://tools.ietf.org/html/rfc3339). | +| `completionTime` | string | REQUIRED | MUST be populated by the implementation, in [RFC3339](https://tools.ietf.org/html/rfc3339). | +| `taskSpec` | [`TaskSpec`](#taskspec) | REQUIRED | | +| `steps` | [][`StepState`](#stepstate) | REQUIRED | | +| `results` | [][`TaskRunResult`](#taskrunresult) | REQUIRED | | +| `sidecars` | [][`SidecarState`](#sidecarstate) | RECOMMENDED | | +| `observedGeneration` | int64 | RECOMMENDED | | + +### Condition + +| Field | Type | Requirement | Notes | +| --------- | ------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `type` | string | REQUIRED | Required values:
`Succeeded`: specifies that the resource has finished.
Other OPTIONAL values:
`TaskRunResultsVerified`
`TrustedResourcesVerified` | +| `status` | string | REQUIRED | Valid values:
"UNKNOWN": .
"TRUE"
"FALSE". (Also see [Status Signalling](#status-signalling)) | +| `reason` | string | REQUIRED | The reason for the condition's last transition. | +| `message` | string | RECOMMENDED | Message describing the status and reason. | + +### StepState + +| Field | Type | Requirement | Notes | +| ---------------- | ----------------------------------- | ----------- | ------------------------- | +| `name` | string | REQUIRED | Name of the StepState. | +| `imageID` | string | REQUIRED | Image ID of the StepState | +| `containerState` | [`ContainerState`](#containerstate) | REQUIRED | State of the container | + +### ContainerState + +| Field | Type | Requirement | Notes | +| ------------ | ---------------------------- | ----------- | ------------------------------------ | +| `waiting` | [`ContainerStateWaiting`] | REQUIRED | Details about a waiting container | +| `running` | [`ContainerStateRunning`] | REQUIRED | Details about a running container | +| `terminated` | [`ContainerStateTerminated`] | REQUIRED | Details about a terminated container | + +\* Only one of `waiting`, `running` or `terminated` can be returned at a time. + +### `ContainerStateRunning` + +| Field Name | Field Type | Requirement | Notes | +| ------------ | ---------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `startedAt`* | string | REQUIRED | Time at which the container was last (re-)started.`startedAt` MUST be populated by the implementation, in [RFC3339](https://tools.ietf.org/html/rfc3339). | ### `ContainerStateWaiting` -| Field Name | Field Type | Requirement | -|------------|------------|-------------| -| `reason` | string | REQUIRED | -| `message` | string | REQUIRED | +| Field Name | Field Type | Requirement | Notes | +| ---------- | ---------- | ----------- | ------------------------------------------------------- | +| `reason` | string | REQUIRED | Reason the container is not yet running. | +| `message` | string | RECOMMENDED | Message regarding why the container is not yet running. | ### `ContainerStateTerminated` -| Field Name | Field Type | Requirement | -|---------------|------------|-------------| -| `exitCode` | int32 | REQUIRED | -| `reason` | string | REQUIRED | -| `message` | string | REQUIRED | -| `startedAt`* | string | REQUIRED | -| `finishedAt`* | string | REQUIRED | +| Field Name | Field Type | Requirement | Notes | +| ------------- | ---------- | ----------- | ------------------------------------------------------- | +| `exitCode` | int32 | REQUIRED | Exit status from the last termination of the container. | +| `reason` | string | REQUIRED | Reason from the last termination of the container. | +| `message` | string | RECOMMENDED | Message regarding the last termination of the container | +| `startedAt`* | string | REQUIRED | Time at which the container was last (re-)started. | +| `finishedAt`* | string | REQUIRED | Time at which the container last terminated. | \* `startedAt` and `finishedAt` MUST be populated by the implementation, in [RFC3339](https://tools.ietf.org/html/rfc3339). -### `EnvVar` +### TaskRunResult -| Field Name | Field Type | Requirement | -|------------|------------|-------------| -| `name` | string | REQUIRED | -| `value` | string | REQUIRED | +| Field | Type | Requirement | Notes | +| ------- | ----------------------------- | ----------- | ----- | +| `name` | string | REQUIRED | | +| `type` | [`ResultsType`](#resultstype) | REQUIRED | | +| `value` | [`ParamValue`](#paramvalue) | REQUIRED | | -**NB:** All other [EnvVar](https://godoc.org/k8s.io/api/core/v1#EnvVar) types inherited from [core.v1/EnvVar](https://godoc.org/k8s.io/api/core/v1#EnvVar) and supported by the Kubernetes implementation (e.g., `valueFrom`) are **OPTIONAL** for the purposes of this spec. +### SidecarState -### `Param` +| Field | Type | Requirement | Notes | +| ---------------- | ----------------------------------- | ----------- | ----------------------------- | +| `name` | string | RECOMMENDED | Name of the SidecarState. | +| `imageID` | string | RECOMMENDED | Image ID of the SidecarState. | +| `containerState` | [`ContainerState`](#containerstate) | RECOMMENDED | State of the container. | -| Field Name | Field Type | Requirement | -|------------|-----------------|-------------| -| `name` | string | REQUIRED | -| `value` | `ParamValue` | REQUIRED | +### PipelineRunSpec -### `ParamSpec` +| Field | Type | Requirement | Notes | +| -------------- | --------------------------------------- | ----------- | ---------------------------------------- | +| `params` | [][`Param`](#param) | REQUIRED | | +| `pipelineRef` | [`PipelineRef`](#pipelineref) | RECOMMENDED | | +| `pipelineSpec` | [`PipelineSpec`](#pipelinespec) | REQUIRED | | +| `timeouts` | [`TimeoutFields`](#timeoutfields) | REQUIRED | Time after which the Pipeline times out. | +| `workspaces` | [`WorkspaceBinding`](#workspacebinding) | REQUIRED | | -| Field Name | Field Type | Requirement | -|---------------|------------|-------------| -| `name` | string | REQUIRED | -| `description` | string | REQUIRED | -| `type` | Enum:
- `"string"` (default)
- `"array"`
- `"object"` | REQUIRED (The values `string` and `array` for this field are REQUIRED, and the value `object` is RECOMMENDED.) | -| `properties` | map |RECOMMENDED

note: `PropertySpec` is a type that defines the spec of an individual key. See how to define the `properties` section in the [example](../examples/v1/taskruns/beta/object-param-result.yaml).| -| `default` | `ParamValue` | REQUIRED | +### PipelineRef -### `ParamValue` +| Field | Type | Requirement | Note | +| ---------- | ----------------- | ----------- | ----------------------- | +| `name` | string | RECOMMENDED | Name of the referent. | +| `resolver` | string | RECOMMENDED | A field of ResolverRef. | +| `params` | [][Param](#param) | RECOMMENDED | A field of ResolverRef. | -A `ParamValue` may be a string, a list of string, or a map of string to string. +### PipelineRunStatus -### `Step` +| Field | Type | Requirement | Notes | +| ----------------- | ----------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------- | +| `conditions` | [][`Condition`](#condition) | REQUIRED | Condition type `Succeeded` MUST be populated. See [Status Signalling](#status-signalling) for details. Other types are OPTIONAL | +| `startTime` | string | REQUIRED | MUST be populated by the implementation, in [RFC3339](https://tools.ietf.org/html/rfc3339). | +| `completionTime` | string | REQUIRED | MUST be populated by the implementation, in [RFC3339](https://tools.ietf.org/html/rfc3339). | +| `pipelineSpec` | [`PipelineSpec`](#pipelinespec) | RECOMMEDED | Resolved spec of the pipeline that was executed | +| `results` | [][`PipelineRunResult`](#pipelinerunresult) | RECOMMENDED | Results produced from the pipeline | +| `childReferences` | [][ChildStatusReference](#childstatusreference) | REQUIRED | References to any child Runs created as part of executing the pipelinerun | -| Field Name | Field Type | Requirement | -|--------------|------------|-------------| -| `name` | string | REQUIRED | -| `image` | string | REQUIRED | -| `args` | []string | REQUIRED | -| `command` | []string | REQUIRED | -| `workingDir` | []string | REQUIRED | -| `env` | `[]EnvVar` | REQUIRED | -| `script` | string | REQUIRED | +### PipelineRunResult -**NB:** All other fields inherited from the [core.v1/Container](https://godoc.org/k8s.io/api/core/v1#Container) type supported by the Kubernetes implementation are **OPTIONAL** for the purposes of this spec. +| Field | Type | Requirement | Notes | +| ------- | --------------------------- | ----------- | ------------------------------------------------------------------- | +| `name` | string | RECOMMENDED | Name is the result's name as declared by the Pipeline | +| `value` | [`ParamValue`](#paramvalue) | RECOMMENDED | Value is the result returned from the execution of this PipelineRun | -### `StepState` +### ChildStatusReference -| Field Name | Field Type | Requirement | -|---------------|----------------------------|-------------| -| `name` | string | REQUIRED | -| `imageID` | string | REQUIRED | -| `waiting`* | `ContainerStateWaiting` | REQUIRED | -| `running`* | `ContainerStateRunning` | REQUIRED | -| `terminated`* | `ContainerStateTerminated` | REQUIRED | +| Field | Type | Requirement | Notes | +| ------------------ | ------ | ----------- | --------------------------------------------------------------------- | +| `Name` | string | REQUIRED | Name is the name of the TaskRun this is referencing. | +| `PipelineTaskName` | string | REQUIRED | PipelineTaskName is the name of the PipelineTask this is referencing. | -\* Only one of `waiting`, `running` or `terminated` can be returned at a time. +### TimeoutFields + +| Field | Type | Requirement | Notes | +| ---------- | ----------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `Pipeline` | string (duration) | REQUIRED | Pipeline sets the maximum allowed duration for execution of the entire pipeline. The sum of individual timeouts for tasks and finally must not exceed this value. | +| `Tasks` | string (duration) | REQUIRED | Tasks sets the maximum allowed duration of this pipeline's tasks | +| `Finally` | string (duration) | REQUIRED | Finally sets the maximum allowed duration of this pipeline's finally | + +**string (duration)** : A duration string is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as "300ms", "-1.5h" or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h" + +**Note:** Currently three keys are accepted in the map: pipeline, tasks and finally. Timeouts.pipeline >= Timeouts.tasks + Timeouts.finally -### `TaskResult` +### WorkspaceDeclaration -| Field Name | Field Type | Requirement | -|--------------|------------|-------------| -| `name` | string | REQUIRED | -| `description` | string | REQUIRED | -| `type` | Enum:
- `"string"` (default)
- `"array"`
- `"object"` | RECOMMENDED (Each of the values is RECOMMENDED.)| -| `properties` | map | RECOMMENDED

note: `PropertySpec` is a type that defines the spec of an individual key. See how to define the `properties` section in the [example](../examples/v1/taskruns/beta/object-param-result.yaml).| +| Field | Type | Requirement | Notes | +| ------------- | ------- | ----------- | ------------------------------------------------------------- | +| `name` | string | REQUIRED | Name is the name by which you can bind the volume at runtime. | +| `description` | string | RECOMMENDED | | +| `mountPath` | string | RECOMMENDED | | +| `readOnly` | boolean | RECOMMENDED | Defaults to false. | -### `TaskRunResult` +### WorkspacePipelineTaskBinding -| Field Name | Field Type | Requirement | -|------------|------------|-------------| -| `name` | string | REQUIRED | -| `type` | Enum:
- `"string"` (default)
- `"array"`
- `"object"` | RECOMMENDED (Each of the values is RECOMMENDED.) | -| `value` | `ParamValue` | REQUIRED | +| Field | Type | Requirement | Notes | +| ----------- | ------ | ----------- | --------------------------------------------------------------- | +| `name` | string | REQUIRED | Name is the name of the workspace as declared by the task | +| `workspace` | string | REQUIRED | Workspace is the name of the workspace declared by the pipeline | -### `TaskSpec` +### PipelineWorkspaceDeclaration -| Field Name | Field Type | Requirement | -|---------------|--------------------------|-------------| -| `params` | `[]ParamSpec` | REQUIRED | -| `steps` | `[]Step` | REQUIRED | -| `results` | `[]TaskResult` | REQUIRED | -| `workspaces` | `[]WorkspaceDeclaration` | REQUIRED | -| `description` | string | REQUIRED | +| Field | Type | Requirement | Notes | +| ------ | ------ | ----------- | ---------------------------------------------------------------- | +| `name` | string | REQUIRED | Name is the name of a workspace to be provided by a PipelineRun. | -### `WorkspaceBinding` +### WorkspaceBinding -| Field Name | Field Type | Requirement | -|------------|--------------|-------------| -| `name` | string | REQUIRED | -| `emptyDir` | empty struct | REQUIRED | +| Field Name | Field Type | Requirement | Notes | +| ---------- | ------------ | ----------- | ----- | +| `name` | string | REQUIRED | | +| `emptyDir` | empty struct | REQUIRED | | **NB:** All other Workspace types supported by the Kubernetes implementation are **OPTIONAL** for the purposes of this spec. +### EnvVar -### `WorkspaceDeclaration` +| Field Name | Field Type | Requirement | Notes | +|------------|------------|-------------|-------| +| `name` | string | REQUIRED | | +| `value` | string | REQUIRED | | -| Field Name | Field Type | Requirement | -|---------------|------------|-------------| -| `name` | string | REQUIRED | -| `description` | string | REQUIRED | -| `mountPath` | string | REQUIRED | -| `readOnly` | boolean | REQUIRED | -| `description` | string | REQUIRED | +**NB:** All other [EnvVar](https://godoc.org/k8s.io/api/core/v1#EnvVar) types inherited from [core.v1/EnvVar](https://godoc.org/k8s.io/api/core/v1#EnvVar) and supported by the Kubernetes implementation (e.g., `valueFrom`) are **OPTIONAL** for the purposes of this spec. + +## Status Signalling + +The Tekton Pipelines API uses the [Kubernetes Conditions convention](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#typical-status-properties) to communicate status and errors to the user. + +`TaskRun`'s `status` field MUST have a `conditions` field, which must be a list of `Condition` objects of the following form: + +| Field | Type | Requirement | +|-----------------------|---------------------------------------------------------------|-------------| +| `type` | string | REQUIRED | +| `status` | Enum:
- `"True"`
- `"False"`
- `"Unknown"` (default) | REQUIRED | +| `reason` | string | REQUIRED | +| `message` | string | REQUIRED | +| `severity` | Enum:
- `""` (default)
- `"Warning"`
- `"Info"` | REQUIRED | +| `lastTransitionTime`* | string | OPTIONAL | + +\* If `lastTransitionTime` is populated by the implementation, it must be in [RFC3339](https://tools.ietf.org/html/rfc3339). + +Additionally, the resource's `status.conditions` field MUST be managed as follows to enable clients to present useful diagnostic and error information to the user. + +If a resource describes that it must report a Condition of the `type` `Succeeded`, then it must report it in the following manner: + +- If the `status` field is `"True"`, that means the execution finished successfully. +- If the `status` field is `"False"`, that means the execution finished unsuccessfully -- the Condition's `reason` and `message` MUST include further diagnostic information. +- If the `status` field is `"Unknown"`, that means the execution is still ongoing, and clients can check again later until the Condition's `status` reports either `"True"` or `"False"`. + +Resources MAY report Conditions with other `type`s, but none are REQUIRED or RECOMMENDED.