Skip to content

Commit 8afa09c

Browse files
xenolinuxxenolinux
authored
Merge pull request #95134 from mramendi/RHDEVDOCS-6414
RHDEVDOCS 6414 new Results CLI
2 parents 27ec1ba + 7ba2be1 commit 8afa09c

11 files changed

+422
-6
lines changed

‎modules/op-prepare-opc-for-results.adoc‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ Before you can query {tekton-results}, you must prepare the environment for the
1212
.Prerequisites
1313

1414
* You installed the `opc` utility.
15+
* You logged on to the {OCP} cluster by using the {oc-first}.
1516
1617
.Procedure
1718

@@ -29,6 +30,8 @@ $ export RESULTS_API=$(oc get route tekton-results-api-service -n openshift-pipe
2930
$ oc create token <service_account>
3031
----
3132
+
33+
Replace `<service_account>` with the name of an {OCP} service account that has read access to the namespaces where {pipelines-shortname} ran the pipeline runs and task runs.
34+
+
3235
Save the string that this command outputs.
3336

3437
. Optional: Create the `~/.config/tkn/results.yaml` file for automatic authentication with the {tekton-results} API. The file must have the following contents:

‎modules/op-query-results-name.adoc‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,13 +21,13 @@ You can list and query results and records using their names.
2121
+
2222
[source,terminal]
2323
----
24-
$ opc results list --addr ${RESULTS_API} <namespace_name>
24+
$ opc results result list --addr ${RESULTS_API} <namespace_name>
2525
----
2626
+
2727
.Example command
2828
[source,terminal]
2929
----
30-
$ opc results list --addr ${RESULTS_API} results-testing
30+
$ opc results result list --addr ${RESULTS_API} results-testing
3131
----
3232
+
3333
.Example output

‎modules/op-results-concepts.adoc‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -170,4 +170,6 @@ $ oc get pipelinerun <cr_name> -o yaml
170170

171171
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.
172172

173-
You can also configure {tekton-results} to facilitate forwarding the logging information of all the tools that ran as a part of a pipeline or task to LokiStack. You can then query {tekton-results} for logging information of the task run associated with a {tekton-results} record.
173+
You can configure {tekton-results} to facilitate forwarding the logging information of all the tools that ran as a part of a pipeline or task to LokiStack. You can then query {tekton-results} for logging information of the task run associated with a {tekton-results} record.
174+
175+
You can also query results and logs by the names of pipeline runs and task runs.

‎modules/op-results-opc-config.adoc‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
// This module is included in the following assembly:
2+
//
3+
// * records/using-tekton-results-for-openshift-pipelines-observability.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="results-opc-config_{context}"]
7+
= Configuring the opc utility for querying results by pipeline run and task run names
8+
9+
[role="_abstract"]
10+
Before you can query results from {tekton-results} by pipeline run and task run names, you must configure the `opc` utility.
11+
12+
.Prerequisites
13+
14+
* You installed the `opc` utility.
15+
* You logged on to the {OCP} cluster by using the {oc-first}.
16+
17+
.Procedure
18+
19+
. Create an authentication token for the {tekton-results} API by entering the following command:
20+
+
21+
[source,terminal]
22+
----
23+
$ oc create token <service_account>
24+
----
25+
+
26+
Replace `<service_account>` with the name of an {OCP} service account that has read access to the namespaces where {pipelines-shortname} ran the pipeline runs and task runs.
27+
+
28+
Save the string that this command outputs.
29+
30+
. Complete one of the following steps:
31+
32+
** Configure the `opc` utility interactively by entering the following command:
33+
+
34+
[source,terminal]
35+
----
36+
$ opc results config set
37+
----
38+
+
39+
Reply to the prompts that the utility displays. For `Token`, enter the authentication token that you created.
40+
41+
** Configure the `opc` utility from a command by entering the following command:
42+
+
43+
[source,terminal]
44+
----
45+
$ opc results config set --host="https://tekton-results.example.com" --token="<token>"
46+
----
47+
+
48+
Replace the host name with the fully qualified domain name of your {tekton-results} route. Replace `<token>` with the authentication token that you generated.
49+
50+
.Verification
51+
52+
* You can view the configuration that you set for the `opc` utility by entering the following command:
53+
+
54+
[source,terminal]
55+
----
56+
$ opc results config view
57+
----
58+
+
59+
.Example output
60+
[source,terminal]
61+
----
62+
api-path: ""
63+
apiVersion: results.tekton.dev/v1alpha2
64+
host: https://tekton-results.openshiftapps.com
65+
insecure-skip-tls-verify: "true"
66+
kind: Client
67+
token: sha256~xyz
68+
----

‎modules/op-results-opc-pipelinerunlist.adoc‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
// This module is included in the following assembly:
2+
//
3+
// * records/using-tekton-results-for-openshift-pipelines-observability.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="results-opc-pipelinerunlist_{context}"]
7+
= Viewing a list of pipeline run names and identifiers
8+
9+
[role="_abstract"]
10+
You can use the `opc` utility to view a list of names and identifiers of pipeline runs in a namespace.
11+
12+
.Prerequisites
13+
14+
* You installed the `opc` utility.
15+
* You configured the `opc` utility to query results from {tekton-results} by pipeline run and task run names.
16+
17+
.Procedure
18+
19+
* Use any of the following commands to view pipeline runs:
20+
21+
** To view all pipeline runs in a specified namespace, enter the following command:
22+
+
23+
[source,terminal]
24+
----
25+
$ opc results pipelinerun list -n <namespace_name>
26+
----
27+
+
28+
Optionally, specify the `--limit` command line option, for example, `--limit=10`. With this setting, the `opc` command displays the specified number of lines containing pipeline run names and then exits. If you add the `--single-page=false` command line option, the command displays the specified number of lines and then prompts you to continue or quit.
29+
+
30+
Optionally, specify the `--labels` command line option, for example, `--labels="app.kubernetes.io/name=test-app, app.kubernetes.io/component=database`. With this setting, the list includes only the pipeline runs that have the specified labels or annotations.
31+
+
32+
.Example output of the `opc results pipelinerun list` command
33+
+
34+
[source,terminal]
35+
----
36+
NAME UID STARTED DURATION STATUS
37+
openshift-pipelines-main-release-tests-zscq8 78515e3a-8e20-43e8-a064-d2442c2ae845 1 week ago 5s Failed(CouldntGetPipeline)
38+
openshift-pipelines-main-release-tests-zrgv6 14226144-2d08-440d-a600-d602ca46cdf6 1 week ago 26m13s Failed
39+
openshift-pipelines-main-release-tests-jdc24 e34daea2-66fb-4c7d-9d4b-d9d82a07b6cd 1 week ago 5s Failed(CouldntGetPipeline)
40+
openshift-pipelines-main-release-tests-6zj7f 9b3e5d68-70ab-4c23-8872-e7ad7121e60b 1 week ago 5s Failed(CouldntGetPipeline)
41+
openshift-pipelines-main-release-tests-kkk9t 2fd28c48-388b-4e6a-9ec3-2bcd9dedebc3 1 week ago 5s Failed(CouldntGetPipeline)
42+
----
43+
44+
** To view pipeline runs related to specified named pipelines, enter the following command:
45+
+
46+
[source,terminal]
47+
----
48+
$ opc results pipelinerun list <pipeline_name> -n <namespace_name>
49+
----
50+
+
51+
The command lists all pipeline runs for pipelines that have names containing `<pipeline_name>`. For example, if you specify `build`, the command displays all pipeline runs related to pipelines named `build`, `build_123`, or `enhancedbuild`.
52+
+
53+
Optionally, specify the `--limit` command line option, for example, `--limit=10`. With this setting, the `opc` command displays the specified number of lines containing pipeline run names and then exits. If you add the `--single-page=false` command line option, the command displays the specified number of lines and then prompts you to continue or quit.

‎modules/op-results-opc-pipelinerunresults.adoc‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
// This module is included in the following assembly:
2+
//
3+
// * records/using-tekton-results-for-openshift-pipelines-observability.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="results-opc-pipelinerunresults_{context}"]
7+
= Viewing result information for a pipeline run
8+
9+
[role="_abstract"]
10+
You can use the `opc` utility to view a description of when and how a pipeline run completed, a full manifest for the pipeline run, and any logs that the pipeline run produced.
11+
12+
.Prerequisites
13+
14+
* You installed the `opc` utility.
15+
* You configured the `opc` utility to query results from {tekton-results} by pipeline run and task run names.
16+
* You have the name or UUID of the pipeline run. You can use the `ocp results list pipelineruns` commands to view names and UUIDs of pipeline runs for which results are available.
17+
18+
.Procedure
19+
20+
* Use any of the following commands to view the result information for a pipeline run:
21+
** To view a description of when and how the pipeline run completed, enter the following command:
22+
+
23+
[source,terminal]
24+
----
25+
$ opc results pipelinerun describe -n <namespace_name> <pipelinerun_name>
26+
----
27+
+
28+
Alternatively, you can use the pipeline run UUID instead of the name:
29+
+
30+
[source,terminal]
31+
----
32+
$ opc results pipelinerun describe -n <namespace_name> --uid <pipelinerun_uuid>
33+
----
34+
+
35+
.Example output of the `opc results pipelinerun describe` command
36+
[source,terminal]
37+
----
38+
Name: operator-main-index-4-18-on-pull-request-7kssl
39+
Namespace: tekton-ecosystem-tenant
40+
Service Account: appstudio-pipeline
41+
Labels:
42+
app.kubernetes.io/managed-by=pipelinesascode.tekton.dev
43+
app.kubernetes.io/version=v0.33.0
44+
Annotations:
45+
appstudio.openshift.io/snapshot=openshift-pipelines-main-b7jj6
46+
build.appstudio.openshift.io/repo=https://github.com/openshift-pipelines/operator?rev=ba5e62e51af0c88bc6c3fd4201e789bdfc093daa
47+
48+
📌 Status
49+
STARTED DURATION STATUS
50+
27d ago 9m54s Succeeded
51+
52+
⏱ Timeouts
53+
Pipeline: 2h0m0s
54+
55+
⚓ Params
56+
NAME VALUE
57+
• git-url https://github.com/pramodbindal/operator
58+
• revision ba5e62e51af0c88bc6c3fd4201e789bdfc093daa
59+
60+
🗂 Workspaces
61+
NAME SUB PATH WORKSPACE BINDING
62+
• workspace --- VolumeClaimTemplate
63+
• git-auth --- Secret (secret=pac-gitauth-ceqzjt)
64+
65+
📦 Taskruns
66+
NAME TASK NAME
67+
• operator-main-index-4-18-on-pull-request-7kssl-init init
68+
• operator-main-index-4-18-on-pull-request-7kssl-clone-repository clone-repository
69+
----
70+
71+
* To view the full YAML manifest of the pipeline run, enter the following command:
72+
+
73+
[source,terminal]
74+
----
75+
$ opc results pipelinerun describe -n <namespace_name> --output yaml <pipelinerun_name>
76+
----
77+
+
78+
Alternatively, you can use the pipeline run UUID instead of the name:
79+
+
80+
[source,terminal]
81+
----
82+
$ opc results pipelinerun describe -n <namespace_name> --output yaml --uid <pipelinerun_uuid>
83+
----
84+
85+
* To view the logs associated with the pipeline run, enter the following command:
86+
+
87+
[source,terminal]
88+
----
89+
$ opc results pipelinerun logs -n <namespace_name> <pipelinerun_name>
90+
----
91+
+
92+
Alternatively, you can use the pipeline run UUID instead of the name:
93+
+
94+
[source,terminal]
95+
----
96+
$ opc results pipelinerun logs -n <namespace_name> --uid <pipelinerun_uuid>
97+
----
98+
99+
[IMPORTANT]
100+
====
101+
Logs that the `opc results pipelinerun logs` displays do not include logs of task runs that completed within this pipeline run. To view these logs, find the names of the task runs in this pipeline run using the `opc results taskrun list --pipelinerun` command and specify the name of the pipeline run. Then use the `opc results taskrun log` command to view the logs for the task runs.
102+
====

‎modules/op-results-opc-shortnames.adoc‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
// This module is included in the following assembly:
2+
//
3+
// * records/using-tekton-results-for-openshift-pipelines-observability.adoc
4+
5+
:_mod-docs-content-type: REFERENCE
6+
[id="results-opc-shortnames_{context}"]
7+
= Short names for command-line arguments
8+
9+
When using the `opc` utility to query results from {tekton-results} by pipeline run and task run names, you can replace long command-line arguments with short versions of their names.
10+
11+
.Short names for command-line parameters
12+
[cols="1,1",options="header"]
13+
|===
14+
| Full parameter name | Short parameter name
15+
16+
| `pipelinerun` | `pr`
17+
| `taskrun` | `tr`
18+
| `describe` | `desc`
19+
20+
|===

‎modules/op-results-opc-taskrunlist.adoc‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
// This module is included in the following assembly:
2+
//
3+
// * records/using-tekton-results-for-openshift-pipelines-observability.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="results-opc-taskrunlist_{context}"]
7+
= Viewing a list of task run names and identifiers
8+
9+
[role="_abstract"]
10+
You can use the `opc` utility to view a lists of names and identifiers of task runs in a namespace or of task runs associated with a pipeline dun.
11+
12+
.Prerequisites
13+
14+
* You installed the `opc` utility.
15+
* You configured the `opc` utility to query results from {tekton-results} by pipeline run and task run names.
16+
17+
.Procedure
18+
19+
* To view a list of all task runs in a namespace, enter the following command:
20+
+
21+
[source,terminal]
22+
----
23+
$ opc results taskrun list -n <namespace_name>
24+
----
25+
+
26+
Optionally, specify the `--limit` command line option, for example, `--limit=10`. With this setting, the `opc` command displays the specified number of lines containing pipeline run names and then exits. If you add the `--single-page=false` command line option, the command displays the specified number of lines and then prompts you to continue or quit.
27+
+
28+
Optionally, specify the `--labels` parameter, for example, `--labels="app.kubernetes.io/name=test-app, app.kubernetes.io/component=database`. With this setting, the list includes only the task runs that have the specified labels or annotations.
29+
+
30+
.Example output of the `opc results pipelinerun list` command for a namespace
31+
+
32+
[source,terminal]
33+
----
34+
NAME UID STARTED DURATION STATUS
35+
openshift-pipelines-main-release-tests-zrgv6-e2e-test 10d6952f-b926-4e4b-a976-519867969ce7 16d ago 12m41s Failed
36+
openshift-pipelines-main-release-tests-zrgv6-deploy-operator ab41b63b-16ec-4a32-8b95-f2678eb5c945 16d ago 22s Succeeded
37+
openshift-pipelines-main-release-tests-zrgv6-provision-cluster b374df00-5132-4633-91df-3259670756b3 16d ago 12m30s Succeeded
38+
operator-main-index-4-18-on-pull-request-ml4ww-show-sbom c5b77784-cd87-4be8-bc12-28957762f382 16d ago 16s Succeeded
39+
openshift-c4ae3a5a28e19ffc930e7c2aa758d85c-provision-eaas-space 22535d8e-d360-4143-9c0c-4bd0414a22b0 16d ago 17s Succeeded
40+
----
41+
42+
* To view a list of task runs associate with a pipeline run, enter the following command:
43+
+
44+
[source,terminal]
45+
----
46+
$ opc results taskrun list --pipelinerun <pipelinerun_name> -n <namespace_name>
47+
----
48+
+
49+
Optionally, specify the `--limit` command line option, for example, `--limit=10`. With this setting, the `opc` command displays the specified number of lines containing pipeline run names and then exits. If you add the `--single-page=false` command line option, the command displays the specified number of lines and then prompts you to continue or quit.
50+
51+
.Example output of the `opc results taskrun list` command for a pipeline run
52+
+
53+
[source,terminal]
54+
----
55+
NAME UID STARTED DURATION STATUS
56+
operator-main-index-4-18-on-pull-request-g95fk-show-sbom 5b405941-0d3e-4f8c-a68a-9ffcc481abf1 16d ago 13s Succeeded
57+
operator-main-index-4-18-on-pul2b222db723593a186d12f1b82f1a1fd9 89588ae7-aa36-4b62-97d1-5634ee201850 16d ago 36s Succeeded
58+
operator-fb80434867bc15d89fea82506058f664-fbc-fips-check-oci-ta 7598d44a-4370-459b-8ef0-ae4165c58ba5 16d ago 5m52s Succeeded
59+
operator-main-index-4-18-on-pull-request-g95fk-validate-fbc fb80d962-807b-4b63-80cb-6a57d383755a 16d ago 1m26s Succeeded
60+
operator-main-index-4-18-on-pull-request-g95fk-apply-tags 8a34b46d-74a9-4f20-9e99-a285f7b258d6 16d ago 13s Succeeded
61+
----

0 commit comments

Comments
 (0)