快速开始

安装 Tekton Results

本文档介绍如何使用现有数据库安装 Tekton Results。

NOTE

目前不支持内置 PostgreSQL 数据库,请使用外部数据库。

有关外部数据库的信息,请参阅使用 Data Services 中的 PostgreSQL

TIP

Tekton Results 支持将日志存储在各种存储后端中。对于可扩展且持久的日志保留,目前建议使用 S3 兼容的对象存储(例如 AWS S3、Ceph、MinIO)。有关详细的 S3 存储配置,请参阅S3 存储配置指南。不建议在生产环境中使用本地 PVC 存储。

前提条件

  1. 必须在集群中安装 Tekton Pipelines。

    TIP

    以下说明假设你已将 Results 安装到默认的 tekton-pipelines 命名空间中。

    如果你将其安装到了其他命名空间,请将 tekton-pipelines 替换为你的命名空间。

  2. 存储数据库账户。

    Tekton Results 使用存储在 Kubernetes Secret 中的用户名和密码连接 PostgreSQL。在安装之前创建 Secret,其中包含 Tekton Results 用于连接数据库的用户,例如专用的 result 用户。默认情况下,Tekton Results 要求此 Secret 具有以下属性:

    • 命名空间:tekton-pipelines
    • 名称:tekton-results-postgres
    • 包含以下字段:
      • POSTGRES_USER=<your_username>
      • POSTGRES_PASSWORD=<your_password>

    你可以使用以下命令快速生成 Secret。单独运行 read -rs 行,输入数据库密码并按 Enter:read -rs 不会显示密码,因此密码不会出现在屏幕上或 shell 历史记录中。在不支持括号粘贴的 shell 中(例如 5.1 之前的 bash),read 会将粘贴块中的下一行作为密码。在 bash 或 zsh 中运行这些命令:在 POSIX sh 中,例如 dash,read -rs 会失败并使变量保持为空:

    read -rs DB_PASSWORD

    然后创建 Secret。创建 Secret 后,unset 会从 shell 中移除密码:

    kubectl create secret generic tekton-results-postgres --namespace="tekton-pipelines" --from-literal=POSTGRES_USER=<your_username> --from-literal=POSTGRES_PASSWORD="$DB_PASSWORD"
    unset DB_PASSWORD
  3. 生成证书/密钥对。注意:可以使用任何证书管理软件完成此操作!

    Tekton Results 要求将证书/密钥对存储在名为 tekton-results-tls 的 TLS Kubernetes Secret 中。

    • 生成新的自签名证书

      openssl req -x509 \
        -newkey rsa:4096 \
        -keyout key.pem \
        -out cert.pem \
        -days 365 \
        -nodes \
        -subj "/CN=tekton-results-api-service.tekton-pipelines.svc.cluster.local" \
        -addext "subjectAltName = DNS:tekton-results-api-service.tekton-pipelines.svc.cluster.local"
      TIP

      如果你的 openssl 版本过低,不支持某些参数,请从 openssl 二进制文件 升级你的 openssl 版本。

    • 从证书创建新的 TLS Secret。

      kubectl create secret tls -n tekton-pipelines tekton-results-tls \
        --cert=cert.pem \
        --key=key.pem
  4. (仅用于快速开始)如果使用旧版 File 存储类型,请创建一个 PVC(不建议在生产环境中使用)。

    WARNING

    不建议在生产环境中使用基于 PVC 的本地存储。对于可扩展且持久的日志保留,建议使用 S3 兼容的对象存储。有关 S3 存储配置,请参阅S3 存储配置指南。

    如果仍需使用 PVC 进行测试:

    cat <<EOF | kubectl create -f -
    apiVersion: v1
    kind: PersistentVolumeClaim
    metadata:
      name: tekton-logs
      namespace: tekton-pipelines
    spec:
      accessModes:
        - ReadWriteOnce  # The access mode indicating it can be read and written by a single node
      resources:
        requests:
          storage: 100Gi  # The requested storage size
    EOF
    • 请根据需要调整 PVC 大小。
    • 示例未设置 storageClassName,因此 PVC 使用集群的默认 StorageClass,该 StorageClass 由 kubectl get storageclass 标记为 (default)。如果集群没有默认 StorageClass,请将 storageClassName: <storage-class> 添加到 spec;没有 StorageClass 时,PVC 可能保持为 Pending。
    • 注意:仅当使用旧版 File 存储类型时才需要此项。

使用 operator CRD 安装

operator 已创建名为 config 的 TektonConfig。将以下 spec.result 字段合并到其中;disabled: false 会安装 Tekton Results。合并操作会保留其他 TektonConfig 字段,包括 spec.targetNamespace,即部署 Tekton Results 的命名空间。

cat <<EOF > tekton-results-patch.yaml
spec:
  result:
    # Install Tekton Results
    disabled: false
    # Update with database address
    db_host: <database_host>
    db_port: 5432
    db_name: <database_name>
    # Use external database
    is_external_db: true
    # secret containing database account information created earlier
    db_secret_name: tekton-results-postgres
    # Basic settings
    server_port: 8080
    # Disable authentication (for testing only, see auth_disable below)
    auth_disable: true
    db_enable_auto_migration: true
    log_level: debug
    # Use logs storage service
    logs_api: true
    logs_type: File
    logging_pvc_name: tekton-logs
    # logs_type: S3  # Recommended: S3-compatible storage for scalable log retention
    # secret_name: tekton-results-s3-credentials  # Secret containing S3 credentials
    logs_path: /logs
    logs_buffer_size: 92160
    # S3 storage does not require PVC, unlike legacy File storage
EOF
kubectl patch tektonconfig config --type merge --patch-file tekton-results-patch.yaml
DETAILS

以下 Tekton Results 配置字段嵌套在 TektonConfig 资源的 spec.result 下,但 targetNamespace 除外,它是 spec.targetNamespace。

  • disabled:是否禁用 Tekton Results。
    • false:安装 Tekton Results。
  • db_host:数据库的主机。
  • db_port:数据库的端口。
  • db_name:数据库的名称。
  • is_external_db:必须为 true,因为不支持内置 PostgreSQL 数据库。
    • true:使用外部数据库。
  • db_secret_name:包含数据库账户信息的 Secret 名称。
    • 这是上一步创建的 Secret。
  • server_port:服务器的端口。
  • targetNamespace(spec.targetNamespace,不会由补丁更改):部署 Results 的命名空间。
  • auth_disable:是否禁用身份验证。
    • true:仅用于测试。Results API 会跳过 Kubernetes RBAC 检查并允许所有请求,因此任何能够访问该 API 的人都可以读取、更改和删除所有命名空间中的结果、记录和日志。这包括通过 Tekton Results 安装所创建的 Ingress tektoncd-results-api 进行访问,该 Ingress 在路径 /results 下提供 API。请按照重新启用身份验证中的说明,在测试后重新启用身份验证。
  • db_enable_auto_migration:是否启用自动数据库迁移。
  • log_level:日志级别。
  • logs_api:是否启用日志 API。
    • true:启用日志 API。
  • logs_type:日志的类型。
    • File:将日志存储在文件中(不建议在生产环境中使用)。
    • S3:将日志存储在 S3 兼容的对象存储中(例如 AWS S3、Ceph、MinIO)。这是实现可扩展且持久日志保留的推荐方式。有关详细配置,请参阅S3 存储配置指南。
  • secret_name:包含 S3 账户信息的 Secret 名称。有关详细配置,请参阅S3 存储配置指南。
  • logs_path:日志的路径。
  • logs_buffer_size:日志的缓冲区大小。
  • logging_pvc_name:用于存储日志的 PVC 名称(仅在使用旧版 File 存储类型时需要)。
    • 这是上一步创建的 PVC(S3 存储不需要)。
TIP

有关更多数据库配置,请参阅PostgreSQL 配置

部署后,可以看到 results-api / results-retention-policy-agent / results-watcher 的状态为 Running。该命名空间还包含其他 Tekton 组件的 Pod;以下输出已缩减为 Tekton Results Pod:

$ kubectl get pods -n tekton-pipelines

NAME                                                    READY   STATUS    RESTARTS   AGE
tekton-results-api-68bb657996-bb487                     1/1     Running   0          14s
tekton-results-retention-policy-agent-c6ff5575b-prczg   1/1     Running   0          14s
tekton-results-watcher-6d7c68f576-p2gbl                 1/1     Running   0          14s

验证功能

可以通过一个简单的 taskrun 验证功能。

1. 创建 TaskRun 资源

cat <<'EOF' | kubectl create -n default -f -
apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: hello
spec:
  taskSpec:
    steps:
      - name: hello
        image: alpine
        command:
          - "echo"
          - "hello"
EOF
NOTE

请将公开的 alpine 镜像替换为集群可以拉取的镜像,例如在隔离网络环境中使用内部 registry 中的镜像。

当集群设置 disable-inline-spec 包含 taskrun 时(请参阅使用 Kyverno 限制 Tekton Pipeline 执行),Tekton webhook 会拒绝带有内联 taskSpec 的 TaskRun;在此类集群中,请创建具有相同步骤的 Task,并改为使用 taskRef 引用它。

2. 等待任务执行完成

$ kubectl get taskruns.tekton.dev -n default -w

NAME                                         SUCCEEDED   REASON      STARTTIME   COMPLETIONTIME
hello                                        Unknown     Pending     3s
hello                                        True        Succeeded   11s         0s

3. 使用 tkn-results CLI 查询结果

准备 CLI

tkn 是用于与 Tekton 交互的命令行工具。你可以从官方页面下载它。

你需要使用 golang 构建 tkn-results。至少使用所检出分支的 go.mod 中 go 行指定的 Go 版本:Results v0.19.0 使用 go 1.25.8,因此需要 Go 1.25.8 或更高版本。

不要始终从 main 构建。请使用与你环境中部署的 Tekton Results 版本匹配的 release 分支。 你可以在 Release Notes 中找到 Results 组件版本(Results 列),然后检出相应的分支 release-v<version>.x。

# 1. Clone the repository
git clone https://github.com/tektoncd/results.git

# 2. Change to the project directory
cd results

# 3. Checkout the matching release branch (example: Results 0.15.x -> release-v0.15.x)
git checkout release-v<version>.x

# 4. Build the binary
go build -o tkn-results ./cmd/tkn-results/main.go

# 5. Copy the binary to a directory in your PATH
连接行为

未设置 --addr 时,tkn-results 会尝试自动将端口转发到 Results API 服务。

在许多版本中(包括 release-v0.15.x),自动目标为 tekton-pipelines/tekton-results-api-service。 如果你的 Results 部署使用不同的命名空间或服务名称,自动模式可能会失败。

设置 --addr 后,tkn-results 会直接连接到该地址。 在这种情况下,通常需要自行运行 kubectl port-forward。

查询执行记录列表
$ tkn results --insecure records list default/results/-

default/results/209dcb81-e3c0-47cd-b082-d910e15702ae/records/209dcb81-e3c0-47cd-b082-d910e15702ae  tekton.dev/v1.TaskRun                   2025-02-19 16:17:11 +0800 CST           2025-02-19 16:17:21 +0800 CST
default/results/209dcb81-e3c0-47cd-b082-d910e15702ae/records/a750035d-0479-34a1-9db2-9a256b53243f  results.tekton.dev/v1alpha3.Log         2025-02-19 16:17:21 +0800 CST           2025-02-19 16:17:21 +0800 CST
自动端口转发失败时的备用方法

在单独的终端中启动端口转发,并在运行 tkn results 命令时保持其运行;该命令会在前台运行,直到使用 Ctrl+C 停止:

kubectl port-forward -n <results-namespace> service/tekton-results-api-service 8080

然后,在第一个终端中运行:

tkn results --insecure --addr localhost:8080 records list default/results/-
tkn results --insecure --addr localhost:8080 records get -o textproto default/results/<result-uid>/records/<record-uid>
tkn results --insecure --addr localhost:8080 logs list default/results/-
# With logs_type File or S3, as set on this page, the Results API serves only the
# v1alpha2 Logs API, so logs get needs --v1alpha2; without it, the command fails with
# "unknown service tekton.results.v1alpha3.Logs". The flag works even where the CLI
# marks it as deprecated:
tkn results --insecure --addr localhost:8080 --v1alpha2 logs get -o textproto default/results/<result-uid>/logs/<log-uid>
查询单条执行记录
$ tkn results --insecure records get -o textproto default/results/209dcb81-e3c0-47cd-b082-d910e15702ae/records/209dcb81-e3c0-47cd-b082-d910e15702ae

name: "default/results/209dcb81-e3c0-47cd-b082-d910e15702ae/records/209dcb81-e3c0-47cd-b082-d910e15702ae"
id: "0805bbd0-e390-40dc-a1ea-f65ae9401930"
uid: "0805bbd0-e390-40dc-a1ea-f65ae9401930"
data: {
  type: "tekton.dev/v1.TaskRun"
  value: "{\"kind\": \"TaskRun\", \"spec\": {\"timeout\": \"1h0m0s\", \"taskSpec\": {\"steps\": [{\"name\": \"hello\", \"image\": \"alpine\", \"command\": [\"echo\", \"hello\"], \"computeResources\": {}}]}, \"serviceAccountName\": \"default\"}, \"status\": {\"steps\": [{\"name\": \"hello\", \"imageID\": \"alpine\", \"container\": \"step-hello\", \"terminated\": {\"reason\": \"Completed\", \"exitCode\": 0, \"startedAt\": \"2025-02-19T08:17:20Z\", \"finishedAt\": \"2025-02-19T08:17:20Z\", \"containerID\": \"containerd://5e2cb72ca758fc976744b06b5ee97564bcc0958ca9cee2a54fdaab64323a1bf9\"}, \"terminationReason\": \"Completed\"}], \"podName\": \"hello-pod\", \"taskSpec\": {\"steps\": [{\"name\": \"hello\", \"image\": \"alpine\", \"command\": [\"echo\", \"hello\"], \"computeResources\": {}}]}, \"startTime\": \"2025-02-19T08:17:10Z\", \"conditions\": [{\"type\": \"Succeeded\", \"reason\": \"Succeeded\", \"status\": \"True\", \"message\": \"All Steps have completed executing\", \"lastTransitionTime\": \"2025-02-19T08:17:21Z\"}], \"provenance\": {\"featureFlags\": {\"Coschedule\": \"workspaces\", \"MaxResultSize\": 4096, \"EnableAPIFields\": \"beta\", \"EnableArtifacts\": false, \"EnableParamEnum\": false, \"DisableCredsInit\": false, \"EnableStepActions\": true, \"SetSecurityContext\": false, \"AwaitSidecarReadiness\": true, \"EnableKeepPodOnCancel\": false, \"EnableTektonOCIBundles\": false, \"ResultExtractionMethod\": \"termination-message\", \"SendCloudEventsForRuns\": false, \"DisableAffinityAssistant\": false, \"EnableProvenanceInStatus\": true, \"EnforceNonfalsifiability\": \"none\", \"EnableCELInWhenExpression\": false, \"VerificationNoMatchPolicy\": \"ignore\", \"ScopeWhenExpressionsToTask\": false, \"RequireGitSSHSecretKnownHosts\": false, \"RunningInEnvWithInjectedSidecars\": true}}, \"completionTime\": \"2025-02-19T08:17:21Z\"}, \"metadata\": {\"uid\": \"209dcb81-e3c0-47cd-b082-d910e15702ae\", \"name\": \"hello\", \"labels\": {\"app.kubernetes.io/managed-by\": \"tekton-pipelines\"}, \"namespace\": \"default\", \"finalizers\": [\"results.tekton.dev/taskrun\", \"chains.tekton.dev\"], \"generation\": 1, \"annotations\": {\"results.tekton.dev/log\": \"default/results/209dcb81-e3c0-47cd-b082-d910e15702ae/logs/a750035d-0479-34a1-9db2-9a256b53243f\", \"chains.tekton.dev/signed\": \"true\", \"results.tekton.dev/record\": \"default/results/209dcb81-e3c0-47cd-b082-d910e15702ae/records/209dcb81-e3c0-47cd-b082-d910e15702ae\", \"results.tekton.dev/result\": \"default/results/209dcb81-e3c0-47cd-b082-d910e15702ae\", \"pipeline.tekton.dev/release\": \"8bfd3273cbe7776847884d7fa5004481e6be8f4a\"}, \"managedFields\": [{\"time\": \"2025-02-19T08:17:10Z\", \"manager\": \"kubectl-create\", \"fieldsV1\": {\"f:spec\": {\".\": {}, \"f:taskSpec\": {\".\": {}, \"f:steps\": {}}}}, \"operation\": \"Update\", \"apiVersion\": \"tekton.dev/v1\", \"fieldsType\": \"FieldsV1\"}, {\"time\": \"2025-02-19T08:17:21Z\", \"manager\": \"controller\", \"fieldsV1\": {\"f:metadata\": {\"f:finalizers\": {\"v:\\\"chains.tekton.dev\\\"\": {}}, \"f:annotations\": {\"f:chains.tekton.dev/signed\": {}, \"f:pipeline.tekton.dev/release\": {}}}}, \"operation\": \"Update\", \"apiVersion\": \"tekton.dev/v1\", \"fieldsType\": \"FieldsV1\"}, {\"time\": \"2025-02-19T08:17:21Z\", \"manager\": \"controller\", \"fieldsV1\": {\"f:status\": {\".\": {}, \"f:steps\": {}, \"f:podName\": {}, \"f:taskSpec\": {\".\": {}, \"f:steps\": {}}, \"f:artifacts\": {}, \"f:startTime\": {}, \"f:conditions\": {}, \"f:provenance\": {\".\": {}, \"f:featureFlags\": {\".\": {}, \"f:Coschedule\": {}, \"f:MaxResultSize\": {}, \"f:EnableAPIFields\": {}, \"f:EnableArtifacts\": {}, \"f:EnableParamEnum\": {}, \"f:DisableCredsInit\": {}, \"f:DisableInlineSpec\": {}, \"f:EnableStepActions\": {}, \"f:SetSecurityContext\": {}, \"f:AwaitSidecarReadiness\": {}, \"f:EnableKeepPodOnCancel\": {}, \"f:ResultExtractionMethod\": {}, \"f:SendCloudEventsForRuns\": {}, \"f:EnableKubernetesSidecar\": {}, \"f:DisableAffinityAssistant\": {}, \"f:EnableProvenanceInStatus\": {}, \"f:EnforceNonfalsifiability\": {}, \"f:EnableCELInWhenExpression\": {}, \"f:VerificationNoMatchPolicy\": {}, \"f:EnableConciseResolverSyntax\": {}, \"f:RequireGitSSHSecretKnownHosts\": {}, \"f:RunningInEnvWithInjectedSidecars\": {}}}, \"f:completionTime\": {}}}, \"operation\": \"Update\", \"apiVersion\": \"tekton.dev/v1\", \"fieldsType\": \"FieldsV1\", \"subresource\": \"status\"}, {\"time\": \"2025-02-19T08:17:21Z\", \"manager\": \"watcher\", \"fieldsV1\": {\"f:metadata\": {\"f:finalizers\": {\".\": {}, \"v:\\\"results.tekton.dev/taskrun\\\"\": {}}, \"f:annotations\": {\".\": {}, \"f:results.tekton.dev/log\": {}, \"f:results.tekton.dev/record\": {}, \"f:results.tekton.dev/result\": {}}}}, \"operation\": \"Update\", \"apiVersion\": \"tekton.dev/v1\", \"fieldsType\": \"FieldsV1\"}], \"resourceVersion\": \"1592422\", \"creationTimestamp\": \"2025-02-19T08:17:10Z\"}, \"apiVersion\": \"tekton.dev/v1\"}"
}
etag: "0805bbd0-e390-40dc-a1ea-f65ae9401930-1739953041309658421"
created_time: {
  seconds: 1739953031
  nanos: 16922000
}
create_time: {
  seconds: 1739953031
  nanos: 16922000
}
updated_time: {
  seconds: 1739953041
  nanos: 309658000
}
update_time: {
  seconds: 1739953041
  nanos: 309658000
}

示例输出来自较早版本。在其 metadata.finalizers 中,chains.tekton.dev 是 TaskRun 的 Chains finalizer 旧名称;Chains 现在将其命名为 chains.tekton.dev/taskrun。

查询日志列表
$ tkn results --insecure logs list default/results/-

default/results/209dcb81-e3c0-47cd-b082-d910e15702ae/logs/a750035d-0479-34a1-9db2-9a256b53243f  results.tekton.dev/v1alpha3.Log         2025-02-19 16:17:21 +0800 CST           2025-02-19 16:17:21 +0800 CST
查询单条日志

对于 logs_type File 或 S3(本页面设置的类型),Results API 仅提供 v1alpha2 Logs API。 因此,logs get 需要使用 --v1alpha2 标志;没有该标志时,命令会失败并显示 unknown service tekton.results.v1alpha3.Logs。 logs get 使用该标志调用 v1alpha2 Logs API,即使 CLI 将该标志标记为已弃用。

$ tkn results --insecure --v1alpha2 logs get -o textproto default/results/209dcb81-e3c0-47cd-b082-d910e15702ae/logs/a750035d-0479-34a1-9db2-9a256b53243f

content_type: "text/plain"
data: "[prepare] 2025/02/19 08:17:12 Entrypoint initialization\n\n[hello] hello\n\n"

4. 重新启用身份验证

安装补丁设置了 auth_disable: true,该设置仅用于测试。测试完成后,将以下合并补丁保存为 results-auth-patch.yaml:

spec:
  result:
    auth_disable: false

合并该补丁,然后重复运行第二条命令,直到其输出 AUTH_DISABLE=false。如果它持续输出 AUTH_DISABLE=true,请使用第三条命令读取 TektonConfig 条件。Operator 会先应用 Pipelines、基于事件的 Pruner、Triggers 和 Chains 组件,然后应用 Tekton Results,并在遇到无法应用的组件时停止;此时,ComponentsReady 条件为 False,其消息以 Components not in ready state: 开头,并包含该组件的名称:

kubectl patch tektonconfig config --type merge --patch-file results-auth-patch.yaml
kubectl get configmap tekton-results-api-config -n tekton-pipelines -o jsonpath='{.data.config}' | grep AUTH_DISABLE
kubectl get tektonconfig config -o jsonpath='{range .status.conditions[*]}{.type} {.status} {.message}{"\n"}{end}'

Results API 仅在启动时读取此设置。删除其 Pod,使 Deployment 使用该设置启动新的 Pod,然后检查新 Pod 是否为 Running:

kubectl delete 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-api

参考