Tekton – Results

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Results API

Authentication/Authorization

The reference implementation of the Results API expects cluster generated authentication tokens from the cluster it is running on. In most cases, using a service account will be the easiest way to interact with the API.

RBAC Authorization is used to control access to API Resources.

The following attributes are recognized:

Attribute	Values
apiGroups	results.tekton.dev
resources	results, records
verbs	create, get, list, update, delete

For example, a read-only Role might look like:

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: tekton-results-readonly
rules:
  - apiGroups: ["results.tekton.dev"]
    resources: ["results", "records"]
    verbs: ["get", "list"]

In the reference implementation, all permissions are scoped per namespace (this is what is used as the API parent resource).

As a convenience, the following [ClusterRoles] are defined for common access patterns:

ClusterRole	Description
tekton-results-readonly	Read only access to all Result API resources
tekton-results-readwrite	Includes `tekton-results-readonly` + Create or update all Result API resources
tekton-results-admin	Includes `tekton-results-readwrite` + Allows deletion of Result API Resources

Impersonation

Kubernetes’ impersonation is used to refine access to the APIs.

How to use Impersonation?

Run API server with feature flag AUTH_IMPERSONATE set to true in the config.
Create two ServiceAccount, one for administering the permissions to impersonate and the other one for the permissions of the user to impersonate.
```
kubectl create serviceaccount impersonate-admin -n tekton-pipelines
```
```
kubectl create serviceaccount impersonate-user -n user-namespace
```

Create the following ClusterRole and ClusterRoleBinding for the impersonate-admin service account.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: tekton-results-impersonate
rules:
  - apiGroups: [""]
    resources: ["users", "groups", "serviceaccounts"]
    verbs: ["impersonate"]
  - apiGroups: ["authentication.k8s.io"]
    resources: ["uids"]
    verbs: ["impersonate"]

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: tekton-results-impersonate
subjects:
  - kind: ServiceAccount
    name: impersonate-admin
    namespace: tekton-pipelines
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: tekton-results-impersonate

Finally, create RoleBinding for impersonate-user service account.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: tekton-results-user
  namespace: user-namespace
subjects:
  - kind: ServiceAccount
    name: impersonate-user
    namespace: user-namespace
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: tekton-results-readonly

Now get a token for the service account impersonate-admin and store in a variable.
```
token=$(kubectl create token impersonate-admin -n tekton-pipelines)
```

Then the APIs can be called in the following format

curl -s --cacert /var/tmp/tekton/ssl/tls.crt  \
  -H 'authorization: Bearer '${token} \
  -H 'Impersonate-User: system:serviceaccount:user-namespace:impersonate-user' \
  https://localhost:8080/apis/results.tekton.dev/v1alpha2/parents/user-namespace/results

Need to provide a TLS cert if the API server is using TLS.

Troubleshooting

The following command can be run to query the cluster’s permissions. This can be useful for debugging permission denied errors:

kubectl create --as=system:serviceaccount:tekton-pipelines:tekton-results-watcher -n tekton-pipelines -f - -o yaml << EOF
apiVersion: authorization.k8s.io/v1
kind: SelfSubjectAccessReview
spec:
  resourceAttributes:
    group: results.tekton.dev
    resource: results
    verb: get
EOF
apiVersion: authorization.k8s.io/v1
kind: SelfSubjectAccessReview
metadata:
  creationTimestamp: null
  managedFields:
  - apiVersion: authorization.k8s.io/v1
    fieldsType: FieldsV1
    fieldsV1:
      f:spec:
        f:resourceAttributes:
          .: {}
          f:group: {}
          f:resource: {}
          f:verb: {}
    manager: kubectl
    operation: Update
    time: "2021-02-02T22:37:32Z"
spec:
  resourceAttributes:
    group: results.tekton.dev
    resource: results
    verb: get
status:
  allowed: true
  reason: 'RBAC: allowed by ClusterRoleBinding "tekton-results-watcher" of ClusterRole
    "tekton-results-watcher" to ServiceAccount "tekton-results-watcher/tekton-pipelines"'

Filtering

The reference implementation of the Results API uses CEL as a filtering spec. Filter specs expect a boolean result value. This document covers a small subset of CEL useful for filtering Results and Records.

Result

Here is the mapping between the Result JSON/protobuf fields and the CEL references:

Field	CEL Reference Field	Description
-	`parent`	Parent (workspace/namespace) name for the Result.
`uid`	`uid`	Unique identifier for the Result.
`annotations`	`annotations`	Annotations added to the Result.
`summary`	`summary`	The summary of the Result.
`createTime`	`create_time`	The creation time of the Result.
`updateTime`	`update_time`	The last update time of the Result.

The summary.status field is an enum and must be used in filtering expression without quotes (' or "). Possible values are:

UNKNOWN
SUCCESS
FAILURE
TIMEOUT
CANCELLED

Record and Log

Here is the mapping between the Record JSON/protobuf fields and the CEL references:

Field	CEL Reference Field	Description
`name`	`name`	Record name
`data.type`	`data_type`	It is the type identifier of the Record data. See below for values.
`data.value`	`data`	It is the data contained by the Record. In JSON and protobuf response, it is represented as a base 64 encoded string.

Possible values for data_type and summary.type (for Result) are:

tekton.dev/v1beta1.TaskRun or TASK_RUN - This is only for older records.
tekton.dev/v1beta1.PipelineRun or PIPELINE_RUN - This is only for older records.
tekton.dev/v1.TaskRun or TASK_RUN
tekton.dev/v1.PipelineRun or PIPELINE_RUN
results.tekton.dev/v1alpha2.Log - This is only for older Log records.
results.tekton.dev/v1alpha3.Log
results.tekton.dev/v1.EventList

The `data` field in Record

The data field is the base64 encoded string of the manifest of the object. If you directly request this data using CLI, REST or gRPC you will get the base64 encoded string. You can decode it using base64 -d command. This is not human-readable, but you can directly use filters to filter the response without need to decode it.

Here is an example of the JSON object contained in the data field of a Record. This is directly mappable to the YAML notation we generally use.

{
  "kind": "PipelineRun",
  "spec": {
    "timeout": "1h0m0s",
    "pipelineSpec": {
      "tasks": [
        {
          "name": "hello",
          "taskSpec": {
            "spec": null,
            "steps": [
              {
                "name": "hello",
                "image": "ubuntu",
                "script": "echo hello world!",
                "resources": {}
              }
            ],
            "metadata": {}
          }
        }
      ]
    },
    "serviceAccountName": "default"
  },
  "status": {
    "startTime": "2023-08-22T09:08:59Z",
    "conditions": [
      {
        "type": "Succeeded",
        "reason": "Succeeded",
        "status": "True",
        "message": "Tasks Completed: 1 (Failed: 0, Cancelled 0), Skipped: 0",
        "lastTransitionTime": "2023-08-22T09:09:31Z"
      }
    ],
    "pipelineSpec": {
      "tasks": [
        {
          "name": "hello",
          "taskSpec": {
            "spec": null,
            "steps": [
              {
                "name": "hello",
                "image": "ubuntu",
                "script": "echo hello world!",
                "resources": {}
              }
            ],
            "metadata": {}
          }
        }
      ]
    },
    "completionTime": "2023-08-22T09:09:31Z",
    "childReferences": [
      {
        "kind": "TaskRun",
        "name": "hello-hello",
        "apiVersion": "tekton.dev/v1",
        "pipelineTaskName": "hello"
      }
    ]
  },
  "metadata": {
    "uid": "1638b693-844d-4f13-b767-d7d84ac4ab3d",
    "name": "hello",
    "labels": {
      "tekton.dev/pipeline": "hello"
    },
    "namespace": "default",
    "generation": 1,
    "annotations": {
      "results.tekton.dev/record": "default/results/1638b693-844d-4f13-b767-d7d84ac4ab3d/records/1638b693-844d-4f13-b767-d7d84ac4ab3d",
      "results.tekton.dev/result": "default/results/1638b693-844d-4f13-b767-d7d84ac4ab3d",
      "results.tekton.dev/resultAnnotations": "{\"repo\": \"tektoncd/results\", \"commit\": \"1a6b908\"}",
      "results.tekton.dev/recordSummaryAnnotations": "{\"foo\": \"bar\"}",
      "kubectl.kubernetes.io/last-applied-configuration": "{\"apiVersion\":\"tekton.dev/v1\",\"kind\":\"PipelineRun\",\"metadata\":{\"annotations\":{\"results.tekton.dev/recordSummaryAnnotations\":\"{\\\"foo\\\": \\\"bar\\\"}\",\"results.tekton.dev/resultAnnotations\":\"{\\\"repo\\\": \\\"tektoncd/results\\\", \\\"commit\\\": \\\"1a6b908\\\"}\"},\"name\":\"hello\",\"namespace\":\"default\"},\"spec\":{\"pipelineSpec\":{\"tasks\":[{\"name\":\"hello\",\"taskSpec\":{\"steps\":[{\"image\":\"ubuntu\",\"name\":\"hello\",\"script\":\"echo hello world!\"}]}}]}}}\n"
    },
    "managedFields": [
      {
        "time": "2023-08-22T09:08:59Z",
        "manager": "controller",
        "fieldsV1": {
          "f:metadata": {
            "f:labels": {
              ".": {},
              "f:tekton.dev/pipeline": {}
            }
          }
        },
        "operation": "Update",
        "apiVersion": "tekton.dev/v1",
        "fieldsType": "FieldsV1"
      },
      {
        "time": "2023-08-22T09:08:59Z",
        "manager": "kubectl-client-side-apply",
        "fieldsV1": {
          "f:spec": {
            ".": {},
            "f:pipelineSpec": {
              ".": {},
              "f:tasks": {}
            }
          },
          "f:metadata": {
            "f:annotations": {
              ".": {},
              "f:results.tekton.dev/resultAnnotations": {},
              "f:results.tekton.dev/recordSummaryAnnotations": {},
              "f:kubectl.kubernetes.io/last-applied-configuration": {}
            }
          }
        },
        "operation": "Update",
        "apiVersion": "tekton.dev/v1",
        "fieldsType": "FieldsV1"
      },
      {
        "time": "2023-08-22T09:08:59Z",
        "manager": "watcher",
        "fieldsV1": {
          "f:metadata": {
            "f:annotations": {
              "f:results.tekton.dev/record": {},
              "f:results.tekton.dev/result": {}
            }
          }
        },
        "operation": "Update",
        "apiVersion": "tekton.dev/v1",
        "fieldsType": "FieldsV1"
      },
      {
        "time": "2023-08-22T09:09:31Z",
        "manager": "controller",
        "fieldsV1": {
          "f:status": {
            ".": {},
            "f:startTime": {},
            "f:conditions": {},
            "f:pipelineSpec": {
              ".": {},
              "f:tasks": {}
            },
            "f:completionTime": {},
            "f:childReferences": {}
          }
        },
        "operation": "Update",
        "apiVersion": "tekton.dev/v1",
        "fieldsType": "FieldsV1",
        "subresource": "status"
      }
    ],
    "resourceVersion": "1567",
    "creationTimestamp": "2023-08-22T09:08:59Z"
  },
  "apiVersion": "tekton.dev/v1"
}

You can now access the required fields using the dot notation and considering data as the parent object. For example:

Purpose	Filter Expression
Name of the PipelineRun	`data.metadata.name`
Name of the ServiceAccount used in the PipelineRun	`data.spec.serviceAccountName`
Name of the first task of the PipelineRun from its spec	`data.spec.pipelineSpec.tasks[0].name`
Start time of the PipelineRun	`data.status.startTime`
Labels of the PipelineRun	`data.metadata.labels`
Annotations of the PipelineRun	`data.metadata.annotations`
A particular annotation of the PipelineRun	`data.metadata.annotations['foo']`

The `data` field in Log

The data field is the base64 encoded custom object of the type Log. Accessing the fields is similar to records. Given below is an example of the JSON object contained in the data field of a Log.

{
  "kind": "Log",
  "spec": {
    "type": "File",
    "resource": {
      "uid": "dbe14a60-1fc8-458e-a49b-264771557c3e",
      "kind": "TaskRun",
      "name": "hello",
      "namespace": "default"
    }
  },
  "status": {
    "path": "default/2d27dde5-e201-35f9-b658-2456f2955903/hello-log",
    "size": 83
  },
  "metadata": {
    "uid": "2d27dde5-e201-35f9-b658-2456f2955903",
    "name": "hello-log",
    "namespace": "default",
    "creationTimestamp": null
  },
  "apiVersion": "results.tekton.dev/v1alpha2"
}

Here are some examples of accessing the fields of the Log using the dot notation:

Purpose	Filter Expression
Type of the Run that created this Log	`data.spec.resource.kind`
Size of the Log	`data.status.size`
Name of the Run that created this Log	`data.spec.resource.name`

How to Create CEL Filtering Expressions

CEL expressions are composed of identifiers, literals, operators, and functions. Here, we will learn how to create CEL filtering expressions using the above-mentioned fields. This is not an exhaustive list of CEL expressions. For more information, please refer to CEL Specification.

Accessing Fields

The CEL expression generally has one-to-one mapping with the JSON/protobuf fields. In Tekton Results, we have created some extra alias for easy access. You can see all of them in the tables above. Other than that, you can access any field of the JSON/protobuf object using the dot notation. See the examples in the tables below.

Purpose	Filter Expression	Description
Status of a Result	`summary.status`	The `status` of a Result is a child of the `summary`` object.
Data type of Record	`data_type`	`data_type` is a defined alias for `data.type` for a Record.
Data type of Result	`summary.type`	The `type` of a Result is a child of `summary``.
Name of the first step of the tasks of a run from its status.	`data.status.taskSpec.steps[0].name`	The JSON path is `data -> status -> taskSpec -> steps -> 0 -> name`.

Using Operators

Now that we can access the fields, you can create a filter using operators. Here is a list of operators that can be used in CEL expressions:

Operator	Description	Example
`==`	Equal to	`data_type == "tekton.dev/v1.TaskRun"`
`!=`	Not equal to	`summary.status != SUCCESS`
`IN`	In a list	`data.metadata.name in ['hello', 'foo', 'bar']`
`!`	Negation	`!(data.status.name in ['hello', 'foo', 'bar'])`
`&&`	Logical AND	`data_type == "tekton.dev/v1.TaskRun" && name.startsWith("foo/results/bar")`
`\|\|`	Logical OR	`data_type == "tekton.dev/v1.TaskRun" \|\| data_type == "tekton.dev/v1.PipelineRun"`
`+`, `-`, `*`, `/`, `%`	Arithmetic operators	`data.status.completionTime - data.status.startTime > duration('5m')`
`>`, `>=`, `<`, `<=`	Comparison operators	`data.status.completionTime > data.status.startTime`

Using Functions

There are many functions that can be used in CEL expressions. Here is a list of functions that can be used in CEL expressions. The string in the function argument shows the expected type of the argument:

Functions	Description	Example
`startsWith('string')`	Checks if a string starts with a prefix	`data.metadata.name.startsWith("foo")`
`endsWith('string')`	Checks if a string ends with a suffix	`data.metadata.name.endsWith("bar")`
`contains('string')`	Checks if a field is present or an object contains a key or value	`data.metadata.annotations.contains('bar')`
`timestamp('RFC3339-timestamp')`	Used for comparing timestamps	`data.status.startTime > timestamp("2021-02-02T22:37:32Z")`
`getDate()`	Returns the date from a timestamp	`data.status.completionTime.getDate() == 7`
`getDayOfWeek()`, `getDayOfMonth()`, `getDayOfYear()`	Returns the day of the week, month or year from a timestamp	`data.status.completionTime.getDayOfMonth() == 7`
`getFullYear()`	Returns the year from a timestamp	`data.status.startTime.getFullYear() == 2023`
`getHours()`, `getMinutes()`, `getSeconds()`	Returns the hours, minutes or seconds from a timestamp	`data.status.completionTime.getHours() >= 9`
`string('input')`	Convert a valid input to string	`string(data.status.completionTime) == "2021-02-02T22:37:32Z"`
`matches('regex')`	Checks if a string matches a regex	`name.matches("^foo.*$")`

You can also nest the function calls and mix operators to create complex filtering expressions. Make sure to use the correct type of the argument for the function. You can see a more exhaustive reference of functions in the CEL specification. The functions mentioned above are the ones that are most commonly used and working.

Using CEL Filtering Expressions with gRPC

You can pass filters to gRPC requests by specifying filter=<cel-expression>. Please enclose the queries in proper quotes or use \ if needed. See the examples below:

grpc_cli call --channel_creds_type=ssl \
  --ssl_target=tekton-results-api-service.tekton-pipelines.svc.cluster.local \
  --call_creds=access_token=$ACCESS_TOKEN \
  localhost:8080 tekton.results.v1alpha2.Results.ListResults \
  'parent:"default",filter:"data_type==TASK_RUN"'

Using CEL Filtering Expressions with REST

You can pass filters to REST requests by specifying filter=<cel-expression> in the query. See the examples below:

curl --insecure
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Accept: application/json" \
  https://localhost:8080/apis/results.tekton.dev/v1alpha2/parents/-/results/-?filter=data.status.completionTime.getDate()==7

Using CEL Filtering Expressions with `tkn-results`

If you have the tkn-results CLI installed either independently or as a plugin for tkn, you can use the --filter=<cel-expression> flag to filter the results. See the examples below:

tkn results records list default/results/- --filter="data.metadata.annotations.contains('bar')"

Commonly used filters examples

These example shows the most used filtering expression that would be useful for everyday use. Keep in mind that not all of these filters are available for Results, Records and Logs. You must be providing the correct filter for the correct resource.

Purpose	Filter Expression
Get all Records where the TaskRun/PipelineRun name is `hello`	`data.metadata.name == 'hello'`
Get all Records of TaskRuns which are part of the PipelineRun ‘foo’	`data.metadata.labels['tekton.dev/pipelineRun'] == 'foo'`
Get all the Records of the TaskRun/PipelineRun which are part of Pipeline ‘bar’	`data.metadata.labels['tekton.dev/pipeline'] == 'bar'`
Same query as above, but I only want the PipelineRuns	`data.metadata.labels['tekton.dev/pipeline'] == 'bar' && data_type == 'PIPELINE_RUN'`
Get the Records of the TaskRuns whose name starts with `hello`	`data.metadata.name.startsWith('hello')&&dat_type==TASK_RUN`
Get all the Results of Successful TaskRuns	`summary.status == SUCCESS && summary.type == 'TASK_RUN'`
Get the Records of the PipelineRuns whose completion time is greater than 5 minutes	`data.status.completionTime - data.status.startTime > duration('5m') && data_type == 'PIPELINE_RUN'`
Get the Records of the Runs which completed today (let’s assume today is 7th)	`data.status.completionTime.getDate() == 7`
Get the Records of the PipelineRuns which has annotations containing `bar`	`data.metadata.annotations.contains('bar') && data_type == 'PIPELINE_RUN'`
Get the Records of the PipelineRuns which has annotations containing `bar` and the name starts with `foo`	`data.metadata.annotations.contains('bar') && data.metadata.name.startsWith('foo') && data_type == 'PIPELINE_RUN'`
Get the Results containing the annotations `foo` and `bar`	`summary.annotations.contains('foo') && summary.annotations.contains('bar')`
Get the Results of all the Runs that failed	`!(summary.status == SUCCESS)`
Get all the Records of the Runs that failed	`!(data.status.conditions[0].status == 'True')`
Get all the Records of the PipelineRuns which had 3 or more tasks	`size(data.status.pipelineSpec.tasks) >= 3 && data_type == 'PIPELINE_RUN'`

Filtering Response

Google’s AIP-157 is implemented in the all the APIs and allows the response to be filtered according to user need.

How to use

A URL parameter called fields, containing the paths to the items required in the response needs to be sent along with the request. For gRPC requests this should be sent in the header.
The response will then contain only the elements specified by the paths. Leaving the field blank or not sending the header will return the whole response.

To enable this feature add PartialResponse=true in the FEATURE_GATES section in the config.

fields: records.name, records.data.value.metadata.name

This will only return name and metadata in the response. If a path is not valid in the proto, it will be ignored. If a path is not valid in a JSON field, the path will appear in the response with a null value.
Filtering a JSON array is NOT supported at the moment.

Examples

curl -kG \
--data-urlencode "fields=records.name, records.data.value.metadata" \
http://localhost:8080/apis/results.tekton.dev/v1alpha2/parents/default/results/-/records

grpcurl --insecure \
-H 'fields: records.name, records.data.value.metadata' \
-d '{"parent": "default/results/-"}' \
results.tekton.dev:8080 tekton.results.v1alpha2.Results/ListRecords

Ordering

The reference implementation of the Results API supports ordering result and record responses with an optional direction qualifier (either asc or desc).

To request a list of objects with a specific order, include a order_by query parameter in your request. Pass it the name of the field to be ordered on. Multiple fields can be specified with a comma-separated list. Examples:

create_time
update_time asc
create_time desc, update_time asc

Fields supported in order_by:

Field Name
`create_time`
`update_time`

Pagination

The reference implementation of Results API supports pagination for results, records and logs. The default number of objects in a single page is 50 and the maximum number is 10000.

To paginate the response, include the page_size query parameter in your request. It must be an integer value between 0 and, 10000. If the page_size is less than the number of total objects available for the particular query, the response will include a NextPageToken in the response. You can pass this value to page_token query parameter to fetch the next page. Both the queries are independent and can be used individually or together.

Name	Description
`page_size`	The number of objects to fetch in the response.
`page_token`	Token of the page to be fetched.

Reading results across parents

Results can be read across parents by specifying - as the parent name. This is useful for listing all results stored in the system without prior knowledge about the available parents.

Reading Records across Results

Records can be read across Results by specifying - as the Result name part, or across parents by specifying - as the parent name. (e.g. default/results/- or -/results/-). This can be used to read and filter matching Records without knowing the exact Result name.

Metrics

The API Server includes an HTTP server for exposing gRPC server Prometheus metrics. By default, the Service exposes metrics on port :9090. For more details on the structure of the metrics, see https://github.com/grpc-ecosystem/go-grpc-prometheus#metrics.

Health

The API Server includes gRPC and REST endpoints for monitoring the serving status of the API server as well as serving status of individual services.

Checking Status

# Check status of API server using gRPC
grpcurl --insecure localhost:8080 grpc.health.v1.Health/Check

# Check status of individual service using gRPC
grpcurl --insecure -d '{"service": "tekton.results.v1alpha2.Results"}' localhost:8080 grpc.health.v1.Health/Check

# Check status of API server using REST
curl -k https://localhost:8080/healthz

# Check status of individual service using REST
curl -k https://localhost:8080/healthz?service=tekton.results.v1alpha2.Results

Profiling

The API Server includes an HTTP server for exposing golang’s debug profiles. By default, the Service is disabled and exposes debug profiles on port :6060. For more details on the using the profiles, see https://pkg.go.dev/net/http/pprof.

References

OpenAPI Specification

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Result Watcher

The Result Watcher is a Kubernetes Controller that watches for changes to certain Tekton types and automatically creates/updates their data in the Result API.

Supported Types

The Watcher currently supports the following types:

tekton.dev/v1beta1 TaskRun
tekton.dev/v1beta1 PipelineRun
tekton.dev/v1 TaskRun
tekton.dev/v1 PipelineRun

Result Grouping

The Watcher uses Object data to automatically detect and group related Records into the same Result. The following data is checked (listed in order of precedence):

results.tekton.dev/result annotation. This should correspond to the full Result.name identifier (e.g. foo/results/bar).
triggers.tekton.dev/triggers-eventid label (this is generated from Objects created via Tekton Triggers)
An OwnerReference to a PipelineRun.

If no annotation is detected, the Watcher will automatically generate a new Result name for the Object.

Passing arbitrary key/values to Results

Users and/or integrators can pass arbitrary keys/values to Results by adding special annotations to PipelineRuns and TaskRuns:

results.tekton.dev/resultAnnotations: a JSON object (string->string) to be stored into thee Result.Annotations field.
results.tekton.dev/recordSummaryAnnotations: a JSON object (string->string) to be stored into thee Result.Summary.Annotations field.

Once the Watcher detects those annotations in the observed object, it passes the keys/values to the respective fields of the underlying Result. Those annotations can be used to store relevant metadata (e.g. the Git commit SHA that triggered a PipelineRun) into Results and may be used later to retrieve the objects from the API server. For instance:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  generateName: hello-run-
  annotations:
    results.tekton.dev/resultAnnotations: |-
            {"repo": "tektoncd/results", "commit": "1a6b908"}
    results.tekton.dev/recordSummaryAnnotations: |-
            {"foo": "bar"}

Resource Deletion

When the command line flag is completed_run_grace_period is set to any value other than 0, resources will be deleted after the specified duration in the flag, calculated from the time of completion. If the value is < 0, Runs will be deleted immediately after completion or failure.

The flag check_owner allows additional check before deleting a resource. If set true, resources with any owner references set will not be deleted. When the flag is false, owner references will be not be checked before deletion.

Supported version of TaskRun and PipelineRun CR

Results stores PipelineRun and TaskRun as v1. If there are older records, it’s possible that they are stored as v1beta1. API server can be configured to start a converter during initialisation.

Finalizer for blocking deletion

Watcher implements a finalizer to block deletion by an external pruner when objects are stored via the Watcher.

When deletion request comes, it will block until completion time + completed_run_grace_period period is passed. A hard limit could be set as store_deadline (default 10m), after which the object will be removed from the cluster even without confirmation it’s been stored in the DB.

Disabling Incomplete Runs storage

The disable_storing_incomplete_runs flag controls whether the Watcher should store PipelineRuns and TaskRuns that are still in progress (i.e., not yet completed, cancelled or failed).

When set to true, the Watcher will only store Runs once they are completed. This is useful for reducing the load for API server and reconciliation queue.

When set to false (default), the Watcher will attempt to continuously store all Runs on every modification regardless of their completion status, allowing you to track the full lifecycle of your PipelineRuns and TaskRuns.

Tekton – Results

Docs:

Results API

Authentication/Authorization

Impersonation

How to use Impersonation?

Troubleshooting

Filtering

Result

Record and Log

The data field in Record

The data field in Log

How to Create CEL Filtering Expressions

Accessing Fields

Using Operators

Using Functions

Using CEL Filtering Expressions with gRPC

Using CEL Filtering Expressions with REST

Using CEL Filtering Expressions with tkn-results

Commonly used filters examples

Filtering Response

How to use

Examples

Ordering

Pagination

Reading results across parents

Reading Records across Results

Metrics

Health

Checking Status

Profiling

References

Docs:

Result Watcher

Supported Types

Result Grouping

Passing arbitrary key/values to Results

Resource Deletion

Supported version of TaskRun and PipelineRun CR

Finalizer for blocking deletion

Disabling Incomplete Runs storage

The `data` field in Record

The `data` field in Log

Using CEL Filtering Expressions with `tkn-results`