Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rewrite triggerbindings.md for clarity and flow #988

Merged
merged 1 commit into from
Mar 10, 2021
Merged

Rewrite triggerbindings.md for clarity and flow #988

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
147 changes: 98 additions & 49 deletions docs/triggerbindings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

<!-- FILE: examples/triggerbindings/triggerbinding.yaml -->
```YAML
Expand All @@ -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`.
<!-- FILE: examples/clustertriggerbindings/clustertriggerbinding.yaml -->
```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.
<!-- FILE: examples/eventlisteners/eventlistener-clustertriggerbinding.yaml -->
```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"]}"

Expand All @@ -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"]}"

Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
```