Configure EventListener automatic exposure rules
TOC
What This Document Helps You DoFeature overviewConfiguration entry pointField referenceField Mapping to Ingress ResourcesRequest flow diagramConfiguration examplesExample 1: wildcard host with custom prefixExample 2: shared hostname and prefixExample 3: environment-specific rulesExample 4: team-scoped publishing with default prefixExample 5: multiple external endpoints and adjusted prefixExample 6: Configuring TLS/HTTPSOption A: Manual TLS with pre-created SecretOption B: Using cert-manager for automatic certificate managementOption C: Combined TLS and annotationsGateway API (HTTPRoute) modeHTTPS in Gateway API modeConfiguration workflowRecommended SettingsVerification and troubleshootingVerify ConfigMap contentVerify Ingress objectsCheck EventListener addressesInspect Trigger annotationsTroubleshooting tipsWhat This Document Helps You Do
This document helps you configure automatic external exposure of EventListeners through the automatic exposure feature. You will learn:
- How to configure export rules to automatically expose EventListeners via Ingress or the Gateway API (HTTPRoute)
- How to set up webhook URLs that will be displayed in the UI
- How to configure different exposure strategies for different namespaces or environments
- How to verify that EventListeners are properly exposed
When to use this: Use this feature when you want the system to automatically create Ingress resources for your EventListeners, eliminating the need to manually create and manage Ingress resources. This is especially useful in production environments where you need consistent webhook URL patterns.
Prerequisites: You should have cluster administrator privileges to configure TektonConfig resources, and you should have a basic understanding of Kubernetes Ingress and networking concepts. Two verification commands pipe their output into the jq CLI.
Feature overview
The automatic exposure controller (internally named trigger-wrapper; it runs in the tektoncd-enhancement-controller Deployment) reads the trigger-wrapper-config ConfigMap in the Tekton system namespace (default: tekton-pipelines). The export-rules defined in that ConfigMap determine which EventListeners should be exposed externally (Service, Ingress, etc.) and populate the EventListener/Trigger status with the generated endpoints.
Technical Note: The internal component name is trigger-wrapper, but you don't need to remember this. You only need to configure the export rules through TektonConfig, and the system will handle the rest automatically.
Configuration entry point
On Alauda Tekton, it is recommended to manage this configuration through the TektonConfig custom resource. Embed the rule definitions under spec.pipeline.options.configMaps.trigger-wrapper-config.data.config, for example:
The Operator synchronises this spec into the trigger-wrapper-config ConfigMap inside Tekton system namespace (default: tekton-pipelines). Once updated, the automatic exposure controller refreshes its cache and reconciles resources according to the new rules.
Note: The ConfigMap name trigger-wrapper-config is an internal technical name. You manage the configuration through TektonConfig as shown above, and don't need to directly interact with the ConfigMap.
Field reference
Each entry in export-rules represents a publishing strategy. Important fields:
-
name – rule name, also used when generating Service/Ingress names. Avoid name collisions: the shared Ingress name is the rule name normalized to a valid DNS-1123 subdomain (lower-cased, characters outside
[a-z0-9-]replaced with-, repeated-collapsed). This normalization is lossy, so rule names that differ only by such characters resolve to the same Ingress and overwrite each other — for examplea_b,a.b, andA-Ball becomea-b. Give each rule a name that is already a distinct, valid DNS-1123 subdomain (lower-case letters, digits, and-); do not rely on_,., or letter case to distinguish two rules. -
ingressClass (optional) – the Ingress controller to use, e.g.
nginx,traefik. -
host (optional) – hostname matched by the Ingress. Leave empty to accept all hosts. Important: When configuring a domain name, ensure DNS resolution is properly configured (or add to
/etc/hostsfor local testing). The domain must be resolvable from systems that will send webhooks. -
externalHosts (optional) – What it does: Defines the webhook URLs that will be displayed to users in the UI and populated in EventListener's
status.addressesfield.Think of it as: The "public address" that external systems (like GitHub, GitLab) will use to send webhooks to your EventListener.
How it works:
- The controller combines each
externalHostsURL with the generated path:${externalHost}/<urlPathPrefix>/<eventlistener-namespace>/<eventlistener-name> - For example: an
externalHostslist with the single entryhttps://webhooks.example.com+urlPathPrefix: /triggers→ Final URL:https://webhooks.example.com/triggers/my-namespace/my-listener - These URLs appear in EventListener's
status.addressesfield, making it easy to copy and paste into GitHub/GitLab webhook configuration
Common scenarios:
What happens if you fill it wrong?
- ✅ Ingress will still work correctly (this field doesn't affect Ingress creation)
- ❌ Users will see incorrect webhook URLs in the UI
- ❌ Copying the URL from
status.addressesto GitHub/GitLab will fail - 🔧 Fix: Update the
externalHostsvalue in TektonConfig and the controller will refresh EventListener status
Key differences from
hostfield:Rule of thumb:
- If you can access your webhook at
https://webhooks.example.com:8443/triggers/ns/el, then addhttps://webhooks.example.com:8443toexternalHosts - The controller will append the path automatically
Important notes:
- Always include the protocol (
http://orhttps://) - Include custom ports if your LoadBalancer uses non-standard ports
- Don't include the path in
urlPathPrefix(like/triggers) - the controller appends it to the end of theexternalHostsautomatically - If unsure, leave it empty and check the actual accessible URL first, then update the configuration; while it is empty, this rule adds no address to
status.addresses(other matching rules that setexternalHostsstill add theirs)
- The controller combines each
-
urlPathPrefix (optional) – path prefix; defaults to
/triggers. The final path rendered in the Ingress is${urlPathPrefix}/${eventlistener-namespace}/${eventlistener-name}. Always start with/and avoid trailing slashes. -
namespaceSelector.matchNames (optional) – namespaces allowed by this rule. Use
"*"to target all namespaces. -
namespaceSelector.matchLabels (optional) – namespace labels; the rule applies to EventListeners in namespaces whose labels match.
-
labelSelector (optional) – Kubernetes LabelSelector used to filter EventListeners.
-
tls (optional) – TLS configuration for Ingress. Each entry specifies
hosts(list of hostnames) andsecretName(name of the TLS Secret containing the certificate). -
annotations (optional) – additional annotations for Ingress. Useful for cert-manager, nginx-specific settings, etc. Only your annotations are applied; the controller no longer injects any controller-specific annotation (such as
nginx.ingress.kubernetes.io/rewrite-target). The generated Ingress path usespathType: Exactand no rewrite, so it does not depend on nginx. Its backend is an ExternalName Service, so the Ingress controller must be able to route to ExternalName Services. -
type (optional) – exposure resource:
Ingress(default) orHTTPRoute(Gateway API). Empty defaults toIngressfor backward compatibility. See Gateway API (HTTPRoute) mode. -
gateway (optional) – required when
type: HTTPRoute. References the parent Gateway the HTTPRoute attaches to:name(required),namespace(defaults to the Tekton system namespace), optionalsectionNameandport.
Select namespaces by name with
matchNames("*"for all namespaces) or by namespace label withmatchLabels; a rule withmatchLabelscovers the namespaces whose labels match it.
Field Mapping to Ingress Resources
The following table shows how export rule fields map to the generated Ingress resource:
Example Mapping:
Given this export rule:
DNS Configuration: When using a domain name in the host field, ensure DNS records are configured to resolve the domain to your Ingress controller's IP. For local testing, you can add entries to /etc/hosts (Linux/Mac) or C:\Windows\System32\drivers\etc\hosts (Windows).
The generated Ingress will have:
metadata.name:test-webhooksspec.ingressClassName:nginxspec.rules[0].host:webhooks.example.comspec.rules[0].http.paths[].path:/triggers/${namespace}/${eventlistener-name}(for each matching EventListener)spec.tls[0].hosts: a list with the single entrywebhooks.example.comspec.tls[0].secretName:webhooks-tls-secretmetadata.annotations:cert-manager.io/cluster-issueronly (the controller adds no annotations of its own)
Replace <cluster-issuer> with the name of a cert-manager ClusterIssuer in your cluster, as described in Option B.
Request flow diagram
externalHoststells external clients which URL to call. The Ingress matches requests byhostand the exact path${urlPathPrefix}/${namespace}/${eventlistener}, and forwards to an ExternalName Service in the Tekton system namespace that resolves to the EventListener sink Service. Because the sink accepts any path, the backend receives the full path unchanged (no rewrite).
Configuration examples
Example 1: wildcard host with custom prefix
Result: the Ingress exposes /hooks/default/${namespace}/${eventlistener}. Because host is empty, any hostname will be accepted—ideal when an external gateway assigns the public domain.
Example 2: shared hostname and prefix
Result: every EventListener appears at https://webhooks.example.com/triggers/${namespace}/${eventlistener}; the backend sees the same path.
Example 3: environment-specific rules
Result:
- GitLab webhooks:
https://gitlab-staging.example.com/staging/gitlab/${namespace}/${eventlistener} - GitHub webhooks:
https://github-prod.example.com/prod/github/${namespace}/${eventlistener}
Example 4: team-scoped publishing with default prefix
Result: only EventListeners in team-a are exposed, at /triggers/team-a/${eventlistener}.
Example 5: multiple external endpoints and adjusted prefix
Result:
- Ingress serves
webhook.internal.local/internal/hooks/${namespace}/${eventlistener}internally. - Externally you can publish
https://webhooks.example.com/hooks/internal/hooks/${namespace}/${eventlistener}andhttps://backup.example.com/api/hooks/internal/hooks/${namespace}/${eventlistener}. - The backend Service always receives
/internal/hooks/${namespace}/${eventlistener}.
Example 6: Configuring TLS/HTTPS
Option A: Manual TLS with pre-created Secret
-
Create a TLS Secret containing your certificate:
-
Configure your export rule with TLS:
The controller will automatically configure the Ingress with TLS using the specified Secret.
Option B: Using cert-manager for automatic certificate management
Configure your export rule with cert-manager annotations and a tls entry that names the Secret for the certificate:
The controller copies tls into the Ingress spec.tls. cert-manager then creates a Certificate for the secretName in tls and requests the certificate from the issuer named in the annotation. Without tls, the generated Ingress has no spec.tls and cert-manager creates no Certificate.
Replace <cluster-issuer> with the name of a cert-manager ClusterIssuer in your cluster. The issuer must work without internet access, for example a CA issuer that signs with your own certificate authority. An ACME issuer that uses a public ACME server, such as Let's Encrypt, cannot reach that server from an air-gapped cluster, so the certificate is never issued.
Option C: Combined TLS and annotations
You can combine manual TLS configuration with additional annotations:
Note: cert-manager acts only when the rule also sets
tls: it creates the Certificate for thesecretNamelisted there. Withouttls, the cert-manager annotations do not lead to a certificate.
Gateway API (HTTPRoute) mode
In addition to Ingress, an export rule can expose EventListeners through the
Gateway API by setting type: HTTPRoute.
This is the recommended mode for clusters that have no Ingress controller (or no
usable ingressClass) but do run a Gateway implementation such as Envoy Gateway.
The existing Ingress behaviour is unchanged, and Gateway mode also keeps
status.addresses populated so the UI and Git webhook registration keep working.
Prerequisites:
- The Gateway API CRDs and a Gateway implementation (e.g. Envoy Gateway) are
installed. The controller checks for HTTPRoute
v1and ReferenceGrantv1beta1only when it starts. If they are not served at that moment, the controller stays in Ingress-only mode and records the warning eventGatewayAPIUnavailableon the EventListeners that atype: HTTPRouterule selects; this also happens when the CRDs were installed after the controller started. After installing the CRDs, restart the controller, for example by deleting its Pod:kubectl delete pod -n tekton-pipelines -l app=tektoncd-enhancement-controller. - A parent
Gatewayalready exists. Its listenerallowedRoutes.namespacesmust permit the Tekton system namespace (defaulttekton-pipelines), because the generated HTTPRoute is created there. The controller does not modify the Gateway; it only reads the HTTPRoute'sAcceptedandResolvedRefsconditions. externalHostsis required in this mode — it is the source ofstatus.addresses.
Example:
What the controller creates:
- One
HTTPRouteper matching EventListener in the system namespace, with a singlepath.type: Exactmatch (${urlPathPrefix}/${namespace}/${eventlistener}), aparentRefsentry pointing at your Gateway, and a cross-namespacebackendRefsentry that targets the EventListener sink Service (el-<name>, port 8080) directly. NoURLRewritefilter is used — the sink accepts the full path. The Service has port 8080 only when the EventListener sets neither anotherservicePortnor theTLS_CERTandTLS_KEYenvironment variables; with the TLS variables the listener serves HTTPS. - One
ReferenceGrantper EventListener in the EventListener's namespace, scoped byto.nameto that single sink Service, so the system-namespace HTTPRoute may reference it across the namespace boundary (least privilege).
Mode-specific field behaviour: ingressClass, tls and annotations apply
to Ingress mode only and are ignored when type: HTTPRoute. For HTTPS in Gateway
mode, terminate TLS on the Gateway listener instead — see
HTTPS in Gateway API mode below.
Verification:
status.addresses (and the Trigger annotation endpoints) are published only once
the HTTPRoute is both Accepted by its Gateway and ResolvedRefs. If an address does not appear, check
kubectl get httproute <name> -n tekton-pipelines -o yaml for
status.parents[].conditions — an Accepted: False or ResolvedRefs: False
condition usually means the Gateway listener does not allow the system namespace,
or the sink Service is not reachable.
HTTPS in Gateway API mode
In the Gateway API, TLS is terminated on the Gateway listener, not on the
HTTPRoute — trigger-wrapper never manages certificates in this mode (the tls
field applies to Ingress mode only). To serve an EventListener over HTTPS, attach
the export rule to a Gateway that has an HTTPS listener whose tls.certificateRefs
points at your certificate Secret, and pin the rule to that listener with
gateway.sectionName (or gateway.port).
1. A Gateway with an HTTPS listener (managed by the platform / cluster admin):
The certificate Secret (webhooks-tls above, holding tls.crt / tls.key)
and the Gateway are cluster/platform-managed. allowedRoutes.namespaces.from
must permit the Tekton system namespace, because the generated HTTPRoute is
created there.
2. The export rule, pinned to that HTTPS listener via gateway.sectionName:
Notes:
- Set the rule's
hostto the listenerhostnameso the HTTPRoute hostname matches the TLS SNI, and use thehttps://scheme inexternalHostsso the publishedstatus.addressesadvertise HTTPS. gateway.sectionNamepins the HTTPRoute to a named listener; usegateway.portinstead (or as well) when listeners are distinguished by port. Omitting both lets the Gateway attach the route to any compatible listener.- trigger-wrapper only creates the HTTPRoute (and its
ReferenceGrant); it does not create or modify the Gateway, the listener, or the certificateSecret.
Configuration workflow
- Write the change in the form shown in Configuration entry point and save it as
tektonconfig.yaml. The rules are oneconfigstring, so the file replaces all existing rules: copy every rule thatTektonConfigalready holds into it. - Merge the file into the existing
TektonConfig:kubectl patch tektonconfig config --type merge --patch-file tektonconfig.yaml. Do not usekubectl apply -ffor a file that holds only part ofTektonConfig:kubectl applystores the file in thekubectl.kubernetes.io/last-applied-configurationannotation, and a laterkubectl apply -fof another partial file deletes the fields that the earlier file set and the later file leaves out. If the later file leaves out these rules, the Operator resets them to the shipped empty list and removes the Ingress or HTTPRoute of every exposed EventListener. - Wait for the Operator to propagate the ConfigMap; the automatic exposure controller will then reconcile new resources automatically.
Recommended Settings
When to enable. Enable automatic exposure when EventListeners would
otherwise each need a hand-written Ingress before Git or registry webhooks can
reach them. The export rules in TektonConfig apply to every listener that a rule's
namespaceSelector and labelSelector select, so each selected listener gets
the host, path pattern, and TLS setup of its rule, and the address in
status.addresses follows one predictable format.
Recommended values. Manage the rules only through TektonConfig (see
Configuration entry point). Start from a single
shared rule with a distinct, valid DNS-1123 name, one host, the default
urlPathPrefix: /triggers, an https:// URL in externalHosts, TLS through
tls (hosts and secretName), with the Secret either created beforehand in
the Tekton system namespace or managed by cert-manager through a Certificate for
that secretName when you also set the cert-manager annotations, with an issuer
that works without internet access, such as a CA issuer. On a
cluster that several teams share, select namespaces with an opt-in label:
label each namespace whose listeners may be exposed (for example
kubectl label namespace <namespace> expose-webhooks=true) and set
namespaceSelector.matchLabels to that label, as in the sample below, so that
a team's listeners are exposed only after the namespace carries the label.
Labelling a namespace needs permission on the Namespace object, usually a
cluster administrator. The automatic
exposure controller does not react to namespace label changes: adding or
removing the label takes effect at the next reconcile of the EventListeners in
that namespace. To apply it at once, change the metadata of each of those
EventListeners, for example with
kubectl annotate eventlistener <name> -n <namespace> <key>=<value> --overwrite,
or change the rule. Use namespaceSelector.matchNames with the single entry
'*' only on clusters where every namespace belongs to the same team: it exposes
the listeners of every namespace. Set ingressClass to the IngressClass of the
cluster's Ingress controller (kubectl get ingressclass lists them); the sample
shows it as <ingress-class>. Add further rules with namespaceSelector and labelSelector only where
environments or providers need separate hosts, as in Example 3 under
Configuration examples. On clusters without a usable
Ingress controller, use type: HTTPRoute with gateway and
terminate TLS on the Gateway listener, as described in
Gateway API (HTTPRoute) mode.
Prerequisites. Cluster administrator privileges to edit TektonConfig. An
Ingress controller matching ingressClass, or, for HTTPRoute mode, the Gateway
API CRDs, installed before the automatic exposure controller starts or followed by a
restart of the controller (see Gateway API (HTTPRoute) mode),
a Gateway implementation, and a parent Gateway whose listener allows
routes from the Tekton system namespace (default tekton-pipelines). A DNS
record for host that resolves from the systems sending webhooks, and the TLS
Secret named in tls in the Tekton system namespace (or a cert-manager issuer
that works without internet access, such as a CA issuer, together with that tls
entry). Exposure only
routes requests; authenticate them on each listener as described in
Webhook Secret Authentication.
To confirm that the rules apply, use the checks in Verification and troubleshooting. To undo a rule, merge a file without it, as described in Configuration workflow; Removing a rule in Troubleshooting tips lists what is deleted and the shared Ingress that can be left behind.
Verification and troubleshooting
Verify ConfigMap content
Check that the ConfigMap contains the expected configuration:
Expected output (normal):
What to check:
- The ConfigMap exists and contains the
configkey - The
export-rulesarray matches your TektonConfig specification - YAML syntax is valid (no parsing errors)
Verify Ingress objects
Check that Ingress resources are created for matching export rules:
Important: One shared Ingress is created per export rule in the system namespace. Its name is the rule name, and it carries one pathType: Exact path per matching EventListener (${urlPathPrefix}/${namespace}/${eventlistener}). There is no per-EventListener Ingress in the EventListener's own namespace. On Alauda Container Platform, an ALB that is limited to the namespaces of certain projects serves this Ingress only if it serves the project of the system namespace, which the Operator labels cpaas.io/project=cpaas-system; otherwise the Ingress gets no ADDRESS.
Expected output (normal):
What to check:
- A shared Ingress exists for each export rule that matches at least one EventListener
- The
HOSTSfield matches thehostspecified in the export rule (empty/*means all hosts) - The Ingress has an
ADDRESSassigned (may take a few minutes) - Inspect
kubectl get ingress <rule-name> -n tekton-pipelines -o yamland confirm each matching EventListener has apathType: Exactpath - If no Ingress appears, verify the namespace matches the rule's
namespaceSelector(matchNames, ormatchLabelsfor a rule that selects by label) and EventListener labels matchlabelSelector
Check EventListener addresses
Verify that EventListener status contains the generated webhook addresses. Replace <el-name> with your EventListener name and <namespace> with the namespace where it is deployed:
Expected output (normal):
What to check:
- The
addressesarray contains URLs matching yourexternalHostsconfiguration - URLs follow the pattern:
<externalHost>/<urlPathPrefix>/<eventlistener-namespace>/<eventlistener-name> - If
addressesis empty or missing, possible causes are:- The EventListener matches no export rule
- The matching rule has no
externalHosts(addresses are built only fromexternalHosts) - The matching rule uses
type: HTTPRouteand its route is not yet bothAcceptedby its Gateway andResolvedRefs(addresses are published only when both conditions areTrue) - The matching rule uses Ingress mode and its ExternalName Service or shared Ingress cannot be created or updated (the controller log shows
Failed to process export rule; an IP address inhostis one cause, see Using IP addresses instead of domain names in Troubleshooting tips) - The configuration does not load (the controller log shows
Failed to load config, see Misconfigured label selectors in Troubleshooting tips). The controller then publishes no new address and keeps the addresses that it published before
Inspect Trigger annotations
Check the export metadata stored in Trigger annotations. Replace <trigger-name> with your Trigger name and <namespace> with the namespace where it is deployed:
Expected output (normal), for a Trigger my-trigger in the tekton-triggers-demo namespace that an EventListener my-eventlistener in the same namespace references with triggerRef (a direct match):
What to check:
- The annotation contains an array of EventListener information
- Each entry includes
name,namespace,endpoints, andrelevancefields - The
endpointsarray matches the EventListener'sstatus.addresses - The
relevance.scoreindicates how well the EventListener matches the Trigger (higher is better) - If the annotation is missing, the Trigger may not have found any matching EventListeners
Troubleshooting tips
-
If a rule does not apply:
- Verify that the namespace is listed in
matchNames(or use"*"for all namespaces); for a rule that selects by label, verify that the namespace labels matchmatchLabels - Check that EventListener labels satisfy the
labelSelectorrequirements - Check that no rule has an invalid
labelSelector(see the next item): one invalid selector stops every rule from applying
- Verify that the namespace is listed in
-
Misconfigured label selectors:
- A
labelSelectorthat cannot be parsed makes the controller reject the whole configuration, not only that rule. The controller leaves the existing Ingresses, HTTPRoutes and EventListener addresses as they are, and no rule change applies until the selector is fixed - The controller log shows
Failed to load configwith the errorinvalid config: export rule[<index>] (<rule-name>): invalid labelSelector: .... Reading it needs read access to Pod logs intekton-pipelines, usually a cluster administrator. With-l,kubectl logsprints only the last 10 lines unless--tailis set, so read the whole log:kubectl logs -n tekton-pipelines -l app=tektoncd-enhancement-controller --tail=-1 | grep 'Failed to load config'
- A
-
Removing a rule (or switching its
type):- Deletes the generated resources for that rule (Ingress + ExternalName Service, or HTTPRoute + ReferenceGrant) when the config change reconciles the EventListeners
- If no EventListener exists when you remove the rule or switch its
type, the rule's shared Ingress is left behind. Its backend ExternalName Service is already deleted, so requests to its paths return503or500. Delete that Ingress by hand: it is in the Tekton system namespace (defaulttekton-pipelines) and is named after the rule, normalized as described fornameabove, for examplekubectl delete ingress -n tekton-pipelines <export-rule-name>. Removing a rule while at least one EventListener exists avoids this - Switching a rule between
IngressandHTTPRouteprunes the old mode's resources and creates the new ones - Setting
export-rulesto an empty array disables all external exposure - EventListener
status.addresseswill be cleared when no rules match
-
Using IP addresses instead of domain names:
-
Problem: Kubernetes Ingress resources do not support IP addresses as
hostvalues. If you configurehostwith an IP address (e.g.,host: 192.0.2.10), the Ingress will fail to be created or will not work correctly. -
Solution 1: Leave
hostempty or set it to"*"to accept all hosts. The Ingress will match requests regardless of the host header: -
Solution 2: Configure a domain name that resolves to your IP address, then use that domain in the
hostfield:-
Set up DNS resolution: Add an A record pointing your domain to the IP address (e.g.,
webhooks.example.com→192.0.2.10) -
Configure the export rule with the domain name:
-
-
Note:
externalHostscan contain IP addresses or URLs, as it's only used to populate EventListenerstatus.addressesand doesn't affect Ingress creation. However, the Ingress itself must use a valid hostname (or be empty) in thehostfield.
-
By maintaining the ConfigMap through TektonConfig, you can flexibly control how Tekton EventListeners are exposed to external systems. Keep an eye on controller logs during updates to confirm that reconciliations complete successfully.