From 8017a514f70d9e0c6c525fc6038fe31ece9dabad Mon Sep 17 00:00:00 2001 From: Misha Ramendik Date: Tue, 22 Aug 2023 05:04:21 +0200 Subject: [PATCH] RHDEVDOCS 5244 Tekton Results documentation --- _attributes/common-attributes.adoc | 1 + _topic_maps/_topic_map.yml | 2 + modules/op-installing-results.adoc | 94 ++++++++++ modules/op-prepare-opc-for-results.adoc | 54 ++++++ modules/op-query-results-name.adoc | 98 ++++++++++ modules/op-results-cert.adoc | 40 ++++ modules/op-results-concepts.adoc | 172 ++++++++++++++++++ modules/op-results-db.adoc | 40 ++++ modules/op-results-reference-records.adoc | 30 +++ modules/op-results-reference-results.adoc | 45 +++++ modules/op-results-search-records.adoc | 73 ++++++++ modules/op-results-search-results.adoc | 37 ++++ modules/op-results-storage.adoc | 87 +++++++++ ...for-openshift-pipelines-observability.adoc | 53 ++++++ 14 files changed, 826 insertions(+) create mode 100644 modules/op-installing-results.adoc create mode 100644 modules/op-prepare-opc-for-results.adoc create mode 100644 modules/op-query-results-name.adoc create mode 100644 modules/op-results-cert.adoc create mode 100644 modules/op-results-concepts.adoc create mode 100644 modules/op-results-db.adoc create mode 100644 modules/op-results-reference-records.adoc create mode 100644 modules/op-results-reference-results.adoc create mode 100644 modules/op-results-search-records.adoc create mode 100644 modules/op-results-search-results.adoc create mode 100644 modules/op-results-storage.adoc create mode 100644 records/using-tekton-results-for-openshift-pipelines-observability.adoc diff --git a/_attributes/common-attributes.adoc b/_attributes/common-attributes.adoc index 04ca91052f31..a9b60f2f2495 100644 --- a/_attributes/common-attributes.adoc +++ b/_attributes/common-attributes.adoc @@ -14,6 +14,7 @@ :pipelines-shortname: OpenShift Pipelines :pipelines-ver: pipelines-1.11 :tekton-chains: Tekton Chains +:tekton-results: Tekton Results :tekton-hub: Tekton Hub :artifact-hub: Artifact Hub :pac: Pipelines as Code diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index ab12f5980b51..5fff34cd4969 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -68,6 +68,8 @@ Name: Observability in OpenShift Pipelines Dir: records Distros: openshift-pipelines Topics: +- Name: Using Tekton Results for OpenShift Pipelines observability + File: using-tekton-results-for-openshift-pipelines-observability - Name: Viewing pipeline logs using the OpenShift Logging Operator File: viewing-pipeline-logs-using-the-openshift-logging-operator --- diff --git a/modules/op-installing-results.adoc b/modules/op-installing-results.adoc new file mode 100644 index 000000000000..6f83188b2334 --- /dev/null +++ b/modules/op-installing-results.adoc @@ -0,0 +1,94 @@ +// This module is included in the following assembly: +// +// * cicd/pipelines/using-tekton-results-for-openshift-pipelines-observability.adoc + +:_content-type: PROCEDURE +[id="installing-results_{context}"] += Installing {tekton-results} + +[role="_abstract"] +To install {tekton-results}, you must provide the required resources and then create and apply a `TektonResult` custom resource (CR). The {pipelines-shortname} Operator installs the Results services when you apply the `TektonResult` custom resource. + +.Prerequisites + +* You installed {pipelines-shortname} using the Operator. +* You prepared a secret with the SSL certificate. +* You prepared storage for the logging information. +* You prepared a secret with the database credentials. + +.Procedure + +. Create the resource definition file named `result.yaml` based on the following example. You can adjust the settings as necessary. ++ +[source,yaml] +---- + apiVersion: operator.tekton.dev/v1alpha1 + kind: TektonResult + metadata: + name: result + spec: + targetNamespace: openshift-pipelines + logs_api: true + log_level: debug + db_port: 5432 + db_host: tekton-results-postgres-service.openshift-pipelines.svc.cluster.local + logs_path: /logs + logs_type: File + logs_buffer_size: 32768 + auth_disable: true + tls_hostname_override: tekton-results-api-service.openshift-pipelines.svc.cluster.local + db_enable_auto_migration: true + server_port: 8080 + prometheus_port: 9090 +---- + +. Add configuration for the storage for logging information to this file: +** If you configured a persistent volume claim (PVC), add the following line to provide the name of the PVC: ++ +[source,yaml] +---- + logging_pvc_name: tekton-logs +---- +** If you configured Google Cloud Storage, add the following lines to provide the secret name, the credentials file name, and the name of the Google Cloud Storage bucket: ++ +[source,yaml] +---- + gcs_creds_secret_name: gcs-credentials + gcs_creds_secret_key: application_default_credentials.json # <1> + gcs_bucket_name: bucket-name #<2> +---- +<1> Provide the name, without the path, of the application credentials file that you used when creating the secret. +<2> Provide the name of a bucket in Google Cloud Storage. {tekton-chains} uses this bucket to store logging information for pipeline runs and task runs. +** If you configured S3 bucket storage, add the following line to provide the name of the S3 secret: ++ +[source,yaml] +---- + secret_name: s3-credentials +---- + +. Optional: If you want to use an external PostgreSQL database server to store {tekton-results} information, add the following lines to the file: ++ +[source,yaml] +---- + db_host: postgres.internal.example.com # <1> + db_port: 5432 # <2> + is_external_db: true +---- +<1> The host name for the PostgreSQL server. +<2> The port for the PostgreSQL server. + +. Apply the resource definition by entering the following command: ++ +[source,terminal] +---- +$ oc apply -n openshift-pipelines -f result.yaml +---- + +. Expose the route for the {tekton-results} service API by entering the following command: ++ +[source,terminal] +---- +$ oc create route -n openshift-pipelines \ + passthrough tekton-results-api-service \ + --service=tekton-results-api-service --port=8080 +---- diff --git a/modules/op-prepare-opc-for-results.adoc b/modules/op-prepare-opc-for-results.adoc new file mode 100644 index 000000000000..bc874031504e --- /dev/null +++ b/modules/op-prepare-opc-for-results.adoc @@ -0,0 +1,54 @@ +// This module is included in the following assembly: +// +// * records/using-tekton-results-for-openshift-pipelines-observability.adoc + +:_content-type: PROCEDURE +[id="prepare-opc-for-results_{context}"] += Preparing the opc utility environment for querying {tekton-results} + +[role="_abstract"] +Before you can query {tekton-results}, you must prepare the environment for the `opc` utility. + +.Prerequisites + +* You installed {tekton-results}. +* You installed the `opc` utility. + +.Procedure + +. Set the `RESULTS_API` environment variable to the route to the {tekton-results} API by entering the following command: ++ +[source, terminal] +---- +$ export RESULTS_API=$(oc get route tekton-results-api-service -n openshift-pipelines --no-headers -o custom-columns=":spec.host"):443 +---- + +. Create an authentication token for the {tekton-results} API by entering the following command: ++ +[source,terminal] +---- +$ oc create token sa +---- ++ +Save the string that this command outputs. + +. Optional: Create the `~/.config/tkn/results.yaml` file for automatic authentication with the {tekton-results} API. The file must have the following contents: ++ +[source,yaml] +---- +address: # <1> +token: # <2> +ssl: + roots_file_path: /home/example/cert.pem # <3> + server_name_override: tekton-results-api-service.openshift-pipelines.svc.cluster.local # <4> + service_account: + namespace: service_acc_1 <5> + name: service_acc_1 <5> +---- +<1> The route to the {tekton-results} API. Use the same value as you set for `RESULTS_API`. +<2> The authentication token that was created by the `oc create token` command. If you provide this token, it overrides the `service_account` setting and `opc` uses this token to authenticate. +<3> The location of the file with the SSL certificate that you configured for the API endpoint. +<4> If you configured a custom target namespace for {pipelines-shortname}, replace `openshift-pipelines` with the name of this namespace. +<5> The name of a service account for authenticating with the {tekton-results} API. If you provided the authentication token, you do not need to provide the `service_account` parameters. ++ +Alternatively, if you do not create the `~/.config/tkn/results.yaml` file, you can pass the token to each `opc` command by using the `--authtoken` option. diff --git a/modules/op-query-results-name.adoc b/modules/op-query-results-name.adoc new file mode 100644 index 000000000000..9b91b10a59d4 --- /dev/null +++ b/modules/op-query-results-name.adoc @@ -0,0 +1,98 @@ +// This module is included in the following assembly: +// +// * records/using-tekton-results-for-openshift-pipelines-observability.adoc + +:_content-type: PROCEDURE +[id="query-results-uuid_{context}"] += Querying for results and records by name + +[role="_abstract"] +You can list and query results and records using their names. + +.Prerequisites + +* You installed {tekton-results}. +* You installed the `opc` utility and prepared its environment to query {tekton-results}. +* You installed the `jq` package. + +.Procedure + +. List the names of all results that correspond to pipeline runs and task runs created in a namespace. Enter the following command: ++ +[source,terminal] +---- +$ opc results list --addr ${RESULTS_API} +---- ++ +.Example command +[source,terminal] +---- +$ opc results list --addr ${RESULTS_API} results-testing +---- ++ +.Example output +[source,text] +---- +Name Start Update +results-testing/results/04e2fbf2-8653-405f-bc42-a262bcf02bed 2023-06-29 02:49:53 +0530 IST 2023-06-29 02:50:05 +0530 IST +results-testing/results/ad7eb937-90cc-4510-8380-defe51ad793f 2023-06-29 02:49:38 +0530 IST 2023-06-29 02:50:06 +0530 IST +results-testing/results/d064ce6e-d851-4b4e-8db4-7605a23671e4 2023-06-29 02:49:45 +0530 IST 2023-06-29 02:49:56 +0530 IST +---- + +. List the names of all records in a result by entering the following command: ++ +[source,terminal] +---- +$ opc results records list --addr ${RESULTS_API} +---- ++ +.Example command +[source,terminal] +---- +$ opc results records list --addr ${RESULTS_API} results-testing/results/04e2fbf2-8653-405f-bc42-a262bcf02bed +---- ++ +.Example output +[source,text] +---- +Name Type Start Update +results-testing/results/04e2fbf2-8653-405f-bc42-a262bcf02bed/records/e9c736db-5665-441f-922f-7c1d65c9d621 tekton.dev/v1beta1.TaskRun 2023-06-29 02:49:53 +0530 IST 2023-06-29 02:49:57 +0530 IST +results-testing/results/04e2fbf2-8653-405f-bc42-a262bcf02bed/records/5de23a76-a12b-3a72-8a6a-4f15a3110a3e results.tekton.dev/v1alpha2.Log 2023-06-29 02:49:57 +0530 IST 2023-06-29 02:49:57 +0530 IST +results-testing/results/04e2fbf2-8653-405f-bc42-a262bcf02bed/records/57ce92f9-9bf8-3a0a-aefb-dc20c3e2862d results.tekton.dev/v1alpha2.Log 2023-06-29 02:50:05 +0530 IST 2023-06-29 02:50:05 +0530 IST +results-testing/results/04e2fbf2-8653-405f-bc42-a262bcf02bed/records/e9a0c21a-f826-42ab-a9d7-a03bcefed4fd tekton.dev/v1beta1.TaskRun 2023-06-29 02:49:57 +0530 IST 2023-06-29 02:50:05 +0530 IST +results-testing/results/04e2fbf2-8653-405f-bc42-a262bcf02bed/records/04e2fbf2-8653-405f-bc42-a262bcf02bed tekton.dev/v1beta1.PipelineRun 2023-06-29 02:49:53 +0530 IST 2023-06-29 02:50:05 +0530 IST +results-testing/results/04e2fbf2-8653-405f-bc42-a262bcf02bed/records/e6eea2f9-ec80-388c-9982-74a018a548e4 results.tekton.dev/v1alpha2.Log 2023-06-29 02:50:05 +0530 IST 2023-06-29 02:50:05 +0530 IST +---- + +. Retrieve the YAML manifest for a pipeline run or task run from a record by entering the following command: ++ +[source,terminal] +---- +$ opc results records get --addr ${RESULTS_API} \ + | jq -r .data.value | base64 -d | \ + xargs -0 python3 -c 'import sys, yaml, json; j=json.loads(sys.argv[1]); print(yaml.safe_dump(j))' +---- ++ +.Example command +[source,terminal] +---- +$ opc results records get --addr ${RESULTS_API} \ + results-testing/results/04e2fbf2-8653-405f-bc42-a262bcf02bed/records/e9c736db-5665-441f-922f-7c1d65c9d621 | \ + jq -r .data.value | base64 -d | \ + xargs -0 python3 -c 'import sys, yaml, json; j=json.loads(sys.argv[1]); print(yaml.safe_dump(j))' +---- + +. Optional: Retrieve the logging information for a task run from a record using the log record name. To get the log record name, replace `records` with `logs` in the record name. Enter the following command: ++ +[source,terminal] +---- +$ opc results logs get --addr ${RESULTS_API} | jq -r .data | base64 -d +---- ++ +.Example command +[source,terminal] +---- +$ opc results logs get --addr ${RESULTS_API} \ + results-testing/results/04e2fbf2-8653-405f-bc42-a262bcf02bed/logs/e9c736db-5665-441f-922f-7c1d65c9d621 | \ + jq -r .data | base64 -d +---- diff --git a/modules/op-results-cert.adoc b/modules/op-results-cert.adoc new file mode 100644 index 000000000000..9675b600c9fe --- /dev/null +++ b/modules/op-results-cert.adoc @@ -0,0 +1,40 @@ +// This module is included in the following assembly: +// +// * records/using-tekton-results-for-openshift-pipelines-observability.adoc + +:_content-type: PROCEDURE +[id="results-cert_{context}"] += Preparing a secret with an SSL certificate + +{tekton-results} provides a REST API using the HTTPS protocol, which requires an SSL certificate. Provide a secret with this certificate. If you have an existing certificate provided by a certificate authority (CA), use this certificate, otherwise create a self-signed certificate. + +.Prerequisites + +* The `openssl` command-line utility is installed. + +.Procedure + +. If you do not have a certificate provided by a CA, create a self-signed certificate by entering the following command: ++ +[source,terminal] +---- +$ openssl req -x509 \ +-newkey rsa:4096 \ +-keyout key.pem \ +-out cert.pem \ +-days 365 \ +-nodes \ +-subj "/CN=tekton-results-api-service.openshift-pipelines.svc.cluster.local" \ +-addext "subjectAltName = DNS:tekton-results-api-service.openshift-pipelines.svc.cluster.local" +---- ++ +Replace `tekton-results-api-service.openshift-pipelines.svc.cluster.local` with the route endpoint that you plan to use for the {tekton-results} API. + +. Create a transport security layer (TLS) secret from the certificate by entering the following command: ++ +[source,terminal] +---- +$ oc create secret tls -n openshift-pipelines tekton-results-tls --cert=cert.pem --key=key.pem +---- ++ +If you want to use an existing certificate provided by a CA, replace `cert.pem` with the name of the file containing this certificate. diff --git a/modules/op-results-concepts.adoc b/modules/op-results-concepts.adoc new file mode 100644 index 000000000000..a3116a220a5a --- /dev/null +++ b/modules/op-results-concepts.adoc @@ -0,0 +1,172 @@ +// This module is included in the following assembly: +// +// * records/using-tekton-results-for-openshift-pipelines-observability.adoc + +:_content-type: CONCEPT +[id="results-concepts_{context}"] += {tekton-results} concepts + +{tekton-results} archives pipeline runs and task runs in the form of results and records. + +For every `PipelineRun` and `TaskRun` custom resource (CR) that completes running, {tekton-results} creates a _record_. + +A _result_ can contain one or several records. A record is always a part of exactly one result. + +A result corresponds to a pipeline run, and includes the records for the `PipelineRun` CR itself and for all the `TaskRun` CRs that were started as a part of the pipeline run. + +If a task run was started directly, without the use of a pipeline run, a result is created for this task run. This result contains the record for the same task run. + +Each result has a name that includes the namespace in which the `PipelineRun` or `TaskRun` CR was created and the UUID of the CR. The format for the result name is `/results/`. In this format, `` is the UUUD of a pipeline run or else of a task run that was started directly. + +.Example result name +---- +results-testing/results/04e2fbf2-8653-405f-bc42-a262bcf02bed +---- + +Each record has a name that includes name of the result that contains the record, as well as the UUID of the `PipelineRun` or `TaskRun` CR to which the record corresponds. The format for the result name is `/results//results/`. + +.Example record name +---- +results-testing/results/04e2fbf2-8653-405f-bc42-a262bcf02bed/records/e9c736db-5665-441f-922f-7c1d65c9d621 +---- + +The record includes the full YAML manifest of the `TaskRun` or `PipelineRun` CR as it existed after the completion of the run. This manifest contains the specification of the run, any annotation specified for the run, as well as certain information about the results of the run, such as the time when it was completed and whether the run was successful. + +While the `TaskRun` or `PipelineRun` CR exists, you can view the YAML manifest by using the following command: + +[source,terminal] +---- +$ oc get pipelinerun -o yaml +---- + +{tekton-results} preserves this manifest after the `TaskRun` or `PipelineRun` CR is deleted and makes it available for viewing and searching. + +.Example YAML manifest of a pipeline run after its completion +[source,yaml] +---- + kind: PipelineRun + spec: + params: + - name: message + value: five + timeouts: + pipeline: 1h0m0s + pipelineRef: + name: echo-pipeline + serviceAccountName: pipeline + status: + startTime: "2023-08-07T11:41:40Z" + conditions: + - type: Succeeded + reason: Succeeded + status: "True" + message: 'Tasks Completed: 1 (Failed: 0, Cancelled 0), Skipped: 0' + lastTransitionTime: "2023-08-07T11:41:49Z" + pipelineSpec: + tasks: + - name: echo-task + params: + - name: message + value: five + taskRef: + kind: Task + name: echo-task-pipeline + params: + - name: message + type: string + completionTime: "2023-08-07T11:41:49Z" + childReferences: + - kind: TaskRun + name: echo-pipeline-run-gmzrx-echo-task + apiVersion: tekton.dev/v1beta1 + pipelineTaskName: echo-task + metadata: + uid: 62c3b02e-f12b-416c-9771-c02af518f6d4 + name: echo-pipeline-run-gmzrx + labels: + tekton.dev/pipeline: echo-pipeline + namespace: releasetest-js5tt + finalizers: + - chains.tekton.dev/pipelinerun + generation: 2 + annotations: + results.tekton.dev/log: releasetest-js5tt/results/62c3b02e-f12b-416c-9771-c02af518f6d4/logs/c1e49dd8-d641-383e-b708-e3a02b6a4378 + chains.tekton.dev/signed: "true" + results.tekton.dev/record: releasetest-js5tt/results/62c3b02e-f12b-416c-9771-c02af518f6d4/records/62c3b02e-f12b-416c-9771-c02af518f6d4 + results.tekton.dev/result: releasetest-js5tt/results/62c3b02e-f12b-416c-9771-c02af518f6d4 + generateName: echo-pipeline-run- + managedFields: + - time: "2023-08-07T11:41:39Z" + manager: kubectl-create + fieldsV1: + f:spec: + .: {} + f:params: {} + f:pipelineRef: + .: {} + f:name: {} + f:metadata: + f:generateName: {} + operation: Update + apiVersion: tekton.dev/v1 + fieldsType: FieldsV1 + - time: "2023-08-07T11:41:40Z" + manager: openshift-pipelines-controller + fieldsV1: + f:metadata: + f:labels: + .: {} + f:tekton.dev/pipeline: {} + operation: Update + apiVersion: tekton.dev/v1beta1 + fieldsType: FieldsV1 + - time: "2023-08-07T11:41:49Z" + manager: openshift-pipelines-chains-controller + fieldsV1: + f:metadata: + f:finalizers: + .: {} + v:"chains.tekton.dev/pipelinerun": {} + f:annotations: + .: {} + f:chains.tekton.dev/signed: {} + operation: Update + apiVersion: tekton.dev/v1beta1 + fieldsType: FieldsV1 + - time: "2023-08-07T11:41:49Z" + manager: openshift-pipelines-controller + fieldsV1: + f:status: + f:startTime: {} + f:conditions: {} + f:pipelineSpec: + .: {} + f:tasks: {} + f:params: {} + f:completionTime: {} + f:childReferences: {} + operation: Update + apiVersion: tekton.dev/v1beta1 + fieldsType: FieldsV1 + subresource: status + - time: "2023-08-07T11:42:15Z" + manager: openshift-pipelines-results-watcher + fieldsV1: + f:metadata: + f:annotations: + f:results.tekton.dev/log: {} + f:results.tekton.dev/record: {} + f:results.tekton.dev/result: {} + operation: Update + apiVersion: tekton.dev/v1beta1 + fieldsType: FieldsV1 + resourceVersion: "126429" + creationTimestamp: "2023-08-07T11:41:39Z" + deletionTimestamp: "2023-08-07T11:42:23Z" + deletionGracePeriodSeconds: 0 + apiVersion: tekton.dev/v1beta1 +---- + +{tekton-results} also creates a log record that contains the logging information of all the tools that ran as a part of a pipeline run or task run. + +You can access every result and record by its name. You can also use Common Expression Language (CEL) queries to search for results and records by the information they contain, including the YAML manifest. diff --git a/modules/op-results-db.adoc b/modules/op-results-db.adoc new file mode 100644 index 000000000000..516afe6ea151 --- /dev/null +++ b/modules/op-results-db.adoc @@ -0,0 +1,40 @@ +// This module is included in the following assembly: +// +// * records/using-tekton-results-for-openshift-pipelines-observability.adoc + +:_content-type: PROCEDURE +[id="results-db_{context}"] += Preparing a secret with the database credentials + +{tekton-results} uses a PostgreSQL database to store data. You can configure the installation to use either a PostgreSQL server that is automatically installed with {tekton-results} or an external PostgreSQL server that already exists in your deployment. In both cases, provide a secret with the database credentials. + +.Procedure + +Complete one of the following steps: + +* If you do not need to use an external PostgreSQL server, create a secret with the database user named `result` and a random password in the `openshift-pipelines` namespace by entering the following command: ++ +[source,terminal] +---- +$ oc create secret generic tekton-results-postgres \ + --namespace=openshift-pipelines \ + --from-literal=POSTGRES_USER=result \ + --from-literal=POSTGRES_PASSWORD=$(openssl rand -base64 20) +---- ++ +[NOTE] +==== +In this command and in subsequent commads, if you configured a custom target namespace for {pipelines-shortname}, use the name of this namespace instead of `openshift-pipelines`. +==== + +* If you want to use an external PostgreSQL database server to store {tekton-results} data, create a secret with the credentials for this server by entering the following command: ++ +[source,terminal] +---- +$ oc create secret generic tekton-results-postgres \ + --namespace=openshift-pipelines \ + --from-literal=POSTGRES_USER= \ # <1> + --from-literal=POSTGRES_PASSWORD= #<2> +---- ++ +Replace `` with the username for the PostgreSQL user that {tekton-results} must use. Replace `` with the password for the same account. diff --git a/modules/op-results-reference-records.adoc b/modules/op-results-reference-records.adoc new file mode 100644 index 000000000000..f22c2ca957ef --- /dev/null +++ b/modules/op-results-reference-records.adoc @@ -0,0 +1,30 @@ +// This module is included in the following assembly: +// +// * records/using-tekton-results-for-openshift-pipelines-observability.adoc + +:_content-type: REFERENCE +[id="results-reference-records_{context}"] += Reference information for searching records + +You can use the following fields in Common Expression Language (CEL) queries for records: + +.Fields available in CEL queries for records +|=== +| CEL field | Description | Values + +| `name` +| Record name +| + +| `data_type` +| Record type identifier +| `tekton.dev/v1beta1.TaskRun` or `TASK_RUN` +`tekton.dev/v1beta1.PipelineRun` or `PIPELINE_RUN` +`results.tekton.dev/v1alpha2.Log` + +| `data` +| The YAML data for the task run or pipeline run. In log records, this field contains the logging output. +| +|=== + +Because the `data` field contains the entire YAML data for the task run or pipeline run, you can use all elements of this data in your CEL query. For example, `data.status.completionTime` contains the completion time of the task run or pipeline run. diff --git a/modules/op-results-reference-results.adoc b/modules/op-results-reference-results.adoc new file mode 100644 index 000000000000..402d7e99e22c --- /dev/null +++ b/modules/op-results-reference-results.adoc @@ -0,0 +1,45 @@ +// This module is included in the following assembly: +// +// * records/using-tekton-results-for-openshift-pipelines-observability.adoc + +:_content-type: REFERENCE +[id="results-reference-results_{context}"] += Reference information for searching results + +You can use the following fields in Common Expression Language (CEL) queries for results: + +.Fields available in CEL queries for results +|=== +| CEL field | Description + +| `parent` +| The namespace in which the `PipelineRun` or `TaskRun` custom resource (CR) was created. + +| `uid` +| Unique identifier for the result. + +| `annotations` +| Annotations added to the `PipelineRun` or `TaskRun` CR. + +| `summary` +| The summary of the result. + +| `create_time` +| The creation time of the result. + +| `update_time` +| The last update time of the result. +|=== + +You can use the `summary.status` field to determine whether the pipeline run was successful. This field can have the following values: + +* `UNKNOWN` +* `SUCCESS` +* `FAILURE` +* `TIMEOUT` +* `CANCELLED` + +[NOTE] +==== +Do not use quote characters such as `"` or `'` to provide the value for this field. +==== diff --git a/modules/op-results-search-records.adoc b/modules/op-results-search-records.adoc new file mode 100644 index 000000000000..e49e35653a50 --- /dev/null +++ b/modules/op-results-search-records.adoc @@ -0,0 +1,73 @@ +// This module is included in the following assembly: +// +// * records/using-tekton-results-for-openshift-pipelines-observability.adoc + +:_content-type: PROCEDURE +[id="results-search-records_{context}"] += Searching for records + +[role="_abstract"] +You can search for records using Common Expression Language (CEL) queries. As each record contains full YAML information for a pipeline run or task run, you can find records by many different criteria. + +.Prerequisites + +* You installed {tekton-results}. +* You installed the `opc` utility and prepared its environment to query {tekton-results}. + +.Procedure + +* Search for records using a CEL query by entering the following command: ++ +[source,terminal] +---- +$ opc results records list --addr ${RESULTS_API} --filter="" /result/- +---- ++ +Replace `` with the namespace in which the pipeline runs or task runs were created. Alternatively, search for records within a single result by entering the following command: ++ +[source,terminal] +---- +$ opc results records list --addr ${RESULTS_API} --filter="" +---- ++ +Replace `` with the full name of the result. + + +.Example CEL queries for records +|=== +| Purpose | CEL query + +| Records of all task runs or pipeline runs that failed +| `!(data.status.conditions[0].status == 'True')` + +| Records where the name of the `TaskRun` or `PipelineRun` custom resource (CR) was `run1` +| `data.metadata.name == 'run1'` + +| Records for all task runs that were started by the `PipelineRun` CR named `run1` +| `data_type == 'TASK_RUN' && data.metadata.labels['tekton.dev/pipelineRun'] == 'run1'` + +| Records of all pipeline runs and task runs that were created from a `Pipeline` CR named `pipeline1` +| `data.metadata.labels['tekton.dev/pipeline'] == 'pipeline1'` + +| Records of all pipeline runs that were created from a `Pipeline` CR named `pipeline1` +| `data.metadata.labels['tekton.dev/pipeline'] == 'pipeline1' && data_type == 'PIPELINE_RUN'` + +| Records of all task runs where the `TaskRun` CR name stared with `hello` +| `data.metadata.name.startsWith('hello') && data_type=='TASK_RUN'` + +| Records of all pipeline runs that took more than five minutes to complete +| `data.status.completionTime - data.status.startTime > duration('5m') && data_type == 'PIPELINE_RUN'` + +| Records of all pipeline runs and task runs that completed on October 7, 2023 +| `data.status.completionTime.getDate() == 7 && data.status.completionTime.getMonth() == 10 && data.status.completionTime.getFullYear() == 2023` + +| Records of all pipeline runs that included three or more tasks +| `size(data.status.pipelineSpec.tasks) >= 3 && data_type == 'PIPELINE_RUN'` + +| Records of all pipeline runs that had annotations containing `ann1` +| `data.metadata.annotations.contains('ann1') && data_type == 'PIPELINE_RUN'` + +| Records of all pipeline runs that had annotations containing `ann1` and the name of the `PipelineRun` CR started with `hello` +| `data.metadata.annotations.contains('ann1') && data.metadata.name.startsWith('hello') && data_type == 'PIPELINE_RUN'` + +|=== diff --git a/modules/op-results-search-results.adoc b/modules/op-results-search-results.adoc new file mode 100644 index 000000000000..8acb9e25c5b0 --- /dev/null +++ b/modules/op-results-search-results.adoc @@ -0,0 +1,37 @@ +// This module is included in the following assembly: +// +// * records/using-tekton-results-for-openshift-pipelines-observability.adoc + +:_content-type: PROCEDURE +[id="results-search-results_{context}"] += Searching for results + +[role="_abstract"] +You can search for results using Common Expression Language (CEL) queries. For example, you can find results for pipeline runs that did not succeed. However, most of the relevant information is not contained in result objects; to search by the names, completion times, and other data, search for records. + +.Prerequisites + +* You installed {tekton-results}. +* You installed the `opc` utility and prepared its environment to query {tekton-results}. + +.Procedure + +* Search for results using a CEL query by entering the following command: ++ +[source,terminal] +---- +$ opc results list --addr ${RESULTS_API} --filter="" +---- + +Replace `` with the namespace in which the pipeline runs or task runs were created. + +.Example CEL queries for results +|=== +| Purpose | CEL query + +| The results of all runs that failed +| `!(summary.status == SUCCESS)` + +| The results all pipeline runs that contained the annotations `ann1` and `ann2` +| `summary.annotations.contains('ann1') && summary.annotations.contains('ann2') && summary.type=='PIPELINE_RUN'` +|=== diff --git a/modules/op-results-storage.adoc b/modules/op-results-storage.adoc new file mode 100644 index 000000000000..5abbbaca7fad --- /dev/null +++ b/modules/op-results-storage.adoc @@ -0,0 +1,87 @@ +// This module is included in the following assembly: +// +// * records/using-tekton-results-for-openshift-pipelines-observability.adoc + +:_content-type: PROCEDURE +[id="results-storage_{context}"] += Preparing storage for logging information + +{tekton-results} uses separate storage for logging information related to pipeline runs and task runs. You can configure any one of the following types of storage: + +* Persistent volume claim (PVC) on your {product-title} cluster +* Google Cloud Storage +* S3 bucket storage + +.Procedure + +Complete one of the following procedures: + +* To use a PVC, complete the following steps: +.. Create a file named `pvc.yaml` with the following definition for the PVC: ++ +[source,yaml] +---- + apiVersion: v1 + kind: PersistentVolumeClaim + metadata: + name: tekton-logs + spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Gi +---- +.. Apply the definition by entering the following command: ++ +[source,terminal] +---- +$ oc apply -n openshift-pipelines -f pvc.yaml +---- + +* To use Google Cloud Storage, complete the following steps: +.. Create an application credentials file by using the `gcloud` command. For instructions about providing application credentials in a file, see link:https://cloud.google.com/docs/authentication/application-default-credentials#personal[User credentials provided by using the gcloud CLI] in the Google Cloud documentation. +.. Create a secret from the application credentials file by entering the following command: ++ +[source,terminal] +---- +$ oc create secret generic gcs-credentials \ + --from-file=$HOME/.config/gcloud/application_default_credentials.json \ + -n openshift-pipelines +---- ++ +Adjust the path and filename of the application credentials file as necessary. + +* To use S3 bucket storage, complete the following steps: +.. Create a file named `s3_secret.yaml` with the following content: ++ +[source,yaml] +---- + apiVersion: v1 + kind: Secret + metadata: + name: my_custom_secret + namespace: tekton-pipelines + type: Opaque + stringData: + S3_BUCKET_NAME: bucket1 # <1> + S3_ENDPOINT: https://example.localhost.com # <2> + S3_HOSTNAME_IMMUTABLE: "false" + S3_REGION: region-1 # <3> + S3_ACCESS_KEY_ID: "1234" # <4> + S3_SECRET_ACCESS_KEY: secret_key # <5> + S3_MULTI_PART_SIZE: "5242880" +---- +<1> The name of the S3 storage bucket +<2> The S3 API endpoint URL +<3> The S3 region +<4> The S3 access key ID +<5> The S3 secret access key + +.. Create a secret from the file by entering the following command: ++ +[source,terminal] +---- +$ oc create secret generic s3-credentials \ + --from-file=s3_secret.yaml -n openshift-pipelines +---- diff --git a/records/using-tekton-results-for-openshift-pipelines-observability.adoc b/records/using-tekton-results-for-openshift-pipelines-observability.adoc new file mode 100644 index 000000000000..28bbdf0c1c92 --- /dev/null +++ b/records/using-tekton-results-for-openshift-pipelines-observability.adoc @@ -0,0 +1,53 @@ +:_content-type: ASSEMBLY +[id="using-tekton-results-for-openshift-pipelines-observability"] += Using Tekton Results for {pipelines-shortname} observability +include::_attributes/common-attributes.adoc[] +:context: using-tekton-results-for-openshift-pipelines-observability + +toc::[] + +[role="_abstract"] +{tekton-results} is a service that archives the complete information for every pipeline run and task run. You can prune the `PipelineRun` and `TaskRun` resources as necessary and use the {tekton-results} API or the `opc` command line utility to access their YAML manifests as well as logging information. + +:FeatureName: Tekton Results +include::snippets/technology-preview.adoc[] + +include::modules/op-results-concepts.adoc[leveloffset=+1] + +[id="preparing-to-install_using-tekton-results-for-openshift-pipelines-observability"] +== Preparing to install {tekton-results} + +You must complete several preparatory steps before installing {tekton-results}. + +include::modules/op-results-cert.adoc[leveloffset=+2] +include::modules/op-results-db.adoc[leveloffset=+2] +include::modules/op-results-storage.adoc[leveloffset=+2] + + +include::modules/op-installing-results.adoc[leveloffset=+1] + +[id="querying-using-opc_using-tekton-results-for-openshift-pipelines-observability"] +== Querying {tekton-results} using the opc command line utility + +You can use the `opc` command line utility to query {tekton-results} for results and records. To install the `opc` command line utility, install the package for the `tkn` command line utility. For instructions about installing this package, see xref:../tkn_cli/installing-tkn.adoc#installing-tkn[Installing tkn]. + +You can use the names of records and results to retrieve the data in them. + +You can search for results and records using Common Expression Language (CEL) queries. These searches display the UUIDs of the results or records. You can use the provided examples to create queries for common search types. You can also use reference information to create other queries. + +include::modules/op-prepare-opc-for-results.adoc[leveloffset=+2] + +include::modules/op-query-results-name.adoc[leveloffset=+2] + +include::modules/op-results-search-results.adoc[leveloffset=+2] + +include::modules/op-results-search-records.adoc[leveloffset=+2] + +include::modules/op-results-reference-results.adoc[leveloffset=+2] + +include::modules/op-results-reference-records.adoc[leveloffset=+2] + +[role="_additional-resources"] +[id="additional-resources_{context}"] +== Additional resources +* link:https://github.com/google/cel-spec[Common Expression Language specification]