数据库配置

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

NOTE

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

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

前提条件

集群要求

  • 集群中必须安装 Tekton Operator。

数据库要求

版本:

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

数据库设置:

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

创建数据库命令:

CREATE DATABASE tekton_results;

配置概述

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

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

配置参数参考

字段说明默认值是否必填
is_external_db是否使用外部数据库false是(使用外部数据库时设置为 true)
db_host数据库主机地址localhost是
db_port数据库端口5432是
db_name数据库名称tekton_results是
db_sslmodeSSL 连接模式disable否
db_sslrootcertSSL 根证书路径空否(使用 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
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 允许连接到可能由他人注册的服务器,建议使用 verify-full。如果使用本地 CA 或自签名证书,verify-ca 通常已足够。

WARNING

重要提示: 使用 require、verify-ca 或 verify-full SSL 模式时,必须提供签署数据库服务器证书的 CA 证书。若未正确配置 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 步:在 TektonConfig 中配置 Volume 挂载

为了让容器访问 CA 证书,需要在 TektonConfig 的 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 服务器和保留策略智能体均可访问该 CA 证书

操作

更新数据库配置

修改数据库配置后,需要重启 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

方案二:重新创建 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 -

故障排查

常见问题

  1. 连接被拒绝:

    • 检查数据库主机和端口是否正确
    • 检查网络连通性
    • 确认数据库是否正在运行
  2. 认证失败:

    • 核实 Secret 中的用户名和密码
    • 检查数据库用户权限
  3. 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 实例时,请注意以下重要要求:

  1. 选择与 Tekton Results 版本匹配的 PostgreSQL 版本,例如 PostgreSQL 12.x 或更高。
  2. 存储配额不得少于 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。