Add API to configure Interceptors from a Trigger

This commit adds new fields (`ref`, `param`, `name`) to refer to a pluggable Interceptor from within a Trigger's spec. Previously a user could either reference one of core interceptors (e.g. `cel`) or use the `webhook` field to refer to webhook interceptors. The new API is a replacement for these old options though the old API will continue to work for now to ensure backwards compatibility. The new fields are: 1. `ref`: This is required and references a ClusterInterceptor 2. `params`: Any optional params to pass on to the Interceptor. The values can be any valid JSON. 3. `name`: Optional name to configure a named interceptor config. Part of tektoncd#869 Signed-off-by: Dibyo Mukherjee <dibyo@google.com>
dibyom · Mar 19, 2021 · 8a76f34 · 8a76f34
1 parent 5a59253
commit 8a76f34
Show file tree

Hide file tree

Showing 43 changed files with 555 additions and 250 deletions.
diff --git a/docs/clusterinterceptors.md b/docs/clusterinterceptors.md
@@ -12,11 +12,18 @@ custom resource describes how an EventListener can connect to a workload that
 is running the interceptor business logic (and in the future what extra
 paramters the interceptor accepts).
 
-**NOTE**: This doc is a WIP. Please also see the [Interceptors section](./eventlisteners.md#interceptors) in the EventListener doc.
+A `ClusterInterceptor` will consist of a custom resource of type ClusterInterceptor that defines it and a 
+deployment/service combination that runs a HTTP server containing the actual interceptor processing logic. The 
+interceptor can process the incoming request, decide to stop or continue processing, and add extra fields that are 
+available to `TriggerBindings` and other interceptors in a chain under the `extensions` field.
+
+**NOTE**: This doc describes a ClusterInterceptor and its interface. Please see the [Interceptors section](./eventlisteners.md#interceptors) 
+in the EventListener doc for details on how to configure a Trigger to use an interceptor.
 
 - [Interceptors](#interceptors)
   - [Syntax](#syntax)
     - [clientConfig](#clientConfig)
+  - [Interceptor Services](#interceptor-services)
 
 ## Syntax
 
@@ -55,3 +62,13 @@ spec:
       port: 8081 # defaults to 80
 ```
 
+## Interceptor Services
+
+To be a valid ClusterInterceptor, the workload should satisfy the following:
+
+- Be fronted by a regular Kubernetes v1 Service and serve HTTP
+- Accept HTTP POST requests that contain a [`InterceptorRequest`](https://pkg.go.dev/github.com/tektoncd/triggers/pkg/apis/triggers/v1alpha1#InterceptorRequest) 
+  JSON body
+- Respond with a status code of 200 OK with [`InterceptorResponse`](https://pkg.go.dev/github.com/tektoncd/triggers/pkg/apis/triggers/v1alpha1#InterceptorResponse) 
+  body
+- Respond with a non 200 response only if something catastrophic went wrong during processing
diff --git a/docs/eventlisteners.md b/docs/eventlisteners.md
@@ -31,7 +31,7 @@ using [Event Interceptors](#Interceptors).
   - [Annotations](#annotations)
   - [Interceptors](#interceptors)
     - [Webhook Interceptors](#webhook-interceptors)
-      - [Event Interceptor Services](#event-interceptor-services)
+      - [ Webhook Interceptor Services](#webhook-interceptor-services)
     - [GitHub Interceptors](#github-interceptors)
     - [GitLab Interceptors](#gitlab-interceptors)
     - [Bitbucket Interceptors](#bitbucket-interceptors)
@@ -406,10 +406,42 @@ by the annotations available in the eventlistener.
 ## Interceptors
 
 Triggers within an `EventListener` can optionally specify interceptors, to
-modify the behavior or payload of Triggers.
-
-Event Interceptors can take several different forms today:
-
+modify the behavior or payload of Triggers. With 
+[TEP-0026](https://github.com/tektoncd/community/blob/main/teps/0026-interceptor-plugins.md), users have a unified way 
+to configure all interceptors though we continue to support the old core and webhook interceptors as well.
+
+An interceptor consists of:
+- `name` - (Optional) a name to identify this interceptor configuration
+- `ref` - A reference to a ClusterInterceptor. At least, the `name` field must be specified while the `kind` and 
+  `apiVersion` fields are optional
+- `params` - (Optional) A list of `name` and `value` pairs. The `name` field is a string while the `value` can be any 
+   valid JSON object
+   
+As an example, see the snippet below:
+```yaml
+interceptors:
+    - name: "validate GitHub payload and filter on eventType"
+      ref:
+        name: "github"
+      params:
+      - name: "secretRef"
+        value:
+          secretName: github-secret
+          secretKey: secretToken
+      - name: "eventTypes"
+        value: ["pull_request"]
+    - name: "CEL filter: only when PRs are opened"
+      ref:
+        name: "cel"
+      params:
+      - name: "filter"
+        value: "body.action in ['opened', 'reopened']"
+```
+
+The following section describes the old and DEPRECATED way of configuring interceptors. While they continue to be 
+supported for now, they will be removed in a future release.
+
+Interceptors can take several different forms:
 - [Webhook Interceptors](#Webhook-Interceptors)
 - [GitHub Interceptors](#GitHub-Interceptors)
 - [GitLab Interceptors](#GitLab-Interceptors)
@@ -445,9 +477,9 @@ is the responsibility of Interceptors to preserve header/body data if desired.
 The response body and headers of the last Interceptor is used for resource
 binding/templating.
 
-#### Event Interceptor Services
+#### Webhook Interceptor Services
 
-To be an Event Interceptor, a Kubernetes object should:
+To be a valid Webhook Interceptor, a Kubernetes object should:
 
 - Be fronted by a regular Kubernetes v1 Service over port 80
 - Accept JSON payloads over HTTP
@@ -495,7 +527,6 @@ spec:
         ref: pipeline-template
 ```
 
-
 ### GitHub Interceptors
 
 GitHub Interceptors contain logic to validate and filter webhooks that come from
@@ -591,24 +622,28 @@ accept to the `eventTypes` field. Valid values can be found in Bitbucket
 The body/header of the incoming request will be preserved in this Interceptor's
 response.
 
-<!-- FILE: examples/bitbucket/bitbucket-eventlistener-interceptor.yaml -->
+<!-- FILE: examples/bitbucket/bitbucket-listener.yaml -->
 ```YAML
 ---
 apiVersion: triggers.tekton.dev/v1alpha1
 kind: EventListener
 metadata:
   name: bitbucket-listener
 spec:
-  serviceAccountName: tekton-triggers-bitbucket-sa
+  serviceAccountName: tekton-triggers-example-sa
   triggers:
     - name: bitbucket-triggers
       interceptors:
-        - bitbucket:
-            secretRef:
-              secretName: bitbucket-secret
-              secretKey: secretToken
-            eventTypes:
-              - repo:refs_changed
+        - ref:
+            name: "bitbucket"
+          params:
+            - name: secretRef
+              value:
+                secretName: bitbucket-secret
+                secretKey: secretToken
+            - name: eventTypes
+              value:
+                - repo:refs_changed
       bindings:
         - ref: bitbucket-binding
       template:
@@ -665,10 +700,13 @@ spec:
   triggers:
     - name: cel-trig
       interceptors:
-        - cel:
-            overlays:
-            - key: truncated_sha
-              expression: "body.pull_request.head.sha.truncate(7)"
+        - ref:
+            name: "cel"
+          params:
+            - name: "overlays"
+              value:
+                - key: extensions.truncated_sha
+                  expression: "body.pull_request.head.sha.truncate(7)"
       bindings:
       - ref: pipeline-binding
       template:

diff --git a/docs/triggers.md b/docs/triggers.md
@@ -34,11 +34,15 @@ 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)"
+    - ref:
+        name: "cel"
+      params:
+        - name: "filter"
+          value: "header.match('X-GitHub-Event', 'pull_request')"
+        - name: "overlays"
+          value:
+            - key: extensions.truncated_sha
+              expression: "body.pull_request.head.sha.truncate(7)"
   bindings:
   - ref: pipeline-binding
   template:

diff --git a/examples/bitbucket/bitbucket-eventlistener-interceptor.yaml b/examples/bitbucket/bitbucket-eventlistener-interceptor.yaml
diff --git a/examples/bitbucket/bitbucket-listener.yaml b/examples/bitbucket/bitbucket-listener.yaml
@@ -0,0 +1,24 @@
+---
+apiVersion: triggers.tekton.dev/v1alpha1
+kind: EventListener
+metadata:
+  name: bitbucket-listener
+spec:
+  serviceAccountName: tekton-triggers-example-sa
+  triggers:
+    - name: bitbucket-triggers
+      interceptors:
+        - ref:
+            name: "bitbucket"
+          params:
+            - name: secretRef
+              value:
+                secretName: bitbucket-secret
+                secretKey: secretToken
+            - name: eventTypes
+              value:
+                - repo:refs_changed
+      bindings:
+        - ref: bitbucket-binding
+      template:
+        ref: bitbucket-template
diff --git a/examples/custom-resource/github-knative-listener-customresource.yaml b/examples/custom-resource/github-knative-listener-customresource.yaml
@@ -7,14 +7,21 @@ spec:
   triggers:
     - name: github-listener
       interceptors:
-        - github:
-            secretRef:
-              secretName: github-secret
-              secretKey: secretToken
-            eventTypes:
-              - pull_request
-        - cel:
-            filter: "body.action in ['opened', 'synchronize', 'reopened']"
+        - ref:
+            name: "github"
+          params:
+            - name: "secretRef"
+              value:
+                secretName: github-secret
+                secretKey: secretToken
+            - name: "eventTypes"
+              value: ["pull_request"]
+        - name: "only when PRs are opened"
+          ref:
+            name: "cel"
+          params:
+            - name: "filter"
+              value: "body.action in ['opened', 'synchronize', 'reopened']"
       bindings:
         - ref: github-pr-binding
       template:

diff --git a/examples/eventlistener-tls-connection/tls-eventlistener-interceptor.yaml b/examples/eventlistener-tls-connection/tls-eventlistener-interceptor.yaml
@@ -7,14 +7,21 @@ spec:
   triggers:
     - name: tls-listener
       interceptors:
-        - github:
-            secretRef:
-              secretName: github-secret
-              secretKey: secretToken
-            eventTypes:
-              - pull_request
-        - cel:
-            filter: "body.action in ['opened', 'synchronize', 'reopened']"
+        - ref:
+            name: "github"
+          params:
+            - name: "secretRef"
+              value:
+                secretName: github-secret
+                secretKey: secretToken
+            - name: "eventTypes"
+              value: ["pull_request"]
+        - name: "only when PRs are opened"
+          ref:
+            name: "cel"
+          params:
+            - name: "filter"
+              value: "body.action in ['opened', 'synchronize', 'reopened']"
       bindings:
         - ref: tls-pr-binding
       template:

diff --git a/examples/eventlisteners/cel-eventlistener-interceptor-with-secret.yaml b/examples/eventlisteners/cel-eventlistener-interceptor-with-secret.yaml
@@ -15,8 +15,11 @@ spec:
   triggers:
     - name: cel-trig-with-matches
       interceptors:
-        - cel:
-            filter: "'test-secret'.compareSecret('token', 'mysecret')"
+      - ref:
+          name: "cel"
+        params:
+        - name: "filter"
+          value: "'test-secret'.compareSecret('token', 'mysecret')"
       bindings:
       - ref: pipeline-binding
       template:

diff --git a/examples/eventlisteners/cel-eventlistener-interceptor.yaml b/examples/eventlisteners/cel-eventlistener-interceptor.yaml
@@ -7,11 +7,15 @@ spec:
   triggers:
     - name: cel-trig-with-matches
       interceptors:
-        - cel:
-            filter: "header.match('X-GitHub-Event', 'pull_request')"
-            overlays:
-            - key: truncated_sha
-              expression: "body.pull_request.head.sha.truncate(7)"
+        - ref:
+            name: "cel"
+          params:
+            - name: "filter"
+              value: "header.match('X-GitHub-Event', 'pull_request')"
+            - name: "overlays"
+              value:
+                - key: truncated_sha
+                  expression: "body.pull_request.head.sha.truncate(7)"
       bindings:
       - name: sha
         value: $(extensions.truncated_sha)

diff --git a/examples/eventlisteners/cel-eventlistener-multiple-overlays.yaml b/examples/eventlisteners/cel-eventlistener-multiple-overlays.yaml
@@ -7,12 +7,15 @@ spec:
   triggers:
     - name: cel-trig
       interceptors:
-        - cel:
-            overlays:
-            - key: truncated_sha
-              expression: "body.pull_request.head.sha.truncate(7)"
-            - key: branch_name
-              expression: "body.ref.split('/')[2]"
+        - ref:
+            name: "cel"
+          params:
+            - name: "overlays"
+              value:
+                - key: truncated_sha
+                  expression: "body.pull_request.head.sha.truncate(7)"
+                - key: branch_name
+                  expression: "body.ref.split('/')[2]"
       bindings:
       - name: sha
         value: $(extensions.truncated_sha)

diff --git a/examples/eventlisteners/cel-eventlistener-no-filter.yaml b/examples/eventlisteners/cel-eventlistener-no-filter.yaml
@@ -7,10 +7,13 @@ spec:
   triggers:
     - name: cel-trig
       interceptors:
-        - cel:
-            overlays:
-            - key: truncated_sha
-              expression: "body.pull_request.head.sha.truncate(7)"
+        - ref:
+            name: "cel"
+          params:
+            - name: "overlays"
+              value:
+                - key: extensions.truncated_sha
+                  expression: "body.pull_request.head.sha.truncate(7)"
       bindings:
       - ref: pipeline-binding
       template:

diff --git a/examples/eventlisteners/eventlistener-multiinterceptor.yaml b/examples/eventlisteners/eventlistener-multiinterceptor.yaml
@@ -8,12 +8,15 @@ spec:
   triggers:
     - name: foo-trig
       interceptors:
-        - github:
-            secretRef:
+        - ref:
+            name: "github"
+          params:
+          - name: "secretRef"
+            value:
               secretName: foo
               secretKey: bar
-            eventTypes:
-              - pull_request
+          - name: "eventTypes"
+            value: ["pull_request"]
         - webhook:
             header:
               - name: Foo-Trig-Header1