Tekton Results

Tekton Results 是一个复杂的系统,通过提供 CI/CD 执行数据的持久化存储、查询和管理来扩展 Tekton 的能力。本文将深入探讨 Tekton Results 的工作原理及其架构,并介绍如何有效利用其功能。

术语表

术语定义
Result一种顶层资源,用于将相关 Record 归组在一起,表示一个逻辑工作单元
Record属于某个 Result 的单个数据实例(TaskRun、PipelineRun、Log)
Watcher一种 Kubernetes 控制器,用于监控 TaskRun 和 PipelineRun,并将其存储在 Results 数据库中
API Server提供对已存储 Result 和 Record 访问的 gRPC/REST 服务器
Retention Policy用于确定数据在 Results 数据库中保留时长的规则

为什么需要 Tekton Results

CI/CD 数据管理面临的挑战

在传统的基于 Kubernetes 的 CI/CD 系统(例如 Tekton Pipelines)中,所有执行数据都存储在 Kubernetes API server 的 etcd 数据库中。这种方式存在以下限制:

  • 存储容量有限:etcd 旨在存储少量配置数据,而不是大量的执行历史记录和日志
  • 资源约束:随着 CI/CD 工作负载不断累积,它们可能会消耗大量 etcd 资源,从而影响集群性能
  • 数据碎片化:相关的 CI/CD 活动(TaskRun、PipelineRun)作为独立资源存储,彼此之间没有明确的关联关系
  • 日志管理:日志通常存储在容器运行时或外部日志系统中,因此很难将其与特定的流水线执行关联起来
  • 数据生命周期:没有内置机制来管理已完成 CI/CD 数据的生命周期

随着 CI/CD 使用规模不断扩大,这些限制会变得日益严重,从而可能导致性能问题和管理开销。

Tekton Results 如何应对这些挑战

Tekton Results 通过以下方式提供全面的解决方案:

  1. 卸载数据存储:将已完成的 CI/CD 执行数据从 etcd 移至专为此目的优化的独立数据库
  2. 建立关联关系:通过 Result/Record 数据模型,为相关的 CI/CD 活动创建明确的关联关系
  3. 集中存储日志:将日志与其关联的 TaskRun/PipelineRun 一起存储
  4. 提供数据生命周期管理:实施保留策略,自动管理数据的生命周期
  5. 支持高级查询:提供超越 Kubernetes API 能力的强大过滤和查询功能

优势

  • 提升集群性能:通过卸载已完成的 CI/CD 数据,降低 Kubernetes API server 和 etcd 的负载
  • 增强数据组织:将相关的 CI/CD 活动归组,以便更好地查看和管理
  • 延长数据保留时间:支持长期存储执行历史记录,同时不影响集群资源
  • 强大的查询功能:为 CI/CD 数据提供高级筛选和搜索功能
  • 集成日志管理:将日志与执行数据一同存储,形成完整的流水线历史记录
  • 自动清理:通过可配置的保留策略管理数据生命周期

适用场景

Tekton Results 在以下场景中特别有价值:

  1. 高吞吐量 CI/CD 环境:运行大量流水线并生成大量执行数据的组织
  2. 合规性要求:需要出于审计或合规目的保留执行历史记录的环境
  3. 资源受限的集群:etcd 资源有限且需要进行优化的集群
  4. 高级分析:希望对 CI/CD 执行模式进行分析和报告的团队
  5. 多团队环境:多个团队共享 Tekton 基础设施,并且需要隔离查看各自 CI/CD 数据的组织

架构和原理

Tekton Results 采用微服务架构,包含三个相互协作的主要组件,可提供完整的解决方案:

API Server 架构

API Server 是中心组件,负责:

  1. 提供数据访问:公开用于存储和检索 Result 与 Record 的 gRPC 和 REST 端点
  2. 管理身份验证:使用 Kubernetes 风格的身份验证机制(服务帐户、令牌)
  3. 实施授权:为 Results 资源实现基于 RBAC 的访问控制
  4. 处理数据持久化:与底层数据库(PostgreSQL)交互
  5. 支持筛选:实现 CEL(通用表达式语言),以支持强大的查询筛选功能

API Server 使用父子层级结构,其中:

  • 命名空间/工作区是 Result 的父级
  • Result 是 Record 的父级
  • Record 包含实际的执行数据

Watcher 架构

Watcher 作为 Kubernetes 控制器运行,负责:

  1. 监控资源:监听集群中的 TaskRun 和 PipelineRun 事件
  2. 确定分组:使用注解、标签和所有者引用对相关资源进行分组
  3. 创建/更新 Record:通过 API Server 将执行数据存储在 Results 数据库中
  4. 为资源添加注解:将 Result 标识符添加到原始 Kubernetes 资源
  5. 管理删除:将已完成的资源存储到数据库后,根据需要删除这些资源

Watcher 使用多种策略对相关资源进行分组:

  • results.tekton.dev/result 注解
  • triggers.tekton.dev/triggers-eventid 标签
  • 指向 PipelineRun 的所有者引用
  • 找不到分组信息时自动生成新的 Result 名称

Retention Policy Agent 架构

Retention Policy Agent 负责:

  1. 安排清理任务:根据配置的计划运行清理任务
  2. 实施保留策略:删除超过配置保留期限的数据
  3. 管理数据库大小:防止 Results 数据库无限增长

深入了解数据模型

Result 结构

一个 Result 包含:

Result
├── metadata
│   ├── name
│   ├── uid
│   ├── createTime
│   ├── updateTime
│   └── annotations (key-value pairs)
└── summary
    ├── type (e.g., PIPELINE_RUN, TASK_RUN)
    ├── status (SUCCESS, FAILURE, TIMEOUT, CANCELLED, UNKNOWN)
    ├── startTime
    ├── endTime
    └── annotations (key-value pairs)

Record 结构

一个 Record 包含:

Record
├── name
├── data
│   ├── type (e.g., tekton.dev/v1.TaskRun, tekton.dev/v1.PipelineRun, results.tekton.dev/v1alpha3.Log)
│   └── value (serialized data)
└── createTime

身份验证和授权

Tekton Results 使用 Kubernetes 风格的身份验证和 RBAC 进行访问控制:

  1. 身份验证:使用 service account token、用户模拟以及其他 Kubernetes 身份验证方法
  2. 授权:使用资源(results、records)和操作(get、list、create、update、delete)实现 RBAC
  3. 命名空间隔离:在多租户环境中按命名空间限定权限范围

RBAC 角色示例:

  • tekton-results-readonly:对 Results 和 Records 的只读访问权限
  • tekton-results-readwrite:对 Results 和 Records 的读写访问权限
  • tekton-results-admin:包括删除 Results 和 Records 在内的完全访问权限

高级过滤

Tekton Results 使用 CEL(Common Expression Language)提供强大的过滤功能:

# Filter by Result status
results.tekton.dev/v1alpha2/parents/default/results?filter=summary.status==SUCCESS

# Filter by creation time
results.tekton.dev/v1alpha2/parents/default/results?filter=create_time>timestamp('2023-01-01T00:00:00Z')

# Filter Records by data type
results.tekton.dev/v1alpha2/parents/default/results/123/records?filter=data_type=='tekton.dev/v1.TaskRun'

# Complex filtering with logical operators
results.tekton.dev/v1alpha2/parents/default/results?filter=summary.status==SUCCESS&&create_time>timestamp('2023-01-01T00:00:00Z')

重要参数

Watcher 参数

参数描述默认值用法
completed_run_grace_period完成后等待多长时间再删除资源0(不删除)设置为时长(例如 24h)以启用自动删除
check_owner删除前是否检查所有者引用true保持为 true,以防止删除具有所有者引用的资源
store_deadline等待存储资源的最长时间10m对于大型资源或速度较慢的数据库连接,可以增大此值

API Server 参数

参数描述默认值用法
AUTH_IMPERSONATE启用用户模拟true保持为 true,以允许 service account 模拟用户
page_size列表请求单页中的最大 Result 数量。这是请求的查询参数,而不是服务器设置50对每个请求单独设置,范围为 5 至 10000

Retention Policy 参数

参数描述默认值用法
runAt运行保留策略任务的时间5 5 * * 0(每周日 05:05 )用于安排清理任务的 Cron 表达式
maxRetention(已弃用)默认保留期限的旧名称;存在时会覆盖 defaultRetention未设置(已弃用)删除前保留数据的时长。如果存在,则会替代 defaultRetention 使用;请将其值移至 defaultRetention 并删除该参数
defaultRetention没有策略匹配时使用的默认保留期限"30"(30 天,等同于 720h)删除前保留数据的时长。纯整数表示天数;也接受 30d 和 720h

参考资料