#Database Configuration

This document describes how to configure the database required for Tekton Results.

#Prerequisites

#Cluster Requirements

• Tekton Operator must be installed in the cluster.

#Database Requirements

Version:

• PostgreSQL 12 or higher
• Recommended to use newer versions for longer maintenance support

Database Setup:

• Database must already exist
• Database should be empty (Tekton Results will automatically create required table structures)
• Ensure the database user has permissions to create tables

Create Database Command:

CREATE DATABASE tekton_results;

#Configuration Overview

Tekton Results supports using external PostgreSQL databases. The configuration is divided into two parts:

1. Database credentials (username and password) are stored in Kubernetes Secrets
2. Database connection parameters (host, port, database name, SSL settings) are configured in the TektonResult custom resource

#Configuration Parameters Reference

The valid options for db_sslmode are explained here https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-PROTECTION.

#Basic Configuration

For a basic external database setup without SSL, follow these steps:

#1. Create Database Credentials

Required Fields in Secret:

Create Secret Command:

kubectl create secret generic tekton-results-postgres \
  --namespace="tekton-pipelines" \
  --from-literal=POSTGRES_USER=result \
  --from-literal=POSTGRES_PASSWORD=your_secure_password

Secret YAML Example:

apiVersion: v1
kind: Secret
type: Opaque
metadata:
  name: tekton-results-postgres
data:
  POSTGRES_USER: <base64 encoded username>
  POSTGRES_PASSWORD: <base64 encoded password>

#2. Configure TektonResult Resource

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonResult
metadata:
  name: result
spec:
  is_external_db: true
  db_host: your-postgres-host.example.com
  db_port: 5432
  db_name: tekton_results
  db_sslmode: allow
  secret_name: tekton-results-postgres

#3. Verify Configuration

kubectl get tektonresults.operator.tekton.dev result
kubectl get pods -n tekton-pipelines -l app.kubernetes.io/name=tekton-results-api

#Advanced Configuration

#SSL Configuration

When secure database connections are required, you can configure SSL-related parameters:

SSL Mode Selection Guide:

SSL Mode Descriptions

The difference between verify-ca and verify-full depends on the policy of the root CA. If a public CA is used, verify-ca allows connections to a server that somebody else may have registered with the CA. In this case, verify-full should always be used. If a local CA is used, or even a self-signed certificate, using verify-ca often provides enough protection.

#Configuring Custom CA Certificates

When using SSL modes that require certificate validation (require, verify-ca, verify-full), you need to provide the CA certificate that signed the database server certificate. The most common approach is to store the CA certificate in a ConfigMap and mount it to the Tekton Results pods.

#Step 1: Create ConfigMap with CA Certificate

If you have a CA certificate file named root.crt, create a ConfigMap:

kubectl create configmap db-root-crt -n tekton-pipelines --from-file ca.crt=./root.crt

#Step 2: Configure TektonResult with Volume Mounts

To make the CA certificate available in the containers, you need to configure the TektonResult resource with additional options to mount the ConfigMap:

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonResult
metadata:
  name: result
spec:
  is_external_db: true
  # Database connection configuration
  db_host: your-postgres-host.example.com
  db_port: 5432
  db_name: tekton_results
  db_sslmode: verify-full
  db_sslrootcert: /etc/tls/db/ca.crt
  # Secret configuration
  secret_name: tekton-results-postgres
  # Options for mounting CA certificate
  options:
    deployments:
      tekton-results-api:
        spec:
          template:
            spec:
              containers:
                - name: api
                  volumeMounts:
                    - mountPath: /etc/tls/db
                      name: postgredb-tls-ca
                      readOnly: true
              volumes:
                - configMap:
                    name: db-root-crt
                  name: postgredb-tls-ca
      tekton-results-retention-policy-agent:
        spec:
          template:
            spec:
              containers:
                - name: retention-policy-agent
                  volumeMounts:
                    - mountPath: /etc/tls/db
                      name: postgredb-tls-ca
                      readOnly: true
              volumes:
                - configMap:
                    name: db-root-crt
                  name: postgredb-tls-ca

With this configuration:

• The CA certificate will be available in the containers at /etc/tls/db/ca.crt
• Set db_sslrootcert to /etc/tls/db/ca.crt to match the mounted path
• Both the API server and retention policy agent will have access to the CA certificate

#Operations

#Updating Database Configuration

After modifying the database configuration, you need to restart the Tekton Results components for the changes to take effect.

Option 1: Restart specific deployments

# Restart the API server
kubectl delete pod -n tekton-pipelines -l app.kubernetes.io/name=tekton-results-api

# Restart the retention policy agent
kubectl delete pod -n tekton-pipelines -l app.kubernetes.io/name=tekton-results-retention-policy-agent

Option 2: Recreate the TektonResult resource

# Get the current TektonResult resource and recreate it
kubectl get tektonresults.operator.tekton.dev result -o yaml | kubectl replace --force -f -

Verify the changes:

# Check if the pods are running with the new configuration
kubectl get pods -n tekton-pipelines -l app.kubernetes.io/name=tekton-results-api
kubectl get pods -n tekton-pipelines -l app.kubernetes.io/name=tekton-results-retention-policy-agent

kubectl get tektonresults.operator.tekton.dev result -o yaml | kubectl replace --force -f -

#Troubleshooting

#Common Issues

1. Connection refused:

   • Verify database host and port
   • Check network connectivity
   • Ensure database is running

2. Authentication failed:

   • Verify username and password in Secret
   • Check database user permissions

3. SSL certificate errors:

   • Verify CA certificate is correctly mounted
   • Check SSL mode configuration
   • Ensure certificate path matches mount path

#Verification Commands

# Check TektonResult status
kubectl get tektonresults.operator.tekton.dev result -o yaml

# Check pod logs
kubectl logs -n tekton-pipelines -l app.kubernetes.io/name=tekton-results-api

# Verify Secret exists
kubectl get secret tekton-results-postgres -n tekton-pipelines

#Using PostgreSQL from Data Services

Data Services supports deploying PostgreSQL instances that can be used for Tekton Results. When creating a PostgreSQL instance, please consider the following important requirements:

1. Choose a PostgreSQL version that matches your Tekton Results version, for example, you can select PostgreSQL 12.x or higher.
2. Storage quota should not be less than 5Gi

When creating a PostgreSQL instance, a Secret containing connection information is automatically generated. This Secret resource can be filtered using the label middleware.instance/type: PostgreSQL.

kubectl get secret -n <ns-of-postgresql-instance> -l middleware.instance/type=PostgreSQL | grep -E '^postgres'