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 triggertemplates.md for clarity and flow #981

Merged
merged 1 commit into from
Mar 5, 2021
Merged

Rewrite triggertemplates.md for clarity and flow #981

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
150 changes: 55 additions & 95 deletions docs/triggertemplates.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,29 @@
<!--
---
linkTitle: "Trigger Templates"
linkTitle: "TriggerTemplates"
weight: 3
---
-->
# TriggerTemplates
# `TriggerTemplates`

A `TriggerTemplate` is a resource that can template resources.
`TriggerTemplate`s have [parameters](#parameters) that can be substituted
**anywhere** within the resource template.
A `TriggerTemplate` is a resource that specifies a blueprint for the resource, such as a `TaskRun` or `PipelineRun`, that you want to instantiate
and/or execute when your `EventListener` detects an event. It exposes parameters that you can use anywhere within your resource's template.

`TriggerTemplates` currently support the following [Tekton Pipelines](https://github.com/tektoncd/pipeline) resources:

`v1alpha1 ` | `v1beta1`
---------------------|---------
`Pipeline` | `Pipeline`
`PipelineRun` | `PipelineRun`
`Task` | `Task`
`TaskRun` | `TaskRun`
`ClusterTask` | `ClusterTask`
`Condition` |
`PipelineResource` |

## Structure of a `TriggerTemplate`

Below is an example `TriggerTemplate` definition:

<!-- FILE: examples/triggertemplates/triggertemplate.yaml -->
```YAML
Expand Down Expand Up @@ -52,100 +67,51 @@ spec:
value: $(tt.params.gitrepositoryurl)
```

`TriggerTemplates` currently support the following [Tekton Pipelines](https://github.com/tektoncd/pipeline) resources:
Keep the following in mind:

v1alpha1 | v1beta1
------------------|---------
pipelines | pipelines
pipelineruns | pipelineruns
tasks | tasks
taskruns | taskruns
clustertasks | clustertasks
conditions |
pipelineresources |

Similar to
[Pipelines](https://github.com/tektoncd/pipeline/blob/master/docs/pipelines.md),`TriggerTemplate`s
do not do any actual work, but instead act as the blueprint for what resources
should be created.

If the namespace is omitted, it will be resolved to the `EventListener`'s
namespace.

The `$(uid)` variable is implicitly available throughout a `TriggerTemplate`'s
resource templates. A random string value is assigned to `$(uid)` like the
postfix generated by the Kubernetes `generateName` metadata field. One instance
where there is useful is when resources in a `TriggerTemplate` have internal
references.

The following are additional labels added to all `TriggerTemplate` resource
templates:

- To help with housekeeping/garbage collection: `tekton.dev/eventlistener`:
`<EventListenerName>`
- To track resources created by the same event: `tekton.dev/triggers-eventid`:
`<EventID>`

To enable support for arbitrary resource types, the resource templates are
internally resolved as byte blobs. As a result, validation on these resources is
only done at event processing time (rather than during `TriggerTemplate`
creation). :rotating_light: As of now, only Tekton resources can be defined
within a `TriggerTemplate` :rotating_light:

## Parameters

`TriggerTemplate`s can declare parameters that are supplied by a
`TriggerBinding` and/or `EventListener`. `params` must have a `name`, and can
have an optional `description` and `default` value.

`params` can be referenced in the `TriggerTemplate` using the following variable
substitution syntax, where `<name>` is the name of the parameter:
* If you don't specify the namespace, Tekton resolves it to the namespace of the `EventListener` that specifies the given `TriggerTemplate`.

```YAML
$(tt.params.<name>)
```
* The `$(uid)` variable is implicitly available to the resource templates you specify in your `TriggerTemplate` with a random value, just like
the postfix generated by the Kubernetes `generateName` metadata field. This can be useful for resource templates that use internal references.

* Tekton adds the following labels to all resource templates within a `TriggerTemplate`:

`tt.params` can be referenced in the `resourceTemplates` section of a
`TriggerTemplate`. The purpose of `tt.params` is to make `TriggerTemplates`
reusable.
* `tekton.dev/eventlistenter`:`<EventListenerName>` to help with housekeeping and garbage collection.
* `tekton.dev/triggers-eventid`:`<EventID>` to track resources created by a specific event.

The value of the `default` field for each entry of the `params` array defined in a `TriggerTemplate` will
be applied if a corresponding entry in the `params` array in a `TriggerBinding` is either missing or cannot
be satisfied in the cases where the entry's value comes from an HTTP header or body.
* To support arbitrary resource types, Tekton resolves resource templates internally as byte blobs. Because of this, Tekton only validates these
resources when processing an event rather than at the creation of the `TriggerTemplate`. Thus, you can **only** specify Tekton resources in a
`TriggerTemplate`.

## Best Practices
* As of Tekton Pipelines [0.8.0](https://github.com/tektoncd/pipeline/releases/tag/v0.8.0), you can embed resource definitions directly in
your `TriggerTemplate` definition. To prevent a race condition between creating and using resources, you **must** embed each resource definition
witihn the `PipelineRun` or `TaskRun` that uses that resource.

As of Tekton Pipelines version
[v0.8.0](https://github.com/tektoncd/pipeline/releases/tag/v0.8.0), users can
embed resource specs. It is a best practice to embed each resource specs in the
PipelineRun or TaskRun that uses the resource spec. Embedding the resource spec
avoids a race condition between creating and using resources.
## Specifying parameters

## Templating Params
A `TriggerTemplate` allows you to declare parameters supplied by the associated `TriggerBinding` and/or `EventListener` as follows:

When templating parameters into resources, a simple replacement on the string
with the parameter name e.g. `$(tt.params.name)` is carried out.
* Declare your parameters in the `params` section of the `TriggerTemplate` definition.

This means that for simple string / number values, replacements in the
YAML should work fine.
* You must specify a `name` and can optionally specifiy a `description` and a `default` value.

If the string could begin with a number e.g. `012abcd`, it might be misinterpreted by YAML as a
number, which could cause an error, in which case you can put quotes around the
templated parameter key, and it should solve the problem.
* Tekton applies the value of the `default` field for each entry in the `params` array of your `TriggerTemplate` if it can't find a corresponding
value in the associated `TriggerBinding` or cannot successfully extract the value from an HTTP header or body payload.

## Escaping quoted strings.
* You can reference `tt.params` in the `resourceTemplates` section of your `TriggerTemplate` to make your `TriggerTemplate` reusable.

TriggerTemplate parameter values were previously escaped by simply replacing
`"` with `\"` this could lead to problems when strings were already escaped, and
generating invalid resources from the TriggerTemplate.
* When you specify parameters in your resource template definitions, Tekton replaces the specified string with the parameter name, for example `$(tt.params.name)`.
Therefore, simple string and number value replacements work fine directly in your YAML file. However, if a string has a numerical prefix, such as `123abcd`,
Tekton can misinterpret it to be a number and throw an error. In such cases, enclose the affected parameter key in quotes (`"`).

No escaping is done on the templated variables, if you are inserting a JSON
object as a template var, then you should not put it within a quoted string.

This behaviour has been deprecated, if this breaks your templates, you can add
an annotation to the TriggerTemplate.
## Embedding JSON objects within resource templates

For example with the following JSON body:
Tekton no longer replaces quotes (`"`) with escaped quotes (`\"`) and does not perform any escaping on variables in your resource templates.
If you are embedding JSON objects as variables in your templates, you **must not** enclose them with quotes (`"`). If you have existing `TriggerTemplates`
that use escaped quotes, add an annotation to work around this behavior change.

For example, consider the following JSON object:

```json
{
Expand All @@ -156,11 +122,8 @@ For example with the following JSON body:
}
```

If you have a TriggerBinding that extracts `$(body.title)` then when it's
inserted into a TriggerTemplate it will be embedded as `this is a \"demo\"
body`.

By annotating the TriggerTemplate.
If your `TriggerBinding` extracts `$(body.title)` then Tekton inserts it into your `TriggerTemplate` as `this is a \"demo\" body`.
To work around this, annotate the `TriggerTemplate` as follows:

```yaml
apiVersion: triggers.tekton.dev/v1alpha1
Expand All @@ -175,9 +138,6 @@ spec:
description: The title from the incoming body
```

This would pass the same body through as `this is a \""demo\"" body`, which is
invalid JSON, but, if you were to use a value with `$(body.object)` in a
template, and want it passed through as a quoted string, then this will work.

This might be useful if you want a string of JSON that you want to parse in a
command.
This way, Tekton passes the value as `this is a \""demo\"" body`, which in itself is not valid JSON code; however, if you use a value with `$(body.object)`
in a resource template that specifically passes it as a quoted string, then this workaround restores normal operation. This can also be useful for parsing
a string containing JSON code in a command.