eventlisteners.md

EventListener

EventListeners connect TriggerBindings to TriggerTemplates and provide an addressable endpoint, which is where webhooks/events are directed. This is also where the service account is connected, which specifies what permissions the resources will be created (or at least attempted) with. The service account must have the following role bound.

kind: Role
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: tekton-triggers-example-minimal
rules:
# Permissions for every EventListener deployment to function
- apiGroups: ["tekton.dev"]
  resources: ["eventlisteners", "triggerbindings", "triggertemplates", "tasks", "taskruns"]
  verbs: ["get"]
- apiGroups: [""]
  resources: ["configmaps"]
  verbs: ["get", "list", "watch"]
# Permissions to create resources in associated TriggerTemplates
- apiGroups: ["tekton.dev"]
  resources: ["pipelineruns", "pipelineresources", "taskruns"]
  verbs: ["create"]

Note that currently, JSON is the only accepted MIME type for events.

When an EventListener is successfully created, a service is created that references a listener pod. This listener pod accepts the incoming events and does what has been specified in the corresponding TriggerBindings/TriggerTemplates. The created service is by default of type ClusterIP; any other pods running in the same Kubernetes cluster can access services' via their cluster DNS. For external services to connect to your cluster (e.g. GitHub sending webhooks), check out the guide on exposing eventlisteners

When the EventListener is created in the different namespace from the trigger component, config-logging-triggers ConfigMap is created for the logging configuration in the namespace when it doesn't exist. The ConfigMap with the default configuration can be created by applying config-logging.yaml

EventListener spec.serviceType can be set to ClusterIP (default) | NodePort | LoadBalancer to configure the underlying Service resource to make it reachable externally.

Autogenerated labels

By default, EventListeners will attach the following labels automatically to all resources created:

Name	Description
tekton.dev/eventlistener	Name of the EventListener that generated the resource.
tekton.dev/trigger	Name of the trigger that generated the resource.
tekton.dev/eventid	UID of the incoming event.

Event Interceptors

Triggers within an EventListener can optionally specify an interceptor field.

Event Interceptors can take several different forms today:

• Webhook Interceptors
• GitHub Interceptors
• GitLab Interceptors

Webhook Interceptors

Webhook interceptors allow users to configure an external k8s object which contains business logic. These are currently specified under the Webhook field, which contains an ObjectReference to a Kubernetes Service. If a Webhook interceptor is specified, the EventListener sink will forward incoming events to the service referenced by the interceptor over HTTP. The service is expected to process the event and return a response back. The status code of the response determines if the processing is successful and the returned body is used as the new event payload by the EventListener and passed on the TriggerBinding. An interceptor has an optional header field with key-value pairs that will be merged with event headers before being sent; canonical names must be specified.

Event Interceptor Services

To be an Event Interceptor, a Kubernetes object should:

• Be fronted by a regular Kubernetes v1 Service over port 80
• Accept JSON payloads over HTTP
• Return a HTTP 200 OK Status if the EventListener should continue processing the event
• Return a JSON body back. This will be used by the EventListener as the event payload for any further processing. If the interceptor does not need to modify the body, it can simply return the body that it received.

apiVersion: tekton.dev/v1alpha1
kind: EventListener
metadata:
  name: listener-interceptor
spec:
  serviceAccountName: tekton-triggers-example-sa
  triggers:
    - name: foo-trig
      interceptor:
        webhook:
          header:
          - name: Foo-Trig-Header1
            value: string-value
          - name: Foo-Trig-Header2
            value:
            - array-val1
            - array-val2
          objectRef:
            kind: Service
            name: gh-validate
            apiVersion: v1
            namespace: default
      bindings:
      - name: pipeline-binding
      template:
        name: pipeline-template

GitHub Interceptors

GitHub interceptors contain logic to validate and filter webhooks that come from GitHub. Supported features include validating webhooks actually came rom GitHub using the logic outlined in GitHub documentation, as well as filtering incoming events.

To use this interceptor as a validator, create a secret string using the method of your choice, and configure the GitHub webhook to use that secret value. Create a Kubernetes secret containing this value, and pass that as a reference to the github interceptor.

To use this interceptor as a filter, add the event types you would like to accept to the eventTypes field. Valid values can be found in Github docs.

apiVersion: tekton.dev/v1alpha1
kind: EventListener
metadata:
  name: github-listener-interceptor
spec:
  serviceAccountName: tekton-triggers-example-sa
  triggers:
    - name: foo-trig
      interceptor:
        github:
          secretRef:
            secretName: foo
            secretKey: bar
            namespace: baz
          eventTypes:
          - pull_request
      bindings:
      - name: pipeline-binding
      template:
        name: pipeline-template

GitLab Interceptors

GitLab interceptors contain logic to validate that a webhook actually came from Gitlab, using the logic outlined in GitLab documentation.

To use this interceptor, create a secret string using the method of your choice, and configure the Gitlab webhook to use that secret value. Create a Kubernetes secret containing this value, and pass that as a reference to the gitlab interceptor:

apiVersion: tekton.dev/v1alpha1
kind: EventListener
metadata:
  name: gitlab-listener-interceptor
spec:
  serviceAccountName: tekton-triggers-example-sa
  triggers:
    - name: foo-trig
      interceptor:
        gitlab:
          secretRef:
            secretName: foo
            secretKey: bar
            namespace: baz
      bindings:
      - name: pipeline-binding
      template:
        name: pipeline-template