Tekton Triggers

An Introduction to Tekton Triggers

The Tekton CD Project has existed for about a year now, and the community has been hard at work building the necessary pieces to assemble enterprise-grade, cloud-native software delivery pipelines for any organization. One of the biggest missing pieces until very recently was an eventing or triggering component. Thanks to some awesome work from a group of contributors, the Triggers project shipped its first release in October. This post explains how to Tekton Triggers were designed and how to get started using them.

Design Principles

Tekton Pipelines were designed to be reusable and decoupled from the start. That means unlike many other CD and Pipeline systems, the definition for a Tekton Pipeline does not contain any information about the exact resources it will operate on or the conditions it will be executed under. Tekton Pipelines are bound to an execution environment (which git repo source code lives in, which cluster to target, where to store logs and artifacts) when they are executed. The Pipeline does not know why it was executed, which makes it possible to use the same Pipeline definition in a wide range of scenarios. Users can manually execute one as part of testing and development, or automate the flow for a continuous delivery system.

The Triggers project was started to provide a mechanism to declaratively create PipelineRuns based on external events. Pipelines have no knowledge of the external event that started them, and Triggers have no knowledge of the Pipeline itself that will be run. This provides for a great separation of concerns between the two projects, making them easy to understand on their own, and flexible enough to be used with other execution engines or eventing systems.

At its core, Tekton Triggers implements a system for creating Kubernetes resources in response to external events, currently in the form of webhooks. Data from the incoming web request can be extracted and used to parameterize the created resources. While the system was designed to create other Tekton resources (PipelineRuns, TaskRuns and PipelineResources), it can be used to create any Kubernetes object.

Trigger Concepts

The Tekton Triggers project defines three main concepts (as Kubernetes CRDs). These are TriggerBindings, TriggerTemplates, and EventListeners. TriggerBindings provide the logic to extract data from an incoming event or web request. Currently JSON formatted data is supported through the GJSON path syntax, but this is likely to become more flexible over time. TriggerTemplates provide a system to declare which Kubernetes resources should be created, and how to use the parameterized data from a TriggerBinding. Finally, EventListeners tie these two concepts together. They provide an endpoint that can listen for incoming events, handle basic filtering, extract data using TriggerBindings and create objects using TriggerTemplates.

Example

Now let’s show how to use these three concepts to put together a simple CI system. This system will run tests on a Github PR and set the status accordingly. First, we need to define a TriggerBinding to extract data from an incoming Github web hook. The Github event we’ll be using is called pull_request, and the payload is described here. There is a lot of data we could use, but we only need a few fields. We’ll extract the SHA of the pull request, the URL of the repository and URL for the Pull Request itself.

Next, we need to tell the Trigger project what we’d like it to do when we receive one of these events. Since we just want to run some tests and set a status on the Github PR, we don’t need a full PipelineRun. A simple TaskRun should be sufficient. The Task itself is decoupled from its environment, so that won’t have to change on each PR. We’ll just instantiate it with a different set of inputs for each event. That Task would look like this:

This task runs a test script, located at test.sh . If the test fails, we leave a comment with the error. Then we set the status on the PR to either success or failure accordingly. For more information on how this works, check out the documentation on Tekton resources.

Now with our Task definition, we can setup our TriggerTemplate to create PipelineResources and a new TaskRun for each incoming PR event. That would look like:

Finally, we need to create our EventListener. This is the resource that exposes a Kubernetes service that listens for events, extracts data and creates resources. That might look something like this:

Putting It All Together

These three types provide everything we need to listen for external events, extract data for them, and create Tekton resources using this extracted data. This lets users build up CI or delivery pipelines that react to anything that supports HTTP webhooks.

We’re making use of these features already in the Tekton project today! Our first usage of this is to manage our GitHub organization permissions. This system lets users declaratively specify membership, permissions and other information for a GitHub organization in code. Each time this file gets changed, we run a Tekton Task to synchronize these permissions.

What’s Next

In the next few releases, we’re hoping to add support for richer data extraction, advanced event filtering, and built-in validation for more event systems. This will make it even easier to setup a secure, reliable delivery pipeline with Tekton Triggers.