Alauda DevOps Pipelines Docs

Quick Start

This guide will help you get started with Tekton Triggers by creating a simple "Hello World" trigger scenario to demonstrate its basic functionality. The guide follows these steps:

  1. Configure trigger-wrapper export rules to expose EventListeners externally
  2. Create EventListener and related resources
  3. Get the automatically generated webhook address from EventListener status

TOC

Prerequisites

  1. Environment Requirements

    • Kubernetes version 1.21 or higher
    • Tekton Operator installed
    • Ensure that Tekton Triggers is installed and ready through the Operator

  2. Required Tools

    • kubectl command line tool
    • curl (for testing triggers)

  3. Permissions

    • Requires cluster administrator privileges (for configuring trigger-wrapper-config)
    • Requires namespace administrator privileges (for creating EventListener resources)

Step 1: Configure Trigger-Wrapper Export Rules

TIP

The trigger-wrapper automatically exposes EventListeners externally based on export rules. You need to configure these rules first so that EventListeners can be accessed via external URLs. For detailed configuration instructions, refer to Configure trigger-wrapper export rules.

Configure Export Rules via TektonConfig

Create or update the TektonConfig resource to configure export rules. Create the file tektonconfig.yaml:

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  pipeline:
    options:
      configMaps:
        trigger-wrapper-config:
          data:
            config: |
              export-rules:
                - name: demo-webhooks
                  host: webhooks.example.com  # Replace with your domain
                  ingressClass: nginx  # Replace with your ingress class
                  urlPathPrefix: /triggers
                  externalHosts:
                    - "https://webhooks.example.com"  # Replace with your external URL
                  namespaceSelector:
                    matchNames:
                      - "tekton-triggers-demo"  # Match your demo namespace

Choose Ingress Configuration Method

The trigger-wrapper supports two methods for configuring Ingress to expose EventListeners externally. Choose the method that best fits your environment:

Method 1: General Ingress Configuration (Recommended for Production)

This method is suitable for most Kubernetes environments. You need to:

  1. Create an IngressClass (if not already exists): for more info please refer to .

  2. Or use a LoadBalancer Service to get an external IP address for more info please refer to .

  3. Configure the export rules based on your Ingress setup:

    • If using IngressClass: Set ingressClass to your IngressClass name (e.g., nginx)
    • If using LoadBalancer: Get the external IP/domain from the LoadBalancer service and configure host and externalHosts accordingly

Example configuration for IngressClass:

export-rules:
  - name: demo-webhooks
    host: webhooks.example.com  # Your domain name
    ingressClass: nginx  # Your IngressClass name
    urlPathPrefix: /triggers
    externalHosts:
      - "https://webhooks.example.com"  # External accessible URL

Method 2: Quick Start for ACP Business Clusters

If you're using an ACP (Alauda Container Platform) business cluster, you can leverage the platform's built-in gateway for quick setup:

  1. Get your ACP platform access address (e.g., https://192.168.1.100)
  2. Get your cluster name (e.g., test)
  3. Configure the export rules as follows:
    • Set host to empty (or use wildcard *)
    • Set externalHosts to: <ACP Platform Access Address>/clusters-rewrite/<Cluster Name>
    • The final webhook URL will be: <externalHost>/<urlPathPrefix>/<namespace>/<eventlistener-name>

Example configuration for ACP:

export-rules:
  - name: demo-webhooks
    host: ""  # Empty or use wildcard "*"
    ingressClass: nginx  # Use default ingress class
    urlPathPrefix: /triggers
    externalHosts:
      - "https://192.168.1.100/clusters-rewrite/test"  # ACP Platform URL + /clusters-rewrite/<cluster-name>
    namespaceSelector:
      matchNames:
        - "tekton-triggers-demo"

With this configuration, the webhook address will be:

https://192.168.1.100/clusters-rewrite/test/triggers/tekton-triggers-demo/hello-listener
TIP

ACP Configuration Formula:

  • ACP Platform URL: https://192.168.1.100
  • Cluster Name: test
  • URL Path Prefix: /triggers (configurable)
  • External Host: https://192.168.1.100/clusters-rewrite/test
  • Final Webhook URL: https://192.168.1.100/clusters-rewrite/test/triggers/<namespace>/<eventlistener-name>

Example: If ACP platform address is https://192.168.1.100, cluster name is test, and urlPathPrefix is /triggers, then the access address is https://192.168.1.100/clusters-rewrite/test/triggers.

WARNING

Important: Replace the placeholder values (webhooks.example.com, nginx, etc.) with your actual domain name, ingress class, and external host URL. If you don't have a domain configured, you can use an empty host field and configure externalHosts with your actual accessible URL.

Apply TektonConfig

kubectl apply -f tektonconfig.yaml

Verify Configuration

Wait a few moments for the Operator to sync the configuration, then verify:

kubectl get configmap trigger-wrapper-config -n tekton-pipelines -o yaml

The ConfigMap should contain your export rules configuration.

Step 2: Create Example Project

Create Namespace

kubectl create namespace tekton-triggers-demo
TIP

For this quick start, we'll use the default ServiceAccount which has namespace-scoped permissions. This is sufficient since we're only handling triggers within the same namespace. If you need to handle triggers across multiple namespaces, refer to Setup EventListener for configuring a custom ServiceAccount with cluster-scoped permissions.

Step 3: Create Hello World TaskRun

Create Task

Create the file hello-task.yaml:

apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: hello-task
  namespace: tekton-triggers-demo
spec:
  params:
    - name: message
      description: Message to print
      type: string
      default: "Hello World!"
  steps:
    - name: echo
      image: alpine
      script: |
        echo "$(params.message)"

Create Trigger Template

Create the file trigger-template.yaml:

apiVersion: triggers.tekton.dev/v1beta1
kind: TriggerTemplate
metadata:
  name: hello-template
  namespace: tekton-triggers-demo
spec:
  params:
    - name: message
      description: Message to print
      default: "Hello World!"
  resourcetemplates:
    - apiVersion: tekton.dev/v1
      kind: TaskRun
      metadata:
        generateName: hello-run-
        namespace: tekton-triggers-demo
      spec:
        taskRef:
          name: hello-task
        params:
          - name: message
            value: $(tt.params.message)

Create Trigger Binding

Create the file trigger-binding.yaml:

apiVersion: triggers.tekton.dev/v1beta1
kind: TriggerBinding
metadata:
  name: hello-binding
  namespace: tekton-triggers-demo
spec:
  params:
    - name: message
      value: $(body.message)

Create Event Listener

Create the file event-listener.yaml:

apiVersion: triggers.tekton.dev/v1beta1
kind: EventListener
metadata:
  name: hello-listener
  namespace: tekton-triggers-demo
spec:
  # Run the following order to get ServiceAccount works for triggers within the same namespace
  # $ kubectl get sa -n ${YOUR_NS} -l triggers.tekton.dev/default-service-account -o jsonpath='{.items[0].metadata.name}'
  serviceAccountName: triggers-default-sa  # Or set to <your service account> to use a custom ServiceAccount
  triggers:
    - name: hello-trigger
      bindings:
        - ref: hello-binding
      template:
        ref: hello-template
INFO

ServiceAccount Note: We're using the default ServiceAccount here (by setting serviceAccountName to triggers-default-sa). This is sufficient for this example since all resources are in the same namespace. The trigger-wrapper will automatically expose this EventListener based on the export rules configured in Step 1.

Apply Configuration

Apply all created resources:

kubectl apply -f hello-task.yaml
kubectl apply -f trigger-template.yaml
kubectl apply -f trigger-binding.yaml
kubectl apply -f event-listener.yaml

Step 4: Get Webhook Address and Test

Wait for EventListener to be Ready

# Wait for the Pod to be ready
kubectl get pods -n tekton-triggers-demo

# Wait for EventListener to be ready
kubectl wait --for=condition=Ready eventlistener/hello-listener -n tekton-triggers-demo --timeout=60s

Get Automatically Generated Webhook Address

The trigger-wrapper automatically generates external webhook addresses based on the export rules configured in Step 1. These addresses are populated in the EventListener's status.addresses field:

# Get the first webhook address from status.addresses
export EL_URL=$(kubectl get el hello-listener -n tekton-triggers-demo -o jsonpath='{.status.addresses[0].url}')

# Or view all available addresses
kubectl get el hello-listener -n tekton-triggers-demo -o jsonpath='{.status.addresses[*].url}' | tr ' ' '\n'
TIP

Address Format: The webhook address follows the pattern: <externalHost>/<urlPathPrefix>/<namespace>/<eventlistener-name>

For example: https://webhooks.example.com/triggers/tekton-triggers-demo/hello-listener

If status.addresses is empty, check:

  • The export rules in trigger-wrapper-config match your EventListener's namespace
  • The trigger-wrapper controller is running and has processed the EventListener
  • View controller logs: kubectl logs -n tekton-pipelines -l app=tektoncd-enhancement-controller
WARNING

Network Access: Ensure your external host URL is accessible from where you're testing. If you're testing within the cluster, you may need to use port-forward or access the internal service address instead.

Send Test Request

curl -v -H 'Content-Type: application/json' -d '{"message":"Hello, Tekton!"}' $EL_URL

View Results

# View the created TaskRun
kubectl get taskrun -n tekton-triggers-demo

# View logs of the specific TaskRun
kubectl logs -l eventlistener=hello-listener -n tekton-triggers-demo

Clean Up Resources

After testing, you can delete the created resources:

kubectl delete namespace tekton-triggers-demo

Next Steps

Now that you have successfully created and tested a basic Tekton Triggers example, you can:

  1. Explore concepts of Tekton Triggers
  2. Learn how to use Setup EventListeners for common setup instructions
  3. Configure trigger-wrapper export rules for advanced exposure scenarios
  4. Setup and use Gitlab events to trigger pipelines

Frequently Asked Questions

  1. EventListener Pod fails to start

    • Check if the default ServiceAccount has sufficient namespace-scoped permissions
    • Verify the EventListener resource is correctly configured
    • View EventListener Pod logs: kubectl logs -n tekton-triggers-demo -l app=el-hello-listener

  2. Webhook address (status.addresses) is empty

    • Verify that export rules in trigger-wrapper-config match your EventListener's namespace
    • Check that the trigger-wrapper controller is running: kubectl get pods -n tekton-pipelines -l app=tektoncd-enhancement-controller
    • View controller logs to see if there are any matching or configuration errors
    • Ensure the namespace in namespaceSelector.matchNames matches your EventListener namespace

  3. Trigger does not respond

    • Verify the webhook URL is accessible (check status.addresses)
    • Check if the request format is correct
    • View the EventListener Pod logs: kubectl logs -n tekton-triggers-demo -l app=el-hello-listener
    • Verify the Ingress is correctly configured: kubectl get ingress -n tekton-triggers-demo

  4. TaskRun is not created

    • Confirm that the TriggerTemplate configuration is correct
    • Check the parameter mapping in TriggerBinding
    • View the error logs of the EventListener Pod