Merge pull request #45 from hibell/migrate-from-webhooks-ext

Add info on migrating from Tekton webhooks extension.
kabanero-io · May 27, 2020 · b6ac209 · b6ac209
2 parents 61df5b8 + ed6862a
commit b6ac209
Show file tree

Hide file tree

Showing 6 changed files with 515 additions and 6 deletions.
diff --git a/README.md b/README.md
@@ -7,6 +7,7 @@
 - [Webhook Processing](#webhook-processing)
 - [Kabanero Integration](#kabanero-integration)
 - [Tech Preview](#tech-preview)
+- [Migrating from Tekton Webhooks Extension](#migrating-from-tekton-webhooks-extension)
 
 <a name="introduction"></a>
 ## Introduction
@@ -869,9 +870,9 @@ mediation. It verifies the url pattern of the webhook request, the github secret
 allows it to associate the webhook event with the mediation `appsody`.
 
 The event mediator applies additional logic for appsody projects. First, it finds the best matching active stack by
-matching its `.spec.images[i].name` to the stack name as defined in `appsody-config.yaml`. 
-It uses `.spec.images[i].version` to find the best semantically matched version. 
-It uses `.status` to ensure that the version is active. 
+matching its `.spec.images[i].name` to the stack name as defined in `appsody-config.yaml`.
+It uses `.spec.images[i].version` to find the best semantically matched version.
+It uses `.status` to ensure that the version is active.
 It creates the variable `message.body.webhooks-kabanero-tekton-listener` to be `listener-12345678`.
 
 It also creates all the default variables and user defined variables to be passed downstream to the Tekton event
@@ -882,7 +883,7 @@ When sending the message downstream, the URL as defined in the EventConnection i
 
 The Tekton event listener is configured to trigger the correct pipeline based on input parameters.
 For the example below, there is a separate pipeline called depending on whether it is a push or pull request.
-In addition, a separate monitor task is created when the event mediator decides. 
+In addition, a separate monitor task is created when the event mediator decides.
 
 ```yaml
 apiVersion: tekton.dev/v1alpha1
@@ -1045,7 +1046,6 @@ Note that:
 
 - the function `eventListenerURL` resolves to the URL of a configured Tekton event listener. For the gitops mediation, it resolves to the Tekton event listener named `deploy-kustomize-listener`, which is used to drive a deployment pipeline.
 
-
 #### Using the Gitops Pipeline
 
 - You update the master branch of your your application.
@@ -1054,4 +1054,308 @@ Note that:
 - If the build is successful, a new pull request is created automatically in your gitops repository.
 - You review and merge the pull request.
 - A new deployment pipeline is automatically triggered.
-- if the deployment succeeds, an AppsodyApplication is automatically created or updated in the same namespace as the build.
+- if the deployment succeeds, an AppsodyApplication is automatically created or updated in the same namespace as the
+  build.
+
+## Migrating from Tekton Webhooks Extension
+
+If you are already using the Tekton Webhooks extension, and you would like to continue to use your existing pipelines
+with Kabanero Events, you can do so by creating a passthrough mediation. The passthrough mediation will pass any events
+it receives to the configured EventListener.
+
+The steps to use an existing pipeline with the webhook mediator is as follows:
+
+1. Apply the `monitor-task-binding.yaml` and `event-trigger-binding.yaml` TriggerBindings.
+2. Create an internal `EventListener` to route traffic to the existing pipelines. See below for an example
+   EventListener. Note that the EventListener should be applied in same namespace as the webhook extension (i.e.
+   `tekton-pipelines`).
+3. Create a webhook mediator that passes events through to the `EventListener`.
+4. Remove the existing webhook configuration created by Tekton Webhooks extension from your project on Github
+5. Configure a webhook at either the organization level or the project level in Github to call the webhook mediator.
+
+### Setting up the EventListener
+
+A few `TriggerBindings` need to be applied to be able to use your existing Tekton triggers created by the Tekton
+webhooks extension. Run the following two commands to create these resources:
+
+```shell
+cat <<'EOF' | kubectl apply -n tekton-pipelines -f -
+apiVersion: triggers.tekton.dev/v1alpha1
+kind: TriggerBinding
+metadata:
+  name: kabanero-events-webhook-trigger-binding
+spec:
+  params:
+  - name: webhooks-tekton-release-name
+    value: "$(body.webhooks-tekton-release-name)"
+  - name: webhooks-tekton-target-namespace
+    value: "$(body.webhooks-tekton-target-namespace)"
+  - name: webhooks-tekton-service-account
+    value: "$(body.webhooks-tekton-service-account)"
+  - name: webhooks-tekton-git-server
+    value: "$(body.webhooks-tekton-git-server)"
+  - name: webhooks-tekton-git-org
+    value: "$(body.webhooks-tekton-git-org)"
+  - name: webhooks-tekton-git-repo
+    value: "$(body.webhooks-tekton-git-repo)"
+  - name: webhooks-tekton-pull-task
+    value: "$(body.webhooks-tekton-pull-task)"
+  - name: webhooks-tekton-ssl-verify
+    value: "$(body.webhooks-tekton-ssl-verify)"
+  - name: webhooks-tekton-insecure-skip-tls-verify
+    value: "$(body.webhooks-tekton-insecure-skip-tls-verify)"
+  - name: webhooks-tekton-docker-registry
+    value: "$(body.webhooks-tekton-docker-registry)"
+EOF
+```
+
+```shell
+cat <<'EOF' | kubectl apply -n tekton-pipelines -f -
+apiVersion: triggers.tekton.dev/v1alpha1
+kind: TriggerBinding
+metadata:
+  name: kabanero-events-monitor-task-binding
+spec:
+  params:
+  - name: commentsuccess
+    value: $(body.commentsuccess)
+  - name: commentfailure
+    value: $(body.commentfailure)
+  - name: commenttimeout
+    value: $(body.commenttimeout)
+  - name: commentmissing
+    value: $(body.commentmissing)
+  - name: gitsecretname
+    value: $(body.gitsecretname)
+  - name: gitsecretkeyname
+    value: $(body.gitsecretkeyname)
+  - name: dashboardurl
+    value: $(body.dashboardurl)
+  - name: insecure-skip-tls-verify
+    value: $(body.webhooks-tekton-insecure-skip-tls-verify)
+  - name: provider
+    value: $(body.provider)
+  - name: apiurl
+    value: $(body.apiurl)
+EOF
+```
+
+The internal EventListener that the mediator will forward events to can now be created. The example EventListener
+configuration demonstrates how to set up an EventListener that processes GitHub `push` and `pull_request` events for two
+stacks: `java-openliberty` and `nodejs-express`. Push and pull requests events that are handled will cause the
+appropriate `build-push` pipeline to be executed.
+
+```yaml
+apiVersion: triggers.tekton.dev/v1alpha1
+kind: EventListener
+metadata:
+  name: kabanero-event-listener
+  namespace: tekton-pipelines
+spec:
+  serviceAccountName: tekton-webhooks-extension-eventlistener
+  triggers:
+  - name: kabanero-ol-push-event
+    interceptors:
+    - cel:
+        filter: 'body["webhooks-appsody-config"]["stack"].contains("java-openliberty:") && body["webhooks-tekton-event-type"] == "push" && body["webhooks-tekton-git-branch"] == "master"'
+    template:
+      apiVersion: v1alpha1
+      name: java-openliberty-build-push-pl-template
+    bindings:
+    - apiversion: v1alpha1
+      kind: TriggerBinding
+      name: java-openliberty-build-push-pl-push-binding
+    - apiversion: v1alpha1
+      kind: TriggerBinding
+      name: kabanero-events-webhook-trigger-binding
+  - name: kabanero-ol-pullrequest-event
+    interceptors:
+    - cel:
+        filter: 'body["webhooks-appsody-config"]["stack"].contains("java-openliberty:") && body["webhooks-tekton-event-type"] == "pull_request" && body["webhooks-tekton-git-branch"] != "master" && (body["action"] == "opened" || body["action"] == "synchronize")'
+    template:
+      apiVersion: v1alpha1
+      name: java-openliberty-build-push-pl-template
+    bindings:
+    - apiversion: v1alpha1
+      kind: TriggerBinding
+      name: java-openliberty-build-push-pl-pullrequest-binding
+    - apiversion: v1alpha1
+      kind: TriggerBinding
+      name: kabanero-events-webhook-trigger-binding
+  - name: kabanero-nodejs-express-push-event
+    interceptors:
+    - cel:
+        filter: 'body["webhooks-appsody-config"]["stack"].contains("nodejs-express:") && body["webhooks-tekton-event-type"] == "push" && body["webhooks-tekton-git-branch"] == "master"'
+    template:
+      apiVersion: v1alpha1
+      name: nodejs-express-build-push-pl-template
+    bindings:
+    - apiversion: v1alpha1
+      kind: TriggerBinding
+      name: nodejs-express-build-push-pl-push-binding
+    - apiversion: v1alpha1
+      kind: TriggerBinding
+      name: kabanero-events-webhook-trigger-binding
+  - name: kabanero-nodejs-express-pullrequest-event
+    interceptors:
+    - cel:
+        filter: 'body["webhooks-appsody-config"]["stack"].contains("nodejs-express:") && body["webhooks-tekton-event-type"] == "pull_request" && body["webhooks-tekton-git-branch"] != "master" && (body["action"] == "opened" || body["action"] == "synchronize")'
+    template:
+      apiVersion: v1alpha1
+      name: nodejs-express-build-push-pl-template
+    bindings:
+    - apiversion: v1alpha1
+      kind: TriggerBinding
+      name: nodejs-express-build-push-pl-pullrequest-binding
+    - apiversion: v1alpha1
+      kind: TriggerBinding
+      name: kabanero-events-webhook-trigger-binding
+  - name: kabanero-monitor-task-event
+    interceptors:
+    - cel:
+        filter: 'body["webhooks-tekton-event-type"] == "pull_request" && body["webhooks-tekton-git-branch"] != "master" && (body["action"] == "opened" || body["action"] == "synchronize")'
+    template:
+      apiversion: v1alpha1
+      name: monitor-task-template
+    bindings:
+    - apiversion: v1alpha1
+      kind: TriggerBinding
+      name: monitor-task-github-binding
+    - apiversion: v1alpha1
+      kind: TriggerBinding
+      name: kabanero-events-monitor-task-binding
+```
+
+The example `EventListener` can be modified for whichever pipelines you would like to execute based on the stack and
+event that is handled. The `TriggerTemplate`s and `TriggerBindings` needed can be determined by inspecting your current
+Webhooks extension `EventListener`:
+
+```shell
+$ oc get el <the-eventlistener-being-migrated> -o yaml | less
+...
+```
+
+Note that any `TriggerBindings` prefixed with `wext-` do not need to be added since you already applied the replacement
+`TriggerBinding`s above.
+
+Once you are finished creating the replacement EventListener, it should be applied to the `tekton-pipelines` namespaces
+like so:
+
+```
+$ oc apply -f kabanero-event-listener.yaml -n tekton-pipelines
+```
+
+### Setting up the Passthrough Event Mediation
+
+To setup a passthrough event mediation, first set up the connections to route from the mediation to the EventListener
+created in the previous step:
+
+```yaml
+apiVersion: events.kabanero.io/v1alpha1
+kind: EventConnections
+metadata:
+  name: example-connections
+spec:
+  connections:
+    - from: 
+        mediator:
+            name: example-webhook-mediator
+            mediation: example-webhook
+            destination: dest
+      to:
+        - https:
+            - url: "http://el-<name-of-the-event-listener-created-above>.tekton-pipelines.svc.cluster.local:8080"
+              insecure: true
+```
+
+The passthrough webhook mediation should then look like:
+
+```yaml
+apiVersion: events.kabanero.io/v1alpha1
+kind: EventMediator
+metadata:
+  name: example-webhook-mediator
+spec:
+  createListener: true
+  createRoute: true
+  repositories:
+    - github:
+        secret: ghe-https-secret
+        webhookSecret: ghe-webhook-secret
+  mediations:
+    - name: example-webhook
+      selector:
+        repositoryType:
+          newVariable: body.webhooks-appsody-config
+          file: .appsody-config.yaml
+      variables:
+        - name: body.webhooks-tekton-target-namespace
+          value: kabanero
+        - name: body.webhooks-tekton-service-account
+          value: kabanero-pipeline
+        # body.webhooks-tekton-docker-registry is docker registry you want; e.g. `docker.io/<your-dockerhub-user-name>`
+        - name: body.webhooks-tekton-docker-registry
+          value: <your-docker-registry>
+        - name: body.webhooks-tekton-ssl-verify
+          value: "false"
+        - name: body.webhooks-tekton-insecure-skip-tls-verify
+          value: "true"
+        - name: body.webhooks-tekton-local-deploy
+          value: "false"
+        - name: body.webhooks-tekton-monitor-dashboard-url
+          value: "https://tekton-dashboard-tekton-pipelines.apps.<your-domain>/#/pipelineruns"
+        # Additional values needed by the webhooks extension TriggerBindings
+        - name: body.webhooks-tekton-release-name
+          valueExpression: 'body["webhooks-tekton-git-repo"]'
+        - name: body.webhooks-tekton-pull-task
+          value: monitor-task
+        # Values needed by the monitor task.
+        - name: body.commentsuccess
+          value: Success
+        - name: body.commentfailure
+          value: Failed
+        - name: body.commenttimeout
+          value: Unknown
+        - name: body.commentmissing
+          value: Missing
+        - name: body.gitsecretname
+          valueExpression: 'body["webhooks-tekton-github-secret-name"]'
+        - name: body.gitsecretkeyname
+          valueExpression: 'body["webhooks-tekton-github-secret-key-name"]'
+        - name: body.dashboardurl
+          value: tekton-dashboard-tekton-pipelines.apps.<your-domain>
+        - name: body.provider
+          value: github
+        - name: body.apiurl
+          value: https://<github-url>/api/v3/
+      sendTo: [ "dest"  ]
+      body:
+        - = : "sendEvent(dest, body, header)"
+```
+
+Set the values to the variables as needed, particularly those whose values enclosed within `<>`. These values can be
+determined by looking at the `wext-` trigger binding that the Webhooks extension created for your `EventListener`.
+Afterwards, apply both the connections and webhook mediation YAML to the `kabanero` namespace.
+
+### Configuring the Webhook
+
+The webhook that calls the webhook mediator can be configured at the project level or at the organization level. The
+Tekton webhooks extension only supported project-level webhooks, but Kabanero events also supports webhooks at the
+organization level. An organization-level webhook is suggested to save users from having to configure a webhook for
+each repository.
+
+The webhook should be created with the following information:
+
+- **Payload URL**: `https://example-webhook-mediator-kabanero.apps.mydomain.com/`. Note that the route can be determined
+  using
+
+  ```shell
+  $ oc get route -n kabanero
+  ...
+  ```
+
+- **Content type**: `application/json`
+- **Secret**: Your webhook secret (optional, but recommended).
+- **SSL verification**: Enable SSL verification (recommended), but this requires that your OpenShift certificate to 
+  be trusted
+- **Which events would you like to trigger this webhook?**: Send me **everything**.
diff --git a/sample_crds/tekton_webhooks_migration/connections.yaml b/sample_crds/tekton_webhooks_migration/connections.yaml
@@ -0,0 +1,15 @@
+apiVersion: events.kabanero.io/v1alpha1
+kind: EventConnections
+metadata:
+  name: example-connections
+spec:
+  connections:
+    - from: 
+        mediator:
+            name: example-webhook-mediator
+            mediation: example-webhook
+            destination: dest
+      to:
+        - https:
+            - url: "http://el-kabanero-event-listener.tekton-pipelines.svc.cluster.local:8080"
+              insecure: true
diff --git a/sample_crds/tekton_webhooks_migration/event-trigger-binding.yaml b/sample_crds/tekton_webhooks_migration/event-trigger-binding.yaml
@@ -0,0 +1,26 @@
+apiVersion: triggers.tekton.dev/v1alpha1
+kind: TriggerBinding
+metadata:
+  name: kabanero-events-webhook-trigger-binding
+spec:
+  params:
+  - name: webhooks-tekton-release-name
+    value: $(body.webhooks-tekton-release-name)
+  - name: webhooks-tekton-target-namespace
+    value: $(body.webhooks-tekton-target-namespace)
+  - name: webhooks-tekton-service-account
+    value: $(body.webhooks-tekton-service-account)
+  - name: webhooks-tekton-git-server
+    value: $(body.webhooks-tekton-git-server)
+  - name: webhooks-tekton-git-org
+    value: $(body.webhooks-tekton-git-org)
+  - name: webhooks-tekton-git-repo
+    value: $(body.webhooks-tekton-git-repo)
+  - name: webhooks-tekton-pull-task
+    value: $(body.webhooks-tekton-pull-task)
+  - name: webhooks-tekton-ssl-verify
+    value: $(body.webhooks-tekton-ssl-verify)
+  - name: webhooks-tekton-insecure-skip-tls-verify
+    value: $(body.webhooks-tekton-insecure-skip-tls-verify)
+  - name: webhooks-tekton-docker-registry
+    value: $(body.webhooks-tekton-docker-registry)