Quick Start
TOC
Installation of Tekton ResultsPrerequisitesInstalling using operator CRDVerify Functionality1. Create aTaskRun resource2. Wait for the task execution to complete3. Use tkn-results CLI to query results4. Turn authentication back onReferencesInstallation of Tekton Results
This document explains how to install Tekton Results using an existing database.
Currently, the built-in PostgreSQL database is not supported, please use an external database.
About external database please refer to Using PostgreSQL from Data Services
Tekton Results supports storing logs in various storage backends. S3-compatible object storage (such as AWS S3, Ceph, MinIO) is now the recommended approach for scalable and durable log retention. For detailed S3 storage configuration, see the S3 Storage Configuration Guide. Local PVC storage is not recommended for production use.
Prerequisites
-
Tekton Pipelines must be installed in the cluster.
TIPThe following instructions assume that you have installed Results into the
tekton-pipelinesnamespace by default.If you have installed it into a different namespace, please replace
tekton-pipelineswith your namespace. -
Store the database account.
Tekton Results connects to PostgreSQL with the user name and password stored in a Kubernetes Secret. Create the
Secretbefore installation, with the database user that Tekton Results connects as, for example a dedicatedresultuser. By default, Tekton Results expects thisSecretto have the following attributes:- Namespace:
tekton-pipelines - Name:
tekton-results-postgres - Including the following fields:
POSTGRES_USER=<your_username>POSTGRES_PASSWORD=<your_password>
You can quickly generate a
Secretusing the following commands. Run theread -rsline on its own, type the database password and press Enter:read -rsdoes not show it, so it does not appear on the screen or in the shell history. In a shell without bracketed paste, such as bash before 5.1,readtakes the next line of a pasted block as the password. Run the commands in bash or zsh: in a POSIXshsuch asdash,read -rsfails and leaves the variable empty:Then create the
Secret.unsetremoves the password from the shell after theSecretis created: - Namespace:
-
Generate a certificate/key pair. Note: Any certificate management software can be used for this purpose!
Tekton Results expects the certificate/key pair to be stored in a TLS Kubernetes Secret named
tekton-results-tls.-
Generate a new self-signed certificate
TIPIf your
opensslversion is too low and does not support some parameters, please upgrade youropensslversion from openssl binaries . -
Create a new TLS Secret from the certificate.
-
-
(For quick start only) Create a
PVCif you are using the legacyFilestorage type (not recommended for production).WARNINGPVC-based local storage is not recommended for production use. S3-compatible object storage is the recommended approach for scalable and durable log retention. For S3 storage configuration, see the S3 Storage Configuration Guide.
If you still need to use PVC for testing purposes:
- Please adjust the PVC size as needed.
- The sample sets no
storageClassName, so the PVC uses the default StorageClass of the cluster, whichkubectl get storageclassmarks with(default). If the cluster has none, addstorageClassName: <storage-class>tospec; without a StorageClass the PVC can stayPending. - Note: This is only required if using the legacy File storage type.
Installing using operator CRD
The operator already created the TektonConfig named config. Merge the following spec.result fields into it; disabled: false installs Tekton Results. The merge keeps the other TektonConfig fields, including spec.targetNamespace, the namespace where Tekton Results is deployed.
DETAILS
The Tekton Results configuration fields below are nested under spec.result in the TektonConfig resource, except targetNamespace, which is spec.targetNamespace.
disabled: Whether Tekton Results is disabled.false: Install Tekton Results.
db_host: The host of the database.db_port: The port of the database.db_name: The name of the database.is_external_db: Must betrue, because the built-in PostgreSQL database is not supported.true: Use an external database.
db_secret_name: The name of the secret containing the database account information.- This is the secret created in the previous step.
server_port: The port of the server.targetNamespace(spec.targetNamespace, not changed by the patch): The namespace where the Results is deployed.auth_disable: Whether to disable authentication.true: For testing only. The Results API skips its Kubernetes RBAC check and allows every request, so anyone who can reach the API can read, change and delete the results, records and logs of every namespace. This includes access through the Ingresstektoncd-results-apithat the Tekton Results installation creates, which serves the API under the path/results. Turn authentication back on after the test as described in Turn authentication back on.
db_enable_auto_migration: Whether to enable automatic database migration.log_level: The level of the log.logs_api: Whether to enable the logs API.true: Enable the logs API.
logs_type: The type of the logs.File: Store logs in a file (not recommended for production use).S3: Store logs in S3-compatible object storage (e.g., AWS S3, Ceph, MinIO). This is the recommended approach for scalable and durable log retention. For detailed configuration, see the S3 Storage Configuration Guide.
secret_name: The name of the secret containing the S3 account information. For detailed configuration, see the S3 Storage Configuration Guide.logs_path: The path of the logs.logs_buffer_size: The buffer size of the logs.logging_pvc_name: The name of the PVC to store the logs (only required when using legacy File storage type).- This is the PVC created in the previous step (not needed for S3 storage).
About more database configuration, please refer to PostgreSQL Configuration
After deployment, you can see that the status of results-api / results-retention-policy-agent / results-watcher is Running. The namespace also holds the Pods of other Tekton components; the output below is shortened to the Tekton Results Pods:
Verify Functionality
Functionality can be verified through a simple taskrun.
1. Create a TaskRun resource
Replace the public alpine image with an image your cluster can pull, for example from an internal registry in an air-gapped environment.
The Tekton webhook rejects a TaskRun with an inline taskSpec when the cluster setting disable-inline-spec contains taskrun (see Constrain Tekton Pipeline Execution with Kyverno); on such a cluster, create a Task with the same step and reference it with taskRef instead.
2. Wait for the task execution to complete
3. Use tkn-results CLI to query results
Preparing the CLI
tkn is a command-line tool for interacting with Tekton. You can download it from the official page.
You need to build tkn-results using golang. Use at least the Go version on the
goline ofgo.modin the branch that you check out: Results v0.19.0 hasgo 1.25.8, so it needs Go 1.25.8 or later.Do not always build from
main. Use the release branch that matches the Tekton Results version deployed in your environment. You can find the Results component version in Release Notes (theResultscolumn), and then checkout the corresponding branchrelease-v<version>.x.
Connection behavior
When
--addris not set,tkn-resultsattempts to auto port-forward to the Results API service.In many versions (including
release-v0.15.x), the auto target istekton-pipelines/tekton-results-api-service. If your Results deployment uses a different namespace or service name, auto mode may fail.When
--addris set,tkn-resultsconnects to that address directly. In that case, you typically need to runkubectl port-forwardyourself.
Querying the execution record list
Fallback when auto port-forward fails
Start the port-forward in a separate terminal and keep it running while you run the tkn results commands; it runs in the foreground until you stop it with Ctrl+C:
Then, in your first terminal:
Querying a single execution record
The sample output comes from an earlier release. In its metadata.finalizers, chains.tekton.dev is the former name of the Chains finalizer of a TaskRun; Chains now names it chains.tekton.dev/taskrun.
Querying the log list
Querying a single log
With
logs_typeFileorS3, the types that this page sets, the Results API serves only the v1alpha2 Logs API.logs gettherefore needs the--v1alpha2flag; without it, the command fails withunknown service tekton.results.v1alpha3.Logs.logs getuses the flag to call the v1alpha2 Logs API, even where the CLI marks the flag as deprecated.
4. Turn authentication back on
The installation patch sets auth_disable: true, which is for testing only. After the test, save the following merge patch as results-auth-patch.yaml:
Merge it, then repeat the second command until it prints AUTH_DISABLE=false. If it keeps printing AUTH_DISABLE=true, read the TektonConfig conditions with the third command. The Operator applies the Pipelines, event-based Pruner, Triggers and Chains components before Tekton Results and stops at a component that it cannot apply; the ComponentsReady condition is then False with a message that starts with Components not in ready state: and names that component:
The Results API reads this setting only when it starts. Delete its Pod so that the Deployment starts a new one with the setting, then check that the new Pod is Running: