数据库配置

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

NOTE

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

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

前提条件

集群要求

集群中必须安装 Tekton Operator。

数据库要求

版本：

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

数据库准备：

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

创建数据库命令：

CREATE DATABASE tekton_results;

配置概览

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

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

配置参数参考

字段	描述	默认值	是否必填
`is_external_db`	是否使用外部数据库	`false`	是（外部数据库需设置为 `true`）
`db_host`	数据库主机地址	`localhost`	是
`db_port`	数据库端口	`5432`	是
`db_name`	数据库名称	`tekton_results`	是
`db_sslmode`	SSL 连接模式	`disable`	否
`db_sslrootcert`	SSL 根证书路径	空	否（使用 SSL 时必填）
`db_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
  namespace: tekton-pipelines # 你的 tekton pipelines 命名空间
data:
  POSTGRES_USER: <base64 encoded username>
  POSTGRES_PASSWORD: <base64 encoded password>

2. 配置 TektonConfig 资源

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

TIP

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

3. 验证配置

kubectl get tektonconfig config
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 允许连接到任何由该 CA 注册的服务器，此时应使用 verify-full。若使用本地 CA 或自签名证书，verify-ca 通常已足够。

WARNING

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

配置自定义 CA 证书

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

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

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

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

第二步：在 TektonConfig 中配置 Volume 挂载

为使 CA 证书在容器中可用，需要在 spec.result.options 下配置挂载 ConfigMap：

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  result:
    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 配置
    db_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 组件以使配置生效。

方式一：重启指定 Deployment

# 重启 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

方式二：重新创建 TektonConfig 资源

# 获取当前 TektonConfig 并强制替换
kubectl get tektonconfig config -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 字段，可能需要重新创建 TektonConfig 资源以使变更生效。

kubectl get tektonconfig config -o yaml | kubectl replace --force -f -

故障排查

常见问题

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

验证命令

# 查看 TektonConfig 状态
kubectl get tektonconfig config -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，请在 TektonConfig 的 spec.result 中设置 db_sslmode 为 allow、prefer 等。

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

#数据库配置

#目录

#前提条件

#集群要求

#数据库要求

#配置概览

#配置参数参考

#基础配置

#1. 创建数据库凭据

#2. 配置 TektonConfig 资源

#3. 验证配置

#高级配置

#SSL 配置

#配置自定义 CA 证书

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

#第二步：在 TektonConfig 中配置 Volume 挂载

#操作

#更新数据库配置

#故障排查

#常见问题

#验证命令

#使用 Data Services 中的 PostgreSQL