improve tkn-results help docs and fix lint errors

- add example for get and list - regenerate cli docs - add makefile entry for generating docs - fix golangci-lint and goimports errors Signed-off-by: Avinal Kumar <[email protected]>
tektoncd · Nov 13, 2023 · 7f632ad · 7f632ad
1 parent 4a61d7b
commit 7f632ad
Show file tree

Hide file tree

Showing 26 changed files with 503 additions and 64 deletions.
diff --git a/Makefile b/Makefile
@@ -98,6 +98,10 @@ goimports: | $(GOIMPORTS) ; $(info $(M) running goimports…) ## Run goimports
 fmt: ; $(info $(M) running gofmt…) @ ## Run gofmt on all source files
 	$Q $(GO) fmt $(PKGS)
 
+.PHONY: cli-docs
+cli-docs: ; $(info $(M) generating tkn-results docs) ## Generate tkn-results docs
+	$(GO) run ./cmd/cli-docs
+
 # Misc
 
 .PHONY: clean

diff --git a/cmd/tkn-results/README.md b/cmd/tkn-results/README.md
@@ -0,0 +1,7 @@
+# tkn-results
+
+tkn CLI plugin for interacting with the Tekton Results API.
+
+## Usage
+
+See [CLI docs](../../docs/cli/tkn-results.md)
diff --git a/cmd/tkn-results/main.go b/cmd/tkn-results/main.go
@@ -2,9 +2,14 @@ package main
 
 import (
 	"context"
+	"os"
+
 	"github.com/tektoncd/results/pkg/cli/cmd"
 )
 
 func main() {
-	cmd.Root().ExecuteContext(context.Background())
+	err := cmd.Root().ExecuteContext(context.Background())
+	if err != nil {
+		os.Exit(1)
+	}
 }
diff --git a/docs/cli/tkn-results.md b/docs/cli/tkn-results.md
@@ -0,0 +1,60 @@
+## tkn-results
+
+tkn CLI plugin for Tekton Results API
+
+### Synopsis
+
+Environment Variables:
+    TKN_RESULTS_SSL_ROOTS_FILE_PATH: Path to local SSL cert to use.
+    TKN_RESULTS_SSL_SERVER_NAME_OVERRIDE: SSL server name override (useful if using with a proxy such as kubectl port-forward).
+
+Config:
+    A config file may be stored in `~/.config/tkn/results.yaml` to configure the CLI client.
+
+    Fields:
+    - address: Results API Server address
+    - service_account: When specified, the CLI will first fetch a bearer token
+                       for the specified ServiceAccount and attach that to Result API requests.
+        - namespace: ServiceAccount namespace
+        - name: ServiceAccount name
+    - token: Bearer token to use for API requests. Takes priority over service_account.
+    - ssl: SSL connection options
+        - roots_file_path: Path to a certificate to include in the cert pool. Useful for adding allowed self-signed certs.
+        - server_name_override: For testing only. Sets the grpc.ssl_target_name_override value for requests.
+    - portforward: enable auto portforwarding to tekton-results-api-service when address is set and portforward is true, tkn-results will portforward tekton-results-api-service automatically
+
+Example:
+
+    ```
+    address: results.dogfooding.tekton.dev:443
+    token: abcd1234
+    ssl:
+        roots_file_path: path/to/file
+        server_name_override: example.com
+    service_account:
+        namespace: default
+        name: result-reader
+    portforward: false
+    ```
+
+
+
+### Options
+
+```
+  -a, --addr string        Result API server address. If not specified, tkn-result would port-forward to service/tekton-results-api-service automatically
+  -t, --authtoken string   authorization bearer token to use for authenticated requests
+  -h, --help               help for tkn-results
+      --insecure           determines whether to run insecure GRPC tls request
+      --portforward        enable auto portforwarding to tekton-results-api-service, when addr is set and portforward is true, tkn-results will portforward tekton-results-api-service automatically (default true)
+      --sa string          ServiceAccount to use instead of token for authorization and authentication
+      --sa-ns string       ServiceAccount Namespace, if not given, it will be taken from current context
+```
+
+### SEE ALSO
+
+* [tkn-results list](tkn-results_list.md)	 - List Results
+* [tkn-results logs](tkn-results_logs.md)	 - Commands for finding and retrieving logs
+* [tkn-results records](tkn-results_records.md)	 - Command sub-group for querying Records
+
+###### Auto generated by spf13/cobra on 13-Nov-2023
diff --git a/docs/cli/tkn-results_list.md b/docs/cli/tkn-results_list.md
@@ -0,0 +1,36 @@
+## tkn-results list
+
+List Results
+
+```
+tkn-results list [flags] <parent>
+
+  <parent>: Parent name to query. This is typically corresponds to a namespace, but may vary depending on the API Server. "-" may be used to query all parents.
+```
+
+### Options
+
+```
+  -f, --filter string   CEL Filter
+  -h, --help            help for list
+  -l, --limit int32     number of items to return. Response may be truncated due to server limits.
+  -o, --output string   output format. Valid values: tab|textproto|json (default "tab")
+  -p, --page string     pagination token to use for next page
+```
+
+### Options inherited from parent commands
+
+```
+  -a, --addr string        Result API server address. If not specified, tkn-result would port-forward to service/tekton-results-api-service automatically
+  -t, --authtoken string   authorization bearer token to use for authenticated requests
+      --insecure           determines whether to run insecure GRPC tls request
+      --portforward        enable auto portforwarding to tekton-results-api-service, when addr is set and portforward is true, tkn-results will portforward tekton-results-api-service automatically (default true)
+      --sa string          ServiceAccount to use instead of token for authorization and authentication
+      --sa-ns string       ServiceAccount Namespace, if not given, it will be taken from current context
+```
+
+### SEE ALSO
+
+* [tkn-results](tkn-results.md)	 - tkn CLI plugin for Tekton Results API
+
+###### Auto generated by spf13/cobra on 13-Nov-2023
diff --git a/docs/cli/tkn-results_logs.md b/docs/cli/tkn-results_logs.md
@@ -0,0 +1,28 @@
+## tkn-results logs
+
+Commands for finding and retrieving logs
+
+### Options
+
+```
+  -h, --help   help for logs
+```
+
+### Options inherited from parent commands
+
+```
+  -a, --addr string        Result API server address. If not specified, tkn-result would port-forward to service/tekton-results-api-service automatically
+  -t, --authtoken string   authorization bearer token to use for authenticated requests
+      --insecure           determines whether to run insecure GRPC tls request
+      --portforward        enable auto portforwarding to tekton-results-api-service, when addr is set and portforward is true, tkn-results will portforward tekton-results-api-service automatically (default true)
+      --sa string          ServiceAccount to use instead of token for authorization and authentication
+      --sa-ns string       ServiceAccount Namespace, if not given, it will be taken from current context
+```
+
+### SEE ALSO
+
+* [tkn-results](tkn-results.md)	 - tkn CLI plugin for Tekton Results API
+* [tkn-results logs get](tkn-results_logs_get.md)	 - Get Log by <log-name>
+* [tkn-results logs list](tkn-results_logs_list.md)	 - List Logs for a given Result
+
+###### Auto generated by spf13/cobra on 13-Nov-2023
diff --git a/docs/cli/tkn-results_logs_get.md b/docs/cli/tkn-results_logs_get.md
@@ -0,0 +1,53 @@
+## tkn-results logs get
+
+Get Log by <log-name>
+
+### Synopsis
+
+Get Log by <log-name>. <log-name> is typically of format <namespace>/results/<parent-run-uuid>/logs/<child-run-uuid>
+
+```
+tkn-results logs get [flags] <log-name>
+```
+
+### Examples
+
+```
+  Lets assume, there is a PipelineRun in 'default' namespace (parent) with:
+  PipelineRun UUID: 0dfc883d-722a-4489-9ab8-3cccc74ca4f6 (parent)
+  TaskRun 1 UUID: db6a5d59-2170-3367-9eb5-83f3d264ec62 (child 1)
+  TaskRun 2 UUID: 9514f318-9329-485b-871c-77a4a6904891 (child 2)
+
+  - Get the log for TaskRun 1:
+    tkn-results logs get default/results/0dfc883d-722a-4489-9ab8-3cccc74ca4f6/logs/db6a5d59-2170-3367-9eb5-83f3d264ec62
+  
+  - Get log for TaskRun 2:
+    tkn-results logs get default/results/0dfc883d-722a-4489-9ab8-3cccc74ca4f6/logs/9514f318-9329-485b-871c-77a4a6904891
+  
+  - Get log for the PipelineRun:
+    tkn-results logs get default/results/0dfc883d-722a-4489-9ab8-3cccc74ca4f6/logs/0dfc883d-722a-4489-9ab8-3cccc74ca4f6
+```
+
+### Options
+
+```
+  -h, --help            help for get
+  -o, --output string   output format. Valid values: textproto|json (default "json")
+```
+
+### Options inherited from parent commands
+
+```
+  -a, --addr string        Result API server address. If not specified, tkn-result would port-forward to service/tekton-results-api-service automatically
+  -t, --authtoken string   authorization bearer token to use for authenticated requests
+      --insecure           determines whether to run insecure GRPC tls request
+      --portforward        enable auto portforwarding to tekton-results-api-service, when addr is set and portforward is true, tkn-results will portforward tekton-results-api-service automatically (default true)
+      --sa string          ServiceAccount to use instead of token for authorization and authentication
+      --sa-ns string       ServiceAccount Namespace, if not given, it will be taken from current context
+```
+
+### SEE ALSO
+
+* [tkn-results logs](tkn-results_logs.md)	 - Commands for finding and retrieving logs
+
+###### Auto generated by spf13/cobra on 13-Nov-2023
diff --git a/docs/cli/tkn-results_logs_list.md b/docs/cli/tkn-results_logs_list.md
@@ -0,0 +1,49 @@
+## tkn-results logs list
+
+List Logs for a given Result
+
+### Synopsis
+
+List Logs for a given Result. <result-name> is typically of format <namespace>/results/<parent-run-uuid>. '-' may be used in place of <parent-run-uuid> to query all Logs for a given parent.
+
+```
+tkn-results logs list [flags] <result-name>
+```
+
+### Examples
+
+```
+  - List all Logs for PipelineRun with UUID 0dfc883d-722a-4489-9ab8-3cccc74ca4f6 in 'default' namespace:
+    tkn-results logs list default/results/0dfc883d-722a-4489-9ab8-3cccc74ca4f6
+  - List all logs for all Runs in 'default' namespace:
+    tkn-results logs list default/results/-
+  - List only TaskRuns logs in 'default' namespace:
+    tkn-results logs list default/results/- --filter="data.spec.resource.kind=TaskRun"
+```
+
+### Options
+
+```
+  -f, --filter string   CEL Filter
+  -h, --help            help for list
+  -l, --limit int32     number of items to return. Response may be truncated due to server limits.
+  -o, --output string   output format. Valid values: tab|textproto|json (default "tab")
+  -p, --page string     pagination token to use for next page
+```
+
+### Options inherited from parent commands
+
+```
+  -a, --addr string        Result API server address. If not specified, tkn-result would port-forward to service/tekton-results-api-service automatically
+  -t, --authtoken string   authorization bearer token to use for authenticated requests
+      --insecure           determines whether to run insecure GRPC tls request
+      --portforward        enable auto portforwarding to tekton-results-api-service, when addr is set and portforward is true, tkn-results will portforward tekton-results-api-service automatically (default true)
+      --sa string          ServiceAccount to use instead of token for authorization and authentication
+      --sa-ns string       ServiceAccount Namespace, if not given, it will be taken from current context
+```
+
+### SEE ALSO
+
+* [tkn-results logs](tkn-results_logs.md)	 - Commands for finding and retrieving logs
+
+###### Auto generated by spf13/cobra on 13-Nov-2023
diff --git a/docs/cli/tkn-results_records.md b/docs/cli/tkn-results_records.md
@@ -0,0 +1,28 @@
+## tkn-results records
+
+Command sub-group for querying Records
+
+### Options
+
+```
+  -h, --help   help for records
+```
+
+### Options inherited from parent commands
+
+```
+  -a, --addr string        Result API server address. If not specified, tkn-result would port-forward to service/tekton-results-api-service automatically
+  -t, --authtoken string   authorization bearer token to use for authenticated requests
+      --insecure           determines whether to run insecure GRPC tls request
+      --portforward        enable auto portforwarding to tekton-results-api-service, when addr is set and portforward is true, tkn-results will portforward tekton-results-api-service automatically (default true)
+      --sa string          ServiceAccount to use instead of token for authorization and authentication
+      --sa-ns string       ServiceAccount Namespace, if not given, it will be taken from current context
+```
+
+### SEE ALSO
+
+* [tkn-results](tkn-results.md)	 - tkn CLI plugin for Tekton Results API
+* [tkn-results records get](tkn-results_records_get.md)	 - Get Record by <record-name>
+* [tkn-results records list](tkn-results_records_list.md)	 - List Records for a given Result
+
+###### Auto generated by spf13/cobra on 13-Nov-2023
diff --git a/docs/cli/tkn-results_records_get.md b/docs/cli/tkn-results_records_get.md
@@ -0,0 +1,53 @@
+## tkn-results records get
+
+Get Record by <record-name>
+
+### Synopsis
+
+Get Record by <record-name>. <record-name> is typically of format <namespace>/results/<parent-run-uuid>/records/<child-run-uuid>
+
+```
+tkn-results records get [flags] <record-name>
+```
+
+### Examples
+
+```
+  Lets assume, there is a PipelineRun in 'default' namespace (parent) with:
+  PipelineRun UUID: 0dfc883d-722a-4489-9ab8-3cccc74ca4f6 (parent)
+  TaskRun 1 UUID: db6a5d59-2170-3367-9eb5-83f3d264ec62 (child 1)
+  TaskRun 2 UUID: 9514f318-9329-485b-871c-77a4a6904891 (child 2)
+
+  - Get the record for TaskRun 1:
+    tkn-results records get default/results/0dfc883d-722a-4489-9ab8-3cccc74ca4f6/records/db6a5d59-2170-3367-9eb5-83f3d264ec62
+
+  - Get the record for TaskRun 2:
+    tkn-results records get default/results/0dfc883d-722a-4489-9ab8-3cccc74ca4f6/records/9514f318-9329-485b-871c-77a4a6904891
+
+  - Get the record for PipelineRun:
+    tkn-results records get default/results/0dfc883d-722a-4489-9ab8-3cccc74ca4f6/records/0dfc883d-722a-4489-9ab8-3cccc74ca4f6
+```
+
+### Options
+
+```
+  -h, --help            help for get
+  -o, --output string   output format. Valid values: textproto|json (default "json")
+```
+
+### Options inherited from parent commands
+
+```
+  -a, --addr string        Result API server address. If not specified, tkn-result would port-forward to service/tekton-results-api-service automatically
+  -t, --authtoken string   authorization bearer token to use for authenticated requests
+      --insecure           determines whether to run insecure GRPC tls request
+      --portforward        enable auto portforwarding to tekton-results-api-service, when addr is set and portforward is true, tkn-results will portforward tekton-results-api-service automatically (default true)
+      --sa string          ServiceAccount to use instead of token for authorization and authentication
+      --sa-ns string       ServiceAccount Namespace, if not given, it will be taken from current context
+```
+
+### SEE ALSO
+
+* [tkn-results records](tkn-results_records.md)	 - Command sub-group for querying Records
+
+###### Auto generated by spf13/cobra on 13-Nov-2023