From fd4cb4621960715439bf0c0757f5be9cad390568 Mon Sep 17 00:00:00 2001 From: HamzaMateen Date: Mon, 25 Sep 2023 16:03:55 +0500 Subject: [PATCH] docs: Add TaskRun Status documentation section In response to issue #5720, this commit adds a new section to the docs/taskruns.md file to document the fields in TaskRun status in detail. The new section follows a similar structure to the PipelineRun status documentation and is divided into Required and Optional sections. - The Required section provides a comprehensive list of essential fields in TaskRun status, offering users insights into the key aspects of a TaskRun's state. - The Optional section complements the Required section by listing additional fields that provide more context and flexibility for TaskRuns. This addition enhances the documentation and helps users understand the details of TaskRun status, aligning it with the structure and clarity of PipelineRun documentation. Files changed: 1. taskruns.md 2. pipelineruns.md Fixes: #5720 --- docs/pipelineruns.md | 4 ++-- docs/taskruns.md | 32 +++++++++++++++++++++++++++++--- 2 files changed, 31 insertions(+), 5 deletions(-) diff --git a/docs/pipelineruns.md b/docs/pipelineruns.md index 70a6af40278..482c9e40913 100644 --- a/docs/pipelineruns.md +++ b/docs/pipelineruns.md @@ -1346,8 +1346,8 @@ Your `PipelineRun`'s `status` field can contain the following fields: - [`apiVersion`][kubernetes-overview] - The API version for the underlying `TaskRun` or `Run`. - [`whenExpressions`](pipelines.md#guard-task-execution-using-when-expressions) - The list of when expressions guarding the execution of this task. - `provenance` - Metadata about the runtime configuration and the resources used in the PipelineRun. The data in the `provenance` field will be recorded into the build provenance by the provenance generator i.e. (Tekton Chains). Currently, there are 2 subfields: - - `RefSource`: the source from where a remote pipeline definition was fetched. - - `FeatureFlags`: the configuration data of the `feature-flags` configmap. + - `refSource`: the source from where a remote pipeline definition was fetched. + - `featureFlags`: the configuration data of the `feature-flags` configmap. - `finallyStartTime`- The time at which the PipelineRun's `finally` Tasks, if any, began executing, in [RFC3339](https://tools.ietf.org/html/rfc3339) format. diff --git a/docs/taskruns.md b/docs/taskruns.md index c8f2c51908e..35b0cfaab18 100644 --- a/docs/taskruns.md +++ b/docs/taskruns.md @@ -28,10 +28,12 @@ weight: 202 - [Specifying `Retries`](#specifying-retries) - [Configuring the failure timeout](#configuring-the-failure-timeout) - [Specifying `ServiceAccount` credentials](#specifying-serviceaccount-credentials) +- [TaskRun status](#taskrun-status) + - [The status field](#the-status-field) - [Monitoring execution status](#monitoring-execution-status) - - [Monitoring `Steps`](#monitoring-steps) - - [Steps](#steps) - - [Monitoring `Results`](#monitoring-results) + - [Monitoring `Steps`](#monitoring-steps) + - [Steps](#steps) + - [Monitoring `Results`](#monitoring-results) - [Cancelling a `TaskRun`](#cancelling-a-taskrun) - [Debugging a `TaskRun`](#debugging-a-taskrun) - [Breakpoint on Failure](#breakpoint-on-failure) @@ -771,6 +773,30 @@ will execute with the [`default` service account](https://kubernetes.io/docs/tas set for the target [`namespace`](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/). For more information, see [`ServiceAccount`](auth.md). +## `TaskRun` status +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. + - `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. + - [`taskSpec`](tasks.md#configuring-a-task) - `TaskSpec` defines the desired state of the `Task` executed via the `TaskRun`. + +- Optional: + - `results` - List of results written out by the `task`'s containers. + + - `provenance` - Provenance contains metadata about resources used in the `TaskRun` such as the source from where a remote `task` definition was fetched. It carries minimum amount of metadata in `TaskRun` `status` so that `Tekton Chains` can utilize it for provenance, its two subfields are: + - `refSource`: the source from where a remote `Task` definition was fetched. + - `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