From cbb889091df677f9122cd93a872bf83c8c71e01b Mon Sep 17 00:00:00 2001 From: Sergetron <28788978+sergetron@users.noreply.github.com> Date: Thu, 4 Mar 2021 12:34:10 -0500 Subject: [PATCH] Rewrite triggertemplates.md for clarity and flow Rewrites triggertemplates.md for clarity and flow --- docs/triggertemplates.md | 150 ++++++++++++++------------------------- 1 file changed, 55 insertions(+), 95 deletions(-) diff --git a/docs/triggertemplates.md b/docs/triggertemplates.md index d7c4d0918..be70c7eca 100644 --- a/docs/triggertemplates.md +++ b/docs/triggertemplates.md @@ -1,14 +1,29 @@ -# 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: ```YAML @@ -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`: - `` -- To track resources created by the same event: `tekton.dev/triggers-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 `` 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.) -``` +* 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`:`` to help with housekeeping and garbage collection. + * `tekton.dev/triggers-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 { @@ -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 @@ -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.