#Setup EventListener

#What This Document Helps You Do

This document helps you configure and deploy an EventListener to receive webhook events from external systems (such as GitHub, GitLab, or custom webhooks) and automatically trigger your Tekton pipelines. You will learn:

• How to create and configure an EventListener resource
• How to expose EventListener to external systems (using Ingress, LoadBalancer, or NodePort)
• How to configure permissions and security settings
• How to choose the right deployment strategy based on your environment

Prerequisites: You should have basic knowledge of Tekton Pipelines and Kubernetes concepts. If you're new to EventListener concepts, we recommend reading the In-Depth Understanding of EventListener document first.

#Overview

EventListener is a core resource in Tekton Triggers, responsible for receiving and processing external events (such as Webhooks). When an external system triggers an event, the EventListener creates Kubernetes resources (such as PipelineRun) based on the configured triggers.

#Key Features

EventListener has the following key features:

• Event Listening: Provides an HTTP endpoint to receive Webhook events from external systems
• Event Filtering: Validates and filters received events using interceptors
• Resource Creation: Automatically creates Kubernetes resources based on trigger definitions
• Extensibility: Supports custom interceptors and various event sources
• Security: Built-in multiple security mechanisms such as Webhook validation

#Configuration Instructions

#Basic Structure

apiVersion: triggers.tekton.dev/v1beta1
kind: EventListener
metadata:
  name: eventlistener
spec:
  serviceAccountName: triggers-default-sa
  resources:
    kubernetesResource:
      serviceType: NodePort  # Service type
      servicePort: 80       # Service port
      spec:
        template:
          spec:
            containers:
              - resources:    # Resource limits
                  requests:
                    memory: "64Mi"
                    cpu: "250m"
                  limits:
                    memory: "128Mi"
                    cpu: "500m"
  triggers:                  # Trigger configuration
    - name: trigger-1       # Trigger name
      interceptors:         # Interceptor configuration
        - ref:
            name: "cel"
          params:
            - name: "filter"
              value: "header.match('X-GitHub-Event', 'pull_request')"
      bindings:            # Trigger bindings
        - ref: pipeline-binding
      template:            # Trigger template
        ref: pipeline-template

#Main Field Descriptions

#spec.resources.kubernetesResource

Used to configure the Kubernetes resources for the EventListener:

• serviceType: Service type (NodePort/ClusterIP/LoadBalancer)
• servicePort: Service port
• spec: Pod template configuration

#spec.triggers

Defines a set of trigger configurations:

• name: Trigger name
• interceptors: List of interceptor configurations
• bindings: Trigger binding configurations
• template: Trigger template configurations

#Security Configurations

EventListener supports multiple security configurations:

1. ServiceAccount:
   • Default ServiceAccount (triggers-default-sa): If spec.serviceAccountName is not specified, EventListener will automatically use the triggers-default-sa ServiceAccount in the namespace. This ServiceAccount is automatically granted the necessary namespace-scoped permissions required for EventListeners to handle triggers within the same namespace. The permissions are automatically bound to the namespace where the ServiceAccount exists.
   • Custom ServiceAccount: When you need to handle triggers across multiple namespaces (e.g., when namespaceSelector is configured), you must specify a custom ServiceAccount with cluster-scoped permissions. Ensure that the specified ServiceAccount is configured with the corresponding permissions (see Permission Guidelines below).
2. Interceptor Validation: Use CEL interceptors for event validation.
3. TLS: Supports configuring HTTPS certificates.

#Permission Guidelines

#Default ServiceAccount vs Custom ServiceAccount

• Default ServiceAccount (triggers-default-sa): When spec.serviceAccountName is not specified, EventListener automatically uses the triggers-default-sa ServiceAccount in the namespace. This ServiceAccount is automatically granted the necessary namespace-scoped permissions required for EventListeners to handle triggers within the same namespace. The permissions are automatically bound to the namespace where the ServiceAccount exists, so you don't need to manually configure Role or RoleBinding.

• Custom ServiceAccount with Cluster Permissions: When you configure namespaceSelector to listen to triggers from multiple namespaces (including '*' for all namespaces), you must specify a custom ServiceAccount with cluster-scoped permissions. The triggers-default-sa ServiceAccount only has namespace-scoped permissions and does not have the necessary cluster-scoped permissions to access resources across namespaces.

#Required Permissions

To trigger pipeline and tasks properly, the ServiceAccount used by EventListener needs the following permissions:

Referable ClusterRole:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: eventlistener-role
rules:
- apiGroups: [""]
  resources: ["configmaps", "secrets", "serviceaccounts"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["apps"]
  resources: ["deployments"]
  verbs: ["create", "get", "list", "watch", "patch", "update"]
- apiGroups: [""]
  resources: ["services", "pods", "events"]
  verbs: ["create", "get", "list", "watch", "patch", "update"]
- apiGroups: ["tekton.dev"]
  resources: ["pipelineruns", "taskruns"]
  verbs: ["create"]
- apiGroups: ["triggers.tekton.dev"]
  resources:
    - "clustertriggerbindings"
    - "triggerbindings"
    - "clusterinterceptors"
    - "interceptors"
    - "triggers"
    - "triggertemplates"
    - "eventlisteners"
  verbs: ["get", "list", "watch"]

#User Guide

Deploying the EventListener needs to be planned according to the scale and the actual network situation of the environment, as described below on how to configure differently based on planning:

#EventListener Trigger Configuration Scenarios

EventListener supports three different scenarios for configuring triggers, each suitable for different use cases:

#1. Namespace-Level EventListener

A namespace-level EventListener binds to specific triggers within the same namespace by explicitly configuring the triggers field in the EventListener spec. This is the simplest scenario and is suitable for single-namespace deployments.

Use Cases and Recommendations:

• Use Cases:

  • Independent deployment and management for a single project or team
  • Requires explicit resource isolation and permission control
  • Teams have in-depth understanding of EventListener configuration and need fine-grained control over each trigger
  • Different namespaces require different EventListener configurations or resource limits
  • High requirements for performance and fault isolation

• Recommended For:

  • Experienced DevOps teams or scenarios requiring high customization
  • When different projects need different EventListener configurations, resource quotas, or security policies
  • Multi-tenant environments requiring complete isolation between tenants
  • When different namespaces need different replica counts, resource limits, or network policies

Example Configuration:

spec:
  # serviceAccountName is optional, defaults to triggers-default-sa
  triggers:
    - name: trigger-1
      bindings:
        - ref: gitlab-push
          kind: ClusterTriggerBinding
      template:
        ref: pipeline-template
    - name: trigger-2
      bindings:
        - ref: github-pullrequest
          kind: ClusterTriggerBinding
      template:
        ref: pipeline-template

#2. Project-Level EventListener

A project-level EventListener uses namespaceSelector to bind to triggers across multiple specified namespaces. This is suitable for managing triggers across a set of related namespaces (e.g., a project or team).

Use Cases and Recommendations:

• Use Cases:

  • Multiple related projects or namespaces need to share the same EventListener
  • Unified event handling at the project group or department level
  • Need to share resources across multiple namespaces without covering the entire cluster
  • Some performance isolation requirements, but can accept resource sharing within the project group

• Recommended For:

  • Medium-sized teams or project groups that need unified trigger management across multiple related namespaces
  • When multiple projects use similar configurations and resource requirements, reducing operational costs
  • When centralized management of Webhook events for a group of related projects is needed
  • Teams with some understanding of EventListener who can configure and manage cross-namespace permissions

Example Configuration:

spec:
  serviceAccountName: eventlistener  # Custom SA with cluster permissions
  namespaceSelector:
    matchNames:
      - project-a
      - project-b
      - project-c

#3. Global-Level EventListener

A global-level EventListener uses namespaceSelector with a wildcard ('*') to bind to triggers from all namespaces in the cluster. This is suitable for centralized event handling across the entire cluster.

Use Cases and Recommendations:

• Use Cases:

  • Cluster-wide unified event processing and management
  • Users have no strict requirements for performance isolation and can accept resource sharing
  • One-time configuration enables all users to use it out-of-the-box without separate configuration in each namespace
  • Users don't need in-depth knowledge of EventListener, managed uniformly by the platform
  • Small to medium-sized clusters with relatively controllable event volumes

• Recommended For:

  • Platform scenarios where platform administrators configure and manage uniformly
  • When cluster scale is small and all users need to use the same EventListener configuration
  • Simplifying user workflows and reducing learning costs and configuration complexity
  • Centralized operational management for unified monitoring and troubleshooting
  • Note: In large-scale clusters or high-concurrency scenarios, performance impact and fault isolation should be considered

Example Configuration:

spec:
  serviceAccountName: eventlistener  # Custom SA with cluster permissions
  namespaceSelector:
    matchNames:
      - '*'  # Wildcard for all namespaces

Comparison Table:

#Scale

In different planning scenarios, different configurations can be used to meet varying requirements.

#Network Configuration

Depending on the priority of the environment and the available network resources, different network configurations can be chosen.

#NodePort Configuration Example

NodePort is suitable for development, testing, or environments where you don't have a LoadBalancer or Ingress controller configured. This method exposes the EventListener service on a high port (30000-32767) on each node in the cluster.

#Prerequisites

• Kubernetes cluster with nodes accessible from external systems
• You should know at least one node's external IP address
• Firewall rules should allow traffic to the NodePort range (30000-32767)

#Configuration Example

apiVersion: triggers.tekton.dev/v1beta1
kind: EventListener
metadata:
  name: el-demo
  namespace: tekton-triggers-demo
spec:
  # serviceAccountName is optional, defaults to triggers-default-sa
  serviceAccountName: triggers-default-sa
  resources:
    kubernetesResource:
      serviceType: NodePort  # Use NodePort service type
      servicePort: 80        # Container port
  triggers:
    - name: hello-trigger
      bindings:
        - ref: hello-binding
      template:
        ref: hello-template

kubectl apply -f eventlistener-nodeport.yaml

# 1. Get the NodePort assigned to the EventListener service
# Replace 'el-el-demo' with your actual service name (format: el-<eventlistener-name>)
# Replace 'tekton-triggers-demo' with your namespace
export NODEPORT=$(kubectl get svc el-el-demo -n tekton-triggers-demo -o jsonpath='{.spec.ports[0].nodePort}')
echo "NodePort: $NODEPORT"

# 2. Get a node's external IP address
# This gets the first node's external IP, you can also use internal IP if nodes are not directly accessible
export NODE_IP=$(kubectl get nodes -o jsonpath='{.items[0].status.addresses[?(@.type=="ExternalIP")].address}')

# If no ExternalIP, try InternalIP
if [ -z "$NODE_IP" ]; then
  export NODE_IP=$(kubectl get nodes -o jsonpath='{.items[0].status.addresses[?(@.type=="InternalIP")].address}')
fi
echo "Node IP: $NODE_IP"

# 3. Construct the webhook URL
export WEBHOOK_URL="http://${NODE_IP}:${NODEPORT}"
echo "Webhook URL: $WEBHOOK_URL"

# Get NodePort
NODEPORT=$(kubectl get svc el-el-demo -n tekton-triggers-demo -o jsonpath='{.spec.ports[0].nodePort}')

# Get all node external IPs
kubectl get nodes -o jsonpath='{range .items[*]}{.status.addresses[?(@.type=="ExternalIP")].address}{"\n"}{end}'

# Or get internal IPs if external IPs are not available
kubectl get nodes -o jsonpath='{range .items[*]}{.status.addresses[?(@.type=="InternalIP")].address}{"\n"}{end}'

# Test the webhook endpoint
curl -v -X POST -H 'Content-Type: application/json' \
  -d '{"message":"Hello from NodePort!"}' \
  $WEBHOOK_URL

# Check EventListener is ready
kubectl get eventlistener el-demo -n tekton-triggers-demo

# Check the service
kubectl get svc el-el-demo -n tekton-triggers-demo

# View EventListener Pod logs
kubectl logs -n tekton-triggers-demo -l app=el-el-demo

#Important Notes for NodePort

• Security: NodePort uses HTTP (not HTTPS), so it's not suitable for production environments where security is critical
• Accessibility: The node IP must be accessible from external systems that will send webhooks
• High Availability: If a node goes down, you'll need to use a different node's IP. Consider using a load balancer in front of multiple nodes
• Port Range: NodePort uses ports in the range 30000-32767. Make sure your firewall allows traffic to these ports
• Multiple Nodes: You can use any node's IP address, as the NodePort is available on all nodes

#When to Use NodePort

• Development and Testing: Quick setup for local development or testing
• Internal Networks: When webhook senders are on the same internal network as your cluster nodes
• No LoadBalancer Available: When your cluster doesn't have a LoadBalancer service or Ingress controller
• Cost Considerations: When you want to avoid LoadBalancer costs

#Transitioning from NodePort to Ingress

If you started with NodePort for testing and now want to move to a production setup with Ingress:

1. Update EventListener Service Type: Change serviceType from NodePort to ClusterIP in your EventListener spec
2. Configure Automatic Exposure (Recommended): Use the automatic exposure feature to automatically create Ingress resources
3. Or Create Ingress Manually: Follow the example below to create Ingress resources manually

The following example shows how to set up EventListener with Ingress for production use.

#Small Scale + HTTPS + ALB Ingress Configuration Example

#Prerequisites

Before configuring the EventListener with Ingress, ensure the following prerequisites are met:

1. LoadBalancer/Gateway Configuration:

   • A LoadBalancer or Gateway (such as ALB) should be deployed and configured in your cluster
   • The LoadBalancer should be accessible from external systems that will send webhooks
   • For more information on configuring a Load Balancer, refer to Configure a Load Balancer.

2. Domain and Certificate Setup:

   • The domain name is configured correctly and points to your LoadBalancer
   • TLS certificates are in place (either manually created or via cert-manager)
   • DNS records are properly configured

3. Ingress Controller:

   • An Ingress controller (ALB in this example) is deployed and configured properly
   • The Ingress controller is ready to handle Ingress resources
   • For more information on creating Ingresses, refer to Creating Ingresses.

#Configuration Example

kubectl create namespace tekton-webhooks

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: eventlistener-role
rules:
- apiGroups: [""]
  resources: ["configmaps", "secrets", "serviceaccounts"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["apps"]
  resources: ["deployments"]
  verbs: ["create", "get", "list", "watch", "patch", "update"]
- apiGroups: [""]
  resources: ["services", "pods", "events"]
  verbs: ["create", "get", "list", "watch", "patch", "update"]
- apiGroups: ["tekton.dev"]
  resources: ["pipelineruns", "taskruns"]
  verbs: ["create"]
- apiGroups: ["triggers.tekton.dev"]
  resources:
    - "clustertriggerbindings"
    - "triggerbindings"
    - "clusterinterceptors"
    - "interceptors"
    - "triggers"
    - "triggertemplates"
    - "eventlisteners"
  verbs: ["get", "list", "watch"]

kubectl apply -f eventlistener-role.yaml

kubectl -n tekton-webhooks create serviceaccount eventlistener
kubectl create clusterrolebinding tekton-webhooks:eventlistener:eventlistener-role --clusterrole=eventlistener-role --serviceaccount=tekton-webhooks:eventlistener

apiVersion: triggers.tekton.dev/v1beta1
kind: EventListener
metadata:
  name: eventlistener
  namespace: tekton-webhooks
  labels:
    el.tekton.dev/namespaces: all
    el.tekton.dev/size: small
spec:
  serviceAccountName: "eventlistener" # Required: Custom SA with cluster permissions needed for namespaceSelector
  # Listen to triggers from all namespaces
  namespaceSelector:
    matchNames:
    - '*'
  # Declare Kubernetes resource, default is Deployment
  resources:
    kubernetesResource:
      serviceType: ClusterIP # ClusterIP service type
      servicePort: 80  # Service port (container port)
      replicas: 2 # Replicas
      spec: # Deployment spec
        template:
          metadata:
            labels:
              el.tekton.dev/namespaces: all
              el.tekton.dev/size: small
          spec: {}

kubectl apply -f eventlistener.yaml

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: eventlistener-ingress
  annotations:
    ### Note ALB does not require setting ingressClassName
    ## kubernetes.io/ingress.class: "nginx" ## Follow changes to the ingress class, and remember to add corresponding ingress annotations.
    ### The following configuration should be customized based on requirements:
    alb.ingress.kubernetes.io/listen-ports: '[{"HTTPS":443}, {"HTTP":80}]'
    alb.ingress.kubernetes.io/scheme: internet-facing
    alb.ingress.kubernetes.io/target-type: ip
spec:
  ### Note ALB does not require setting ingressClassName
  ## ingressClassName: alb ## Change according to the required ingress class
  tls:
  - hosts:
    - <host> # Domain name setting. Ensure DNS resolution is configured (or add to /etc/hosts for testing)
    secretName: <tls secret> # Name of the secret containing TLS certificate
  rules:
  - host: <host> # Domain name setting. Ensure DNS resolution is configured (or add to /etc/hosts for testing)
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: el-eventlistener 
            port:
              number: 80

# Test domain accessibility (replace <host> with your actual domain)
curl -kI https://<host>

# Or test the specific webhook endpoint
curl -kI https://<host>/triggers/<eventlistener-namespace>/<eventlistener-name>

curl -k -X POST -H 'Content-Type: application/json' -d '{"hello": "world"}' https://<host>/triggers/<eventlistener-namespace>/<eventlistener-name>

## The following is the expected return format:
$> {
  "eventListener": "eventlistener",
  "namespace": "tekton-webhooks",
  "eventListenerUID": "8a7edab2-b426-453a-9f92-xxxxxx",
  "eventID": "aefd3b5b-2b19-4a14-b411-xxxxxxx"
}

#Best Practices

1. Resource Limits:

   • Set appropriate resource requests and limits for EventListener Pods.
   • Adjust the number of replicas based on actual load.

2. Security:

   • Use HTTPS and Webhook Secrets.
   • Configure the least privilege ServiceAccount.
   • Validate all incoming events using interceptors.

3. Availability:

   • Expose services using LoadBalancer or Ingress.
   • Configure appropriate health checks.
   • Implement high-availability deployments.

4. Monitoring:

   • Monitor EventListener logs.
   • Set appropriate alert mechanisms.
   • Track event processing performance.

#Frequently Asked Questions

1. Events Not Triggering Pipeline

   • Check interceptor configurations.
   • Validate Webhook configuration.
   • Review EventListener logs.

2. Permission Issues

   • Confirm ServiceAccount permissions.
   • If using the default triggers-default-sa ServiceAccount, verify that it exists in the namespace and has been automatically granted the required permissions.
   • If using a custom ServiceAccount, check Role and RoleBinding configurations.
   • Verify namespace access permissions.
   • If using namespaceSelector to listen across namespaces, ensure you're using a custom ServiceAccount with cluster-scoped permissions. The triggers-default-sa ServiceAccount only has namespace-scoped permissions.

3. Performance Issues

   • Adjust resource limits.
   • Optimize interceptor configurations.
   • Consider horizontal scaling.

#Reference Links

• Tekton Triggers Official Documentation
• EventListener API Reference
• Tekton Trigger Examples
• In-Depth Understanding of EventListener