README
¶
Tekton Results
Tekton Results aims to help users logically group CI/CD workload history and separate out long term result storage away from the Pipeline controller. This allows you to:
- Provide custom Result metadata about your CI/CD workflows not available in the Tekton TaskRun/PipelineRun CRDs (for example: post-run actions)
- Group related workloads together (e.g. bundle related TaskRuns and PipelineRuns into a single unit)
- Make long-term result history independent of the Pipeline CRD controller, letting you free up etcd resources for Run execution.
- Store logs produced by the TaskRuns/PipelineRuns so that completed Runs can be cleaned to save resources.
Additional background and design motivations can be found in TEP-0021.
Overview
Tekton Results is composed of 3 main components:
- A queryable gRPC API server backed by persistent storage (see proto/v1alpha2 for the latest API spec).
- A controller to watch and report TaskRun, PipelineRun, and CustomRun updates to the API server.
- A retention policy agent, an agent which deletes older data from DB.
Life of a Result
sequenceDiagram
actor U as Users
participant PC as Pipeline Controller
participant RW as Result Watcher
participant RA as Result API
U->>PC: Create PipelineRun/TaskRun/CustomRun
RW-->>PC: Watch PipelineRun/TaskRun/CustomRun
Note over PC,RW: Wait for Run Completion
RW->>RA: Update results database
U--)RA: Get Results
- User creates a TaskRun, PipelineRun, or CustomRun via the Kubernetes API as usual.
- Result Watcher listens for all TaskRun/PipelineRun/CustomRun changes.
- If a Run has changed, Watcher updates (or creates) a
corresponding
Record(andResultif necessary) using the Results API.- Watcher will also annotate the original Run with identifiers as well.
- Users can get/query Result/Record data directly from the API. Once the Run is complete and has been successfully stored in the Result API, the original CRD object can be safely removed from the cluster.
Getting Started
- Installation
- Results API: Learn how to connect to the API and make queries.
- Watcher: Learn what types the Watcher supports and how it determines Result groupings.
Usage
See the Results API documentation for querying Results and working with the API.
Data Model
graph BT
B(TaskRun) --> |Record| A[Result]
C(Log) --> |Record| A
D(PipelineRun) --> |Record| A
E(CustomRun) --> |Record| A
- Records are individual instances of data. These will commonly be execution data (e.g. PipelineRun, TaskRuns, Logs), but could also reference additional data about the event/execution. Records are intended to be flexible to support arbitrary information tools want to provide around a CI event.
- Results are aggregators of Records, allowing users to refer to groups of
Records as a single entity. For example, you might have a single Result that
groups the following Records:
- Source Event (e.g. pull request, push) that kicked off the action.
- The PipelineRun that occurred.
- The TaskRuns that occurred in response of the PipelineRun (one per Task).
- Receipt of Cloud Event delivery.
- Receipt of Source status update.
(Note: not all of these types of data are supported by the Watcher yet, but are examples of the data we intend to support).
Development
See docs/DEVELOPMENT.md for build, test, and contribution instructions.
Helpful links
Contact
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
api
command
Package main provides the entry point for the Results API server.
|
Package main provides the entry point for the Results API server. |
|
cli-docs
command
Package main provides CLI documentation generation tool.
|
Package main provides CLI documentation generation tool. |
|
retention-policy-agent
command
Package main provides the entry point for the retention policy agent.
|
Package main provides the entry point for the retention policy agent. |
|
tkn-results
command
Command tkn-results is the Tekton Results CLI entrypoint.
|
Command tkn-results is the Tekton Results CLI entrypoint. |
|
watcher
command
Package main provides the entry point for the Results watcher.
|
Package main provides the entry point for the Results watcher. |
|
internal
|
|
|
fieldmask
Package fieldmask provides field mask filtering for protobuf messages.
|
Package fieldmask provides field mask filtering for protobuf messages. |
|
fieldmask/test
Package test contains go:generate directives for fieldmask test proto definitions.
|
Package test contains go:generate directives for fieldmask test proto definitions. |
|
pkg
|
|
|
api/server/cel
Package cel provides definitions for defining the Results CEL environment.
|
Package cel provides definitions for defining the Results CEL environment. |
|
api/server/cel2sql
Package cel2sql provides utilities for converting CEL expressions to SQL queries.
|
Package cel2sql provides utilities for converting CEL expressions to SQL queries. |
|
api/server/db
Package db defines database models for Result data.
|
Package db defines database models for Result data. |
|
api/server/db/errors/postgres
Package postgres provides postgres-specific error checking.
|
Package postgres provides postgres-specific error checking. |
|
api/server/db/errors/sqlite
Package sqlite provides sqlite-specific error checking.
|
Package sqlite provides sqlite-specific error checking. |
|
api/server/db/pagination
Package pagination provides utilities for paginating database query results.
|
Package pagination provides utilities for paginating database query results. |
|
api/server/db/pagination/proto
Package internal contains go:generate directives for pagination proto definitions.
|
Package internal contains go:generate directives for pagination proto definitions. |
|
api/server/features
Package features provides feature flag management for the API server.
|
Package features provides feature flag management for the API server. |
|
api/server/logger
Package logger provides logging utilities for the API server.
|
Package logger provides logging utilities for the API server. |
|
api/server/test
Package test provides test utilities for the API server.
|
Package test provides test utilities for the API server. |
|
api/server/tlsconfig
Package tlsconfig provides TLS configuration parsing and management for the API server.
|
Package tlsconfig provides TLS configuration parsing and management for the API server. |
|
api/server/v1alpha2
Package server provides the v1alpha2 API server implementation.
|
Package server provides the v1alpha2 API server implementation. |
|
api/server/v1alpha2/auth
Package auth provides authentication and authorization utilities for the API server.
|
Package auth provides authentication and authorization utilities for the API server. |
|
api/server/v1alpha2/auth/impersonation
Package impersonation provides user impersonation support for API requests.
|
Package impersonation provides user impersonation support for API requests. |
|
api/server/v1alpha2/lister
Package lister provides list and aggregation operations for Results resources.
|
Package lister provides list and aggregation operations for Results resources. |
|
api/server/v1alpha2/lister/proto
Package proto provides protocol buffer definitions for the lister pagination.
|
Package proto provides protocol buffer definitions for the lister pagination. |
|
api/server/v1alpha2/record
Package record provides utilities for manipulating and validating Records.
|
Package record provides utilities for manipulating and validating Records. |
|
api/server/v1alpha2/result
Package result provides utilities for manipulating and validating Results.
|
Package result provides utilities for manipulating and validating Results. |
|
apis/config
Package config provides configuration types for Results APIs.
|
Package config provides configuration types for Results APIs. |
|
apis/v1alpha3
Package v1alpha3 provides v1alpha3 API types for Tekton Results.
|
Package v1alpha3 provides v1alpha3 API types for Tekton Results. |
|
cli/client
Package client provides REST client functionality for the Results CLI.
|
Package client provides REST client functionality for the Results CLI. |
|
cli/client/logs
Package logs provides a client for interacting with Results logs.
|
Package logs provides a client for interacting with Results logs. |
|
cli/client/records
Package records provides a client for interacting with Results records.
|
Package records provides a client for interacting with Results records. |
|
cli/cmd
Package cmd provides the root command and subcommands for the Results CLI.
|
Package cmd provides the root command and subcommands for the Results CLI. |
|
cli/cmd/config
Package config provides CLI commands for managing Results configuration.
|
Package config provides CLI commands for managing Results configuration. |
|
cli/cmd/pipelinerun
Package pipelinerun provides CLI commands for PipelineRun resources.
|
Package pipelinerun provides CLI commands for PipelineRun resources. |
|
cli/cmd/taskrun
Package taskrun provides CLI commands for TaskRun resources.
|
Package taskrun provides CLI commands for TaskRun resources. |
|
cli/common/prerun
Package prerun provides shared pre-run functions for CLI commands.
|
Package prerun provides shared pre-run functions for CLI commands. |
|
cli/config
Package config provides configuration management for the Results CLI.
|
Package config provides configuration management for the Results CLI. |
|
cli/dev/client
Package client provides gRPC client utilities for the dev CLI.
|
Package client provides gRPC client utilities for the dev CLI. |
|
cli/dev/cmd/logs
Package logs provides commands for retrieving logs from the Results API.
|
Package logs provides commands for retrieving logs from the Results API. |
|
cli/dev/cmd/records
Package records provides commands for interacting with Results records.
|
Package records provides commands for interacting with Results records. |
|
cli/dev/cmd/result
Package result provides commands for interacting with Results.
|
Package result provides commands for interacting with Results. |
|
cli/dev/config
Package config provides configuration management for the dev CLI.
|
Package config provides configuration management for the dev CLI. |
|
cli/dev/flags
Package flags provides shared flag definitions and parameters for CLI commands.
|
Package flags provides shared flag definitions and parameters for CLI commands. |
|
cli/dev/format
Package format provides output formatting utilities for the CLI.
|
Package format provides output formatting utilities for the CLI. |
|
cli/dev/portforward
Package portforward provides Kubernetes port-forwarding utilities for the CLI.
|
Package portforward provides Kubernetes port-forwarding utilities for the CLI. |
|
cli/flags
Package flags provides flag definitions for the Results CLI.
|
Package flags provides flag definitions for the Results CLI. |
|
cli/options
Package options provides shared option structs for CLI commands.
|
Package options provides shared option structs for CLI commands. |
|
cli/testutils
Package testutils provides test utility functions for the CLI package
|
Package testutils provides test utility functions for the CLI package |
|
converter
Package converter provides utilities for converting between Result types.
|
Package converter provides utilities for converting between Result types. |
|
customrunmetrics
Package customrunmetrics provides metrics collection for CustomRun resources.
|
Package customrunmetrics provides metrics collection for CustomRun resources. |
|
internal/jsonutil
Package jsonutil provides JSON utility functions for testing.
|
Package jsonutil provides JSON utility functions for testing. |
|
internal/protoutil
Package protoutil provides utilities for manipulating protos in tests.
|
Package protoutil provides utilities for manipulating protos in tests. |
|
internal/test
Package test provides test utilities and mock clients.
|
Package test provides test utilities and mock clients. |
|
logs
Package logs provides log writing utilities.
|
Package logs provides log writing utilities. |
|
metrics
Package metrics provides unified metrics recording for Tekton Results.
|
Package metrics provides unified metrics recording for Tekton Results. |
|
pipelinerunmetrics
Package pipelinerunmetrics provides metrics collection for PipelineRun resources.
|
Package pipelinerunmetrics provides metrics collection for PipelineRun resources. |
|
retention
Package retention provides data retention policy management.
|
Package retention provides data retention policy management. |
|
taskrunmetrics
Package taskrunmetrics provides metrics collection for TaskRun resources.
|
Package taskrunmetrics provides metrics collection for TaskRun resources. |
|
test
Package test provides test utilities and assertions.
|
Package test provides test utilities and assertions. |
|
test/fake
Package fake provides fake implementations for testing.
|
Package fake provides fake implementations for testing. |
|
watcher/convert
Package convert provides a method to convert Pipeline v1 API objects to Results API proto objects.
|
Package convert provides a method to convert Pipeline v1 API objects to Results API proto objects. |
|
watcher/grpc
Package grpc provides utilities for working with gRPC clients/servers.
|
Package grpc provides utilities for working with gRPC clients/servers. |
|
watcher/logs
Package logs provides log streaming utilities for the watcher.
|
Package logs provides log streaming utilities for the watcher. |
|
watcher/reconciler
Package reconciler provides the core reconciliation logic for the watcher.
|
Package reconciler provides the core reconciliation logic for the watcher. |
|
watcher/reconciler/annotation
Package annotation provides utilities for managing Result annotations on Tekton resources.
|
Package annotation provides utilities for managing Result annotations on Tekton resources. |
|
watcher/reconciler/client
Package client provides utilities for interacting with watcher reconciler clients.
|
Package client provides utilities for interacting with watcher reconciler clients. |
|
watcher/reconciler/customrun
Package customrun provides the CustomRun reconciler controller.
|
Package customrun provides the CustomRun reconciler controller. |
|
watcher/reconciler/dynamic
Package dynamic provides dynamic reconciliation for Tekton resources.
|
Package dynamic provides dynamic reconciliation for Tekton resources. |
|
watcher/reconciler/leaderelection
Package leaderelection provides a few utilities to help us to enable leader election support in the Watcher controllers.
|
Package leaderelection provides a few utilities to help us to enable leader election support in the Watcher controllers. |
|
watcher/reconciler/pipelinerun
Package pipelinerun provides the PipelineRun reconciler controller.
|
Package pipelinerun provides the PipelineRun reconciler controller. |
|
watcher/reconciler/taskrun
Package taskrun provides the TaskRun reconciler controller.
|
Package taskrun provides the TaskRun reconciler controller. |
|
watcher/results
Package results provides the Results client for the watcher.
|
Package results provides the Results client for the watcher. |
|
proto
|
|
|
pipeline/v1
Package v1 contains go:generate directives for pipeline proto definitions.
|
Package v1 contains go:generate directives for pipeline proto definitions. |
|
v1alpha2
Package v1alpha2 contains go:generate directives for Results API v1alpha2 proto definitions.
|
Package v1alpha2 contains go:generate directives for Results API v1alpha2 proto definitions. |
|
v1alpha2/results_go_proto
Package results_go_proto is a reverse proxy.
|
Package results_go_proto is a reverse proxy. |
|
v1alpha3
Package v1alpha3 contains go:generate directives for Results API v1alpha3 proto definitions.
|
Package v1alpha3 contains go:generate directives for Results API v1alpha3 proto definitions. |
|
test
|
|
|
e2e/client
Package client provides test clients for e2e testing.
|
Package client provides test clients for e2e testing. |
|
tools
|
|
|
simpleui
command
|
|
|
tkn-results
module
|
Click to show internal directories.
Click to hide internal directories.