Add example and documentation for Trigger as Ref

Example eventlistener-triggerref and trigger created. Also,
added documentation of Trigger and information in Eventlistener
for refering to Trigger.

docs/eventlisteners.md

@@ -70,7 +70,7 @@ metadata:
 rules:
 # Permissions for every EventListener deployment to function
 - apiGroups: ["triggers.tekton.dev"]
-  resources: ["eventlisteners", "triggerbindings", "triggertemplates"]
+  resources: ["eventlisteners", "triggerbindings", "triggertemplates", "triggers"]
   verbs: ["get"]
 - apiGroups: [""]
   # secrets are only needed for Github/Gitlab interceptors
@@ -99,8 +99,11 @@ The `triggers` field is required. Each EventListener can consist of one or more
 - `name` - (Optional) a valid
   [Kubernetes name](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set)
 - [`interceptors`](#interceptors) - (Optional) list of interceptors to use
-- `bindings` - A list of `TriggerBindings` reference to use or embedded TriggerBindingsSpecs to use.
-- `template` - The name of `TriggerTemplate` to use
+- `bindings` - (Optional) A list of `TriggerBindings` reference to use or embedded TriggerBindingsSpecs to use.
+- `template` - (Optional) The name of `TriggerTemplate` to use
+- `triggerRef` - (Optional) Reference to the [`Trigger`](./triggers.md).
+
+A `trigger` field must have `template` (along with needed `bindings` and `interceptors`) or `triggerRef`.
 
 ```yaml
 triggers:
@@ -119,6 +122,12 @@ triggers:
       name: pipeline-template
 ```
 
+Or with only `triggerRef`:
+```yaml
+triggers:
+    - triggerRef: trigger
+```
+
 Also, to support multi-tenant styled scenarios, where an administrator may not want all triggers to have
 the same permissions as the `EventListener`, a service account can optionally be set at the trigger level
 and used if present in place of the `EventListener` service account when creating resources:

docs/triggers.md

@@ -0,0 +1,54 @@
+<!--
+---
+linkTitle: "Trigger"
+weight: 9
+---
+-->
+# Triggers
+
+A `Trigger` is resource that combines `TriggerTemplate`, `TriggerBindings` and `interceptors`. The `Trigger` is processed by EventListener which referenced it when it receives an incoming.
+
+- [Syntax](#syntax)
+
+## Syntax
+
+To define a configuration file for an `Trigger` resource, you can specify
+the following fields:
+
+- Required:
+  - [`apiVersion`][kubernetes-overview] - Specifies the API version, for example
+    `triggers.tekton.dev/v1alpha1`.
+  - [`kind`][kubernetes-overview] - Specifies the `Trigger` resource
+    object.
+  - [`metadata`][kubernetes-overview] - Specifies data to uniquely identify the
+    `Trigger` resource object, for example a `name`.
+  - [`spec`][kubernetes-overview] - Specifies the configuration information for
+    your Trigger resource object. The spec include:
+    - [`bindings`] -  A list of `TriggerBindings` reference to use or embedded TriggerBindingsSpecs to use
+    - [`template`] -  The name of `TriggerTemplate` to use
+    - [`interceptors`](./eventlisteners.md#interceptors) - (Optional) list of interceptors to use
+    - [`serviceAccountName`] - (Optional) Specifies the ServiceAccount provided to EventListener by Trigger to create resources
+
+
+<!-- FILE: examples/triggers/trigger.yaml -->
+```YAML
+apiVersion: triggers.tekton.dev/v1alpha1
+kind: Trigger
+metadata:
+  name: trigger
+spec:
+  interceptors:
+    - cel:
+        filter: "header.match('X-GitHub-Event', 'pull_request')"
+        overlays:
+        - key: extensions.truncated_sha
+          expression: "body.pull_request.head.sha.truncate(7)"
+  bindings:
+  - ref: pipeline-binding
+  template:
+    name: pipeline-template
+```
+
+[kubernetes-overview]:
+  https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields
+

examples/role-resources/clustertriggerbinding-roles/clusterrole.yaml

@@ -5,7 +5,7 @@ metadata:
 rules:
 # Permissions for every EventListener deployment to function
 - apiGroups: ["triggers.tekton.dev"]
-  resources: ["clustertriggerbindings", "eventlisteners", "triggerbindings", "triggertemplates"]
+  resources: ["clustertriggerbindings", "eventlisteners", "triggerbindings", "triggertemplates", "triggers"]
   verbs: ["get"]
 - apiGroups: [""]
   # secrets are only needed for Github/Gitlab interceptors

examples/role-resources/triggerbinding-roles/role.yaml

@@ -5,7 +5,7 @@ metadata:
 rules:
 # Permissions for every EventListener deployment to function
 - apiGroups: ["triggers.tekton.dev"]
-  resources: ["eventlisteners", "triggerbindings", "triggertemplates"]
+  resources: ["eventlisteners", "triggerbindings", "triggertemplates", "triggers"]
   verbs: ["get"]
 - apiGroups: [""]
   # secrets are only needed for Github/Gitlab interceptors

examples/triggers/eventlistener-triggerref.yaml

@@ -0,0 +1,8 @@
+apiVersion: triggers.tekton.dev/v1alpha1
+kind: EventListener
+metadata:
+  name: listener-triggerref
+spec:
+  serviceAccountName: tekton-triggers-example-sa
+  triggers:
+    - triggerRef: trigger

examples/triggers/rbac.yaml

@@ -0,0 +1,48 @@
+---
+kind: Role
+apiVersion: rbac.authorization.k8s.io/v1
+metadata:
+  name: tekton-triggers-example-minimal
+rules:
+# Permissions for every EventListener deployment to function
+- apiGroups: ["triggers.tekton.dev"]
+  resources: ["eventlisteners", "triggerbindings", "triggertemplates", "triggers"]
+  verbs: ["get"]
+- apiGroups: [""]
+  # secrets are only needed for Github/Gitlab interceptors
+  resources: ["configmaps", "secrets"]
+  verbs: ["get", "list", "watch"]
+# Permissions to create resources in associated TriggerTemplates
+- apiGroups: ["tekton.dev"]
+  resources: ["pipelineruns", "pipelineresources", "taskruns"]
+  verbs: ["create"]
+- apiGroups: [""]
+  resources: ["serviceaccounts"]
+  verbs: ["impersonate"]
+---
+apiVersion: v1
+kind: Secret
+metadata:
+  name: tekton-triggers-example-secret
+type: Opaque
+stringData:
+  secretToken: "1234567"
+---
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: tekton-triggers-example-sa
+secrets:
+  - name: tekton-triggers-example-secret
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+  name: tekton-triggers-example-binding
+subjects:
+- kind: ServiceAccount
+  name: tekton-triggers-example-sa
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: Role
+  name: tekton-triggers-example-minimal

examples/triggers/trigger.yaml

@@ -0,0 +1,15 @@
+apiVersion: triggers.tekton.dev/v1alpha1
+kind: Trigger
+metadata:
+  name: trigger
+spec:
+  interceptors:
+    - cel:
+        filter: "header.match('X-GitHub-Event', 'pull_request')"
+        overlays:
+        - key: extensions.truncated_sha
+          expression: "body.pull_request.head.sha.truncate(7)"
+  bindings:
+  - ref: pipeline-binding
+  template:
+    name: pipeline-template

examples/triggers/triggerbinding.yaml

@@ -0,0 +1,12 @@
+apiVersion: triggers.tekton.dev/v1alpha1
+kind: TriggerBinding
+metadata:
+  name: pipeline-binding
+spec:
+  params:
+  - name: gitrevision
+    value: $(body.head_commit.id)
+  - name: gitrepositoryurl
+    value: $(body.repository.url)
+  - name: contenttype
+    value: $(header.Content-Type)

examples/triggers/triggertemplate.yaml

@@ -0,0 +1,38 @@
+apiVersion: triggers.tekton.dev/v1alpha1
+kind: TriggerTemplate
+metadata:
+  name: pipeline-template
+spec:
+  params:
+  - name: gitrevision
+    description: The git revision
+    default: master
+  - name: gitrepositoryurl
+    description: The git repository url
+  - name: message
+    description: The message to print
+    default: This is the default message
+  - name: contenttype
+    description: The Content-Type of the event
+  resourcetemplates:
+  - apiVersion: tekton.dev/v1beta1
+    kind: PipelineRun
+    metadata:
+      generateName: simple-pipeline-run-
+    spec:
+      pipelineRef:
+        name: simple-pipeline
+      params:
+      - name: message
+        value: $(tt.params.message)
+      - name: contenttype
+        value: $(tt.params.contenttype)
+      resources:
+      - name: git-source
+        resourceSpec:
+          type: git
+          params:
+          - name: revision
+            value: $(tt.params.gitrevision)
+          - name: url
+            value: $(tt.params.gitrepositoryurl)