From 1629f9a9977d634cc5ae570b7556eef3149fa4f1 Mon Sep 17 00:00:00 2001 From: Khurram Baig Date: Mon, 15 Jul 2024 16:41:03 +0530 Subject: [PATCH] Add documentation on Stored Record Type of PipelineRun and TaskRun --- docs/DEVELOPMENT.md | 8 ++++---- docs/api/README.md | 28 +++++++++++++++------------- docs/api/openapi.yaml | 8 +++++--- docs/watcher/README.md | 9 +++++++-- 4 files changed, 31 insertions(+), 22 deletions(-) diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index baf641051..fab2836bb 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -144,7 +144,7 @@ results { } summary { record: "default/results/7afa9067-5001-4d93-b715-49854a770412/records/7afa9067-5001-4d93-b715-49854a770412" - type: "tekton.dev/v1beta1.TaskRun" + type: "tekton.dev/v1.TaskRun" end_time { seconds: 1677742039 } @@ -174,7 +174,7 @@ results { } summary { record: "default/results/c360def0-d77e-4a3f-a1b0-5b0753e7d5af/records/c360def0-d77e-4a3f-a1b0-5b0753e7d5af" - type: "tekton.dev/v1beta1.TaskRun" + type: "tekton.dev/v1.TaskRun" end_time { seconds: 1677742090 } @@ -223,7 +223,7 @@ This particular request lists the results under default namespace. "etag": "338481c9-3bc6-472f-9d1b-0f7705e6cb8c-1677742014191114634", "summary": { "record": "default/results/640d1af3-9c75-4167-8167-4d8e4f39d403/records/640d1af3-9c75-4167-8167-4d8e4f39d403", - "type": "tekton.dev/v1beta1.TaskRun", + "type": "tekton.dev/v1.TaskRun", "startTime": null, "endTime": "2023-03-02T07:26:54Z", "status": "SUCCESS", @@ -242,7 +242,7 @@ This particular request lists the results under default namespace. "etag": "9514f318-9329-485b-871c-77a4a6904891-1677742090308632274", "summary": { "record": "default/results/c360def0-d77e-4a3f-a1b0-5b0753e7d5af/records/c360def0-d77e-4a3f-a1b0-5b0753e7d5af", - "type": "tekton.dev/v1beta1.TaskRun", + "type": "tekton.dev/v1.TaskRun", "startTime": null, "endTime": "2023-03-02T07:28:10Z", "status": "SUCCESS", diff --git a/docs/api/README.md b/docs/api/README.md index ca7543b01..e606ef644 100644 --- a/docs/api/README.md +++ b/docs/api/README.md @@ -222,9 +222,11 @@ Here is the mapping between the Record JSON/protobuf fields and the CEL referenc Possible values for `data_type` and `summary.type` (for Result) are: -- `tekton.dev/v1beta1.TaskRun` or `TASK_RUN` -- `tekton.dev/v1beta1.PipelineRun` or `PIPELINE_RUN` -- `results.tekton.dev/v1alpha2.Log` +- `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` @@ -299,7 +301,7 @@ This is directly mappable to the YAML notation we generally use. { "kind": "TaskRun", "name": "hello-hello", - "apiVersion": "tekton.dev/v1beta1", + "apiVersion": "tekton.dev/v1", "pipelineTaskName": "hello" } ] @@ -317,7 +319,7 @@ This is directly mappable to the YAML notation we generally use. "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/v1beta1\",\"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" + "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": [ { @@ -332,7 +334,7 @@ This is directly mappable to the YAML notation we generally use. } }, "operation": "Update", - "apiVersion": "tekton.dev/v1beta1", + "apiVersion": "tekton.dev/v1", "fieldsType": "FieldsV1" }, { @@ -356,7 +358,7 @@ This is directly mappable to the YAML notation we generally use. } }, "operation": "Update", - "apiVersion": "tekton.dev/v1beta1", + "apiVersion": "tekton.dev/v1", "fieldsType": "FieldsV1" }, { @@ -371,7 +373,7 @@ This is directly mappable to the YAML notation we generally use. } }, "operation": "Update", - "apiVersion": "tekton.dev/v1beta1", + "apiVersion": "tekton.dev/v1", "fieldsType": "FieldsV1" }, { @@ -391,7 +393,7 @@ This is directly mappable to the YAML notation we generally use. } }, "operation": "Update", - "apiVersion": "tekton.dev/v1beta1", + "apiVersion": "tekton.dev/v1", "fieldsType": "FieldsV1", "subresource": "status" } @@ -399,7 +401,7 @@ This is directly mappable to the YAML notation we generally use. "resourceVersion": "1567", "creationTimestamp": "2023-08-22T09:08:59Z" }, - "apiVersion": "tekton.dev/v1beta1" + "apiVersion": "tekton.dev/v1" } ``` @@ -484,12 +486,12 @@ is a list of operators that can be used in CEL expressions: | Operator | Description | Example | | ----------------------- | -------------------- | ---------------------------------------------------------------------------------------------- | -| `==` | Equal to | `data_type == "tekton.dev/v1beta1.TaskRun"` | +| `==` | 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/v1beta1.TaskRun" && name.startsWith("foo/results/bar")` | -| `\|\|` | Logical OR | `data_type == "tekton.dev/v1beta1.TaskRun" \|\| data_type == "tekton.dev/v1beta1.PipelineRun"` | +| `&&` | 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` | diff --git a/docs/api/openapi.yaml b/docs/api/openapi.yaml index 393fe0f12..978c8e5dd 100644 --- a/docs/api/openapi.yaml +++ b/docs/api/openapi.yaml @@ -365,12 +365,14 @@ components: used as a type to hint to determine how to unmarshal values. Limited to 128 characters. Currently RecordType can be one of the following: - * PipelineRun Record: `tekton.dev/v1beta1.PipelineRun` + * PipelineRun Record: `tekton.dev/v1beta1.PipelineRun`(older records) or `tekton.dev/v1.PipelineRun` - * TaskRun Record: `tekton.dev/v1beta1.TaskRun` + * TaskRun Record: `tekton.dev/v1beta1.TaskRun`(older records) or `tekton.dev/v1.TaskRun` - * Log Record: `results.tekton.dev/v1alpha2.Log` + * Log Record: `results.tekton.dev/v1alpha2.Log`(older records) or `results.tekton.dev/v1alpha3.Log` enum: + - tekton.dev/v1.PipelineRun + - tekton.dev/v1.TaskRun - tekton.dev/v1beta1.PipelineRun - tekton.dev/v1beta1.TaskRun - results.tekton.dev/v1alpha2.Log diff --git a/docs/watcher/README.md b/docs/watcher/README.md index 209948cf2..a80cc257d 100644 --- a/docs/watcher/README.md +++ b/docs/watcher/README.md @@ -14,11 +14,12 @@ 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 @@ -47,7 +48,7 @@ Users and/or integrators can pass arbitrary keys/values to Results by adding spe 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: ```yaml -apiVersion: tekton.dev/v1beta1 +apiVersion: tekton.dev/v1 kind: PipelineRun metadata: generateName: hello-run- @@ -63,3 +64,7 @@ metadata: 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. An ability to convert older v1beta1 records to v1 will be added later on.