Skip to content

Commit

Permalink
Add documentation on Stored Record Type of PipelineRun and TaskRun
Browse files Browse the repository at this point in the history
  • Loading branch information
@khrm @tekton-robot
khrm authored and tekton-robot committed Jul 15, 2024
1 parent c34e40d commit 1629f9a
Show file tree
Hide file tree
Showing 4 changed files with 31 additions and 22 deletions.
8 changes: 4 additions & 4 deletions docs/DEVELOPMENT.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
}
Expand Down Expand Up @@ -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
}
Expand Down Expand Up @@ -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",
Expand All @@ -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",
Expand Down
28 changes: 15 additions & 13 deletions docs/api/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`

Expand Down Expand Up @@ -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"
}
]
Expand All @@ -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": [
{
Expand All @@ -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"
},
{
Expand All @@ -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"
},
{
Expand All @@ -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"
},
{
Expand All @@ -391,15 +393,15 @@ 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"
}
],
"resourceVersion": "1567",
"creationTimestamp": "2023-08-22T09:08:59Z"
},
"apiVersion": "tekton.dev/v1beta1"
"apiVersion": "tekton.dev/v1"
}
```

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

Expand Down
8 changes: 5 additions & 3 deletions docs/api/openapi.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
9 changes: 7 additions & 2 deletions docs/watcher/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

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

0 comments on commit 1629f9a

Please sign in to comment.