数据库配置

本文档介绍如何配置 Tekton Results 所需的数据库。

NOTE

目前，我们仅支持连接外部数据库。原因如下：

内置数据库缺少生产环境所需的关键功能，如备份、监控、高可用和高级管理能力，仅提供基础的存储和查询功能，不适合生产环境。
外部数据库提供全面的企业级功能，包括自动备份、性能监控、扩展能力和专业支持，这些都是生产部署所必需的。
我们的 Data Services 产品已提供完善的 PostgreSQL 管理能力。

前提条件

集群要求

集群中必须安装 Tekton Operator。

数据库要求

版本：

PostgreSQL 12 及以上版本
推荐使用较新版本以获得更长的维护支持

数据库设置：

数据库必须已存在
数据库应为空（Tekton Results 会自动创建所需的表结构）
确保数据库用户具有创建表的权限

创建数据库命令：

CREATE DATABASE tekton_results;

配置概述

Tekton Results 支持使用外部 PostgreSQL 数据库。配置分为两部分：

数据库凭据（用户名和密码）存储在 Kubernetes Secret 中
数据库连接参数（主机、端口、数据库名、SSL 设置）配置在 TektonResult 自定义资源中

配置参数参考

字段	说明	默认值	是否必填
`is_external_db`	是否使用外部数据库	`false`	是（外部数据库需设置为 `true`）
`db_host`	数据库主机地址	`localhost`	是
`db_port`	数据库端口	`5432`	是
`db_name`	数据库名称	`tekton-results`	是
`db_sslmode`	SSL 连接模式	`disable`	否
`db_sslrootcert`	SSL 根证书路径	空	否（使用 SSL 时必填）
`secret_name`	存储数据库凭据的 Secret 名称	空	是

db_sslmode 的有效选项说明见 https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-PROTECTION。

基础配置

以下示例展示如何配置一个无 SSL 的基础外部数据库连接：

1. 创建数据库凭据

Secret 中必填字段：

字段	说明	示例值
`POSTGRES_USER`	数据库用户名	`result`
`POSTGRES_PASSWORD`	数据库密码	`your_secure_password`

创建 Secret 命令：

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

Secret YAML 示例：

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

2. 配置 TektonResult 资源

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

TIP

本文档仅列出了数据库相关的配置字段。完整字段列表请参考快速开始。

3. 验证配置

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

TIP

本快速开始仅涵盖基础配置。生产环境中若需使用 SSL、高级安全或自定义 CA 证书，请参见下方的高级配置部分。

高级配置

SSL 配置

当需要安全的数据库连接时，可以配置 SSL 相关参数：

SSL 模式选择指南：

环境	推荐模式	安全级别	说明
开发	`disable`	无	不加密
测试	`require`	基础	加密连接
生产	`verify-full`	最高	加密且验证证书

SSL 模式说明

sslmode	防止窃听	防止中间人攻击	说明
disable	否	否	不关心安全性，不想承担加密开销。
allow	可能	否	不关心安全性，但如果服务器要求加密则接受加密。
prefer	可能	否	不关心加密，但如果服务器支持加密则使用加密。
require	是	否	希望数据加密，接受加密开销，相信网络能确保连接到正确服务器。
verify-ca	是	取决于 CA 策略	希望数据加密，接受加密开销，确保连接到受信任的服务器。
verify-full	是	是	希望数据加密，接受加密开销，确保连接到指定且受信任的服务器。

verify-ca 和 verify-full 的区别取决于根 CA 的策略。若使用公共 CA，verify-ca 允许连接到可能被他人注册的服务器，建议使用 verify-full。若使用本地 CA 或自签证书，verify-ca 通常已足够。

WARNING

重要提示： 使用 require、verify-ca 或 verify-full 模式时，必须提供签发数据库服务器证书的 CA 证书。否则 Tekton Results 组件将无法启动。详细配置步骤请参见配置自定义 CA 证书。

配置自定义 CA 证书

使用需要证书验证的 SSL 模式时（require、verify-ca、verify-full），需提供签发数据库服务器证书的 CA 证书。通常做法是将 CA 证书存储在 ConfigMap 中，并挂载到 Tekton Results Pod。

第 1 步：创建包含 CA 证书的 ConfigMap

假设 CA 证书文件名为 root.crt，执行：

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

第 2 步：配置 TektonResult 资源挂载卷

为使容器能访问 CA 证书，需要在 TektonResult 资源中通过 options 配置挂载 ConfigMap：

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: verify-full
  db_sslrootcert: /etc/tls/db/ca.crt
  # Secret 配置
  secret_name: tekton-results-postgres
  # 挂载 CA 证书的选项
  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

配置说明：

CA 证书将挂载到容器的 /etc/tls/db/ca.crt
db_sslrootcert 设置为 /etc/tls/db/ca.crt，与挂载路径对应
API 服务和保留策略智能体均可访问该证书

操作

更新数据库配置

修改数据库配置后，需要重启 Tekton Results 组件使配置生效。

方案一：重启指定部署

# 重启 API 服务
kubectl delete pod -n tekton-pipelines -l app.kubernetes.io/name=tekton-results-api

# 重启保留策略智能体
kubectl delete pod -n tekton-pipelines -l app.kubernetes.io/name=tekton-results-retention-policy-agent

方案二：重新创建 TektonResult 资源

# 获取当前 TektonResult 资源并强制替换
kubectl get tektonresults.operator.tekton.dev result -o yaml | kubectl replace --force -f -

验证变更：

# 查看 Pod 是否已使用新配置启动
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

WARNING

如果更新了 db_sslmode 字段，可能需要重新创建 TektonResult 资源以使变更生效。

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

故障排查

常见问题

连接被拒绝：
- 检查数据库主机和端口是否正确
- 检查网络连通性
- 确认数据库服务是否运行
认证失败：
- 核实 Secret 中的用户名和密码
- 检查数据库用户权限
SSL 证书错误：
- 确认 CA 证书是否正确挂载
- 检查 SSL 模式配置
- 确保证书路径与挂载路径一致

验证命令

# 查看 TektonResult 状态
kubectl get tektonresults.operator.tekton.dev result -o yaml

# 查看 Pod 日志
kubectl logs -n tekton-pipelines -l app.kubernetes.io/name=tekton-results-api

# 验证 Secret 是否存在
kubectl get secret tekton-results-postgres -n tekton-pipelines

使用 Data Services 提供的 PostgreSQL

Data Services 支持部署可用于 Tekton Results 的 PostgreSQL 实例。创建 PostgreSQL 实例时，请注意以下重要要求：

选择与 Tekton Results 版本匹配的 PostgreSQL 版本，例如 PostgreSQL 12.x 或更高。
存储配额不得少于 5Gi。

创建 PostgreSQL 实例时，会自动生成包含连接信息的 Secret。该 Secret 资源可通过标签 middleware.instance/type: PostgreSQL 进行筛选。

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

INFO

该 Secret 包含 host、port、username、password 信息。您需要基于该 Secret 补充 database 信息，并在 Tekton Results 实例所在命名空间创建新的 Secret。

若需设置 sslmode，请在 TektonResult 中将 db_sslmode 设置为 allow 或 prefer 等。

更多 PostgreSQL 部署参数和要求，请参见 PostgreSQL Deployment Documentation。

#数据库配置

#目录

#前提条件

#集群要求

#数据库要求

#配置概述

#配置参数参考

#基础配置

#1. 创建数据库凭据

#2. 配置 TektonResult 资源

#3. 验证配置

#高级配置

#SSL 配置

#配置自定义 CA 证书

#第 1 步：创建包含 CA 证书的 ConfigMap

#第 2 步：配置 TektonResult 资源挂载卷

#操作

#更新数据库配置

#故障排查

#常见问题

#验证命令

#使用 Data Services 提供的 PostgreSQL