diff --git a/docs/triggerbindings.md b/docs/triggerbindings.md index 68cf24ef8..c025127ec 100644 --- a/docs/triggerbindings.md +++ b/docs/triggerbindings.md @@ -4,12 +4,18 @@ linkTitle: "Trigger Bindings" weight: 4 --- --> -# TriggerBindings +# `TriggerBindings` -As per the name, `TriggerBinding`s bind against events/triggers. -`TriggerBinding`s enable you to capture fields from an event and store them as -parameters. The separation of `TriggerBinding`s from `TriggerTemplate`s was -deliberate to encourage reuse between them. +A `TriggerBinding` is a resource that specifies the fields in the event payload from which you want to extract data as well as the fields in your +corresponding [`TriggerTemplate`](.docs/triggertemplates.md) to populate with the extracted values. In other words, it *binds* payload fields to +fields in the [`TriggerTemplate`] and for this to work the fields specified in the [`TriggerBinding`] And the corresponding [`TriggerTemplate`] +**must** match. You can then use the populated fields in your [`TriggerTemplate`] to populate fields in the [`TaskRun`] or [`PipelineRun`] associated +with that [`TriggerTemplate`]. Tekton also supports a cluster-scoped version called a `ClusterTriggerBinding` to encourage reusability across your +entire cluster. + +## Structure of a `TriggerBinding` + +Below is an example `TriggerBinding` definition: ```YAML @@ -27,63 +33,108 @@ spec: value: $(header.Content-Type) ``` +## `TriggerBindings` vs. `ClusterTriggerBindings` -`TriggerBinding`s are connected to `TriggerTemplate`s within an -[`EventListener`](eventlisteners.md), which is where the pod is actually -instantiated that "listens" for the respective events. +A `ClusterTriggerBinding` is a cluster-scoped `TriggerBinding` that you can reuse across your entire cluster. +You can reference a `ClusterTriggerBinding` in any `EventListener` in any namespace. You can specify multiple +`ClusterTriggerBindings` within your `Trigger` as well as specify the same `ClusterTriggerBinding` in multiple +`Triggers`. -## Parameters +Below is an example `ClusterTriggerBinding` definition: -`TriggerBinding`s can provide `params` which are passed to a `TriggerTemplate`. -Each parameter has a `name` and a `value`. + +```YAML +apiVersion: triggers.tekton.dev/v1alpha1 +kind: ClusterTriggerBinding +metadata: + name: pipeline-clusterbinding +spec: + params: + - name: gitrevision + value: $(body.head_commit.id) + - name: gitrepositoryurl + value: $(body.repository.url) + - name: contenttype + value: $(header.Content-Type) +``` -## Event Variable Interpolation +When referencing a `ClusterTriggerBinding`, you must specify a `kind` value within the `bindings` field. +The default is `TriggerBinding` which denotes a namespaced `TriggerBinding`. For example: -TriggerBindings can access values from the HTTP JSON body and the headers using -JSONPath expressions wrapped in `$()`. The key in the header is -case-insensitive. + +```YAML +--- +apiVersion: triggers.tekton.dev/v1alpha1 +kind: EventListener +metadata: + name: listener-clustertriggerbinding +spec: + serviceAccountName: tekton-triggers-example-sa + triggers: + - name: foo-trig + bindings: + - ref: pipeline-clusterbinding + kind: ClusterTriggerBinding + - ref: message-clusterbinding + kind: ClusterTriggerBinding + template: + ref: pipeline-template +``` + +## Specifying paramters + +A `TriggerBinding` allows you to specify parameters (`params`) that Tekton passes to the corresponding `TriggerTemplate`. +For each parameter, you must specify a `name` and a `value` field with the appropriate values. -These are all valid expressions: +## Accessing data in HTTP JSON payloads + +Tekton can use a `TriggerBinding` to access data in the headers and body of an HTTP JSON payload. To do so, it uses +JSONPath expressions encapsulated within a `$()` wrapper. Keys in HTTP JSON headers are case-sensitive. + +For example, below is a valid expression: ```shell $(body.key1) $(.body.key) ``` -These are invalid expressions: +On the other hand, the expressions below are invalid: ```shell -.body.key1 # INVALID - Not wrapped in $() -$({body) # INVALID - Ending curly brace absent +.body.key1 # INVALID - Expression is not wrapped in `$()`. +$({body) # INVALID - Trailing curly brace is missing. ``` -If the `$()` is embedded inside another `$()` we will use the contents of the -innermost `$()` as the JSONPath expression +If a `$()` wrapper is embedded inside another `$()` wrapper, Tekton parses the contents of the innermost wrapper +as the JSONPath expression. For example: ```shell script -$($(body.b)) -> $(body.b) -$($($(body.b))) -> $(body.b) +$($(body.b)) # Parsed as $(body.b) +$($($(body.b))) # Parsed as $(body.b) ``` -#### Keys with dots `.` +## Accessing JSON keys containing periods (`.`) -To access JSON keys that contain `.` character, we need to escape the `.` e.g. +To access a JSON key that contains a period (`.`), you must escape the period with a backslash (`\.`). For example: ```shell script -# body contains a filed called "tekton.dev" e.g. {"body": {"tekton.dev": "triggers"}} +# Body contains a `tekton.dev` field: {"body": {"tekton.dev": "triggers"}} $(body.tekton\.dev) -> "triggers" ``` -#### Defaulting +## Fallback to default values + +If Tekton fails to resolve the JSONPath expressions you have configured against the HTTP JSON payload, it +falls back to the `default` value in the corresponding `TriggerTemplate`, if specified. -If the HTTP headers and body contents from an event fail to resolve the JSONPath expressions supplied, -and attempt will be made to utilize the `default` value, if supplied, from the associated `TriggerTemplate`. -### Examples +## Field binding examples + +Below are some examples of Tekton performing field binding based on the most commonly used field definitions: ```shell -`$(body)` is replaced by the entire body. +`$(body)` -> replaced by the entire body $(body) -> "{"key1": "value1", "key2": {"key3": "value3"}, "key4": ["value4", "value5", "value6"]}" @@ -97,7 +148,7 @@ $(body.key4[0]) -> "value4" $(body.key4[0:2]) -> "{"value4", "value5"}" -# $(header) is replaced by all of the headers from the event. +# $(header) -> replaced by all headers from the event $(header) -> "{"One":["one"], "Two":["one","two","three"]}" @@ -110,13 +161,12 @@ $(header.Two) -> "one two three" $(header.Two[1]) -> "two" ``` -## Multiple Bindings +## Specifying multiple bindings -In an [`EventListener`](eventlisteners.md), you may specify multiple bindings as -part of your trigger. This allows you to create reusable bindings that can be -mixed and matched with various triggers. For example, a trigger with one binding -that extracts event information, and another binding that provides deploy -environment information: +You can specify multiple bindings within the `Trigger` definition in your [`EventListener`](eventlisteners.md). +This allows you to reuse as well as mix-and-match your bindings across multiple `Trigger` definitions. For +example, you can create a `Trigger` with a binding that extracts event data and another binding that provides +information on the deployment environment: ```yaml apiVersion: triggers.tekton.dev/v1alpha1 @@ -168,13 +218,18 @@ spec: ref: pipeline-template ``` -## Debugging +## Troubleshooting `TriggerBindings` -### Evaluating TriggerBindings +You can use the `binding-eval` tool to evaluate your `TriggerBinding` against a specific HTTP request +to determine the parameters that Tekton generates from that request when your corresponding `Trigger` executes. -As a convenience, the `binding-eval` tool allows you to evaluate TriggerBindings -for a given HTTP request to determine what the resulting parameters would be -during trigger execution. +To install the `binding-eval` tool use the following command: + +```sh +$ go get -u github.com/tektoncd/triggers/cmd/binding-eval +``` + +Below is an example of using the tool to evaluate a `TriggerBinding`: ```sh $ cat testdata/triggerbinding.yaml @@ -209,9 +264,3 @@ $ binding-eval -b testdata/triggerbinding.yaml -r testdata/http.txt } ] ``` - -To install, run: - -```sh -$ go get -u github.com/tektoncd/triggers/cmd/binding-eval -```