Ingress
Enable Ingress support
This page applies to:
- HAProxy Unified Gateway 1.1 and newer
HAProxy Unified Gateway disables its support for Ingress by default. To grant the controller permission to read Ingress resources, set the --enable-ingress startup argument and restart the controller. The controller exposes the dedicated Ingress ports after it starts.
Prerequisites checklist Jump to heading
Before continuing, ensure that you’ve met these prerequisites:
- You’ve installed HAProxy Unified Gateway version 1.1 or newer and the Gateway API custom resource definitions experimental version 1.6.0 or newer. Experimental version 1.7.0 or newer is required if you’ve installed via the Helm chart, as it enforces that version. HAProxy Unified Gateway requires Gateway API even when you use only Ingress resources. See How HAProxy Unified Gateway supports Ingress for more information.
- You’ve installed the kubectl command-line tool.
- Optional: You’ve installed the ingress.v3.haproxy.org custom resource definitions from HAProxy Kubernetes Ingress Controller. Install them only if you plan to attach a Backend CR to an Ingress.
Enable the controller Jump to heading
To enable Ingress support:
Add the startup argument Jump to heading
Chart and application versions
The Helm chart version and the HAProxy Unified Gateway version are separate. Check the chart’s appVersion, or set controller.image.tag=1.1.0, when you install or upgrade.
If you installed with Helm, add the --enable-ingress argument to the controller with the helm upgrade command:
Caution
If you already pass other arguments through controller.extraArgs, add --enable-ingress to that list so the upgrade doesn’t replace them.
nixhelm upgrade haproxy-unified-gateway haproxytech/haproxy-unified-gateway \--namespace haproxy-unified-gateway \--reuse-values \--set controller.extraArgs={--enable-ingress}
nixhelm upgrade haproxy-unified-gateway haproxytech/haproxy-unified-gateway \--namespace haproxy-unified-gateway \--reuse-values \--set controller.extraArgs={--enable-ingress}
outputtextRelease "haproxy-unified-gateway" has been upgraded. Happy Helming!NAME: haproxy-unified-gatewayNAMESPACE: haproxy-unified-gatewaySTATUS: deployed
outputtextRelease "haproxy-unified-gateway" has been upgraded. Happy Helming!NAME: haproxy-unified-gatewayNAMESPACE: haproxy-unified-gatewaySTATUS: deployed
If you installed with kubectl, add --enable-ingress to the args list of the controller Deployment and re-apply the manifest:
controller.yamlyamlspec:template:spec:containers:- name: haproxy-unified-gatewayargs:- --hugconf-crd=haproxy-unified-gateway/hugconf- --enable-ingress
controller.yamlyamlspec:template:spec:containers:- name: haproxy-unified-gatewayargs:- --hugconf-crd=haproxy-unified-gateway/hugconf- --enable-ingress
nixkubectl apply -f controller.yaml
nixkubectl apply -f controller.yaml
outputtextdeployment.apps/haproxy-unified-gateway configured
outputtextdeployment.apps/haproxy-unified-gateway configured
The Deployment rollout restarts the controller. If you applied a changed Deployment manifest, the rollout starts automatically. Use kubectl rollout status to wait for it to finish.
Restart the controller Jump to heading
Startup argument and port changes require a controller restart. If you installed with Helm, the helm upgrade command rolls out a new Pod automatically. If you applied a changed Deployment manifest, the rollout also starts automatically. Wait for the rollout to finish:
nixkubectl -n haproxy-unified-gateway rollout status deployment/haproxy-unified-gateway
nixkubectl -n haproxy-unified-gateway rollout status deployment/haproxy-unified-gateway
outputtextdeployment "haproxy-unified-gateway" successfully rolled out
outputtextdeployment "haproxy-unified-gateway" successfully rolled out
If the rollout doesn’t start, restart the Deployment:
nixkubectl -n haproxy-unified-gateway rollout restart deployment/haproxy-unified-gateway
nixkubectl -n haproxy-unified-gateway rollout restart deployment/haproxy-unified-gateway
outputtextdeployment.apps/haproxy-unified-gateway restarted
outputtextdeployment.apps/haproxy-unified-gateway restarted
Expose the Ingress ports Jump to heading
The Ingress frontends listen on 8080 and 8443 inside the controller Pod. The controller adds these ports to its Service as it creates the corresponding listeners. To use different ports, set --http-ingress-frontend-port and --https-ingress-frontend-port and restart the controller.
Don't share ports
If you set an Ingress frontend port to a port that a Gateway listener already uses, both routes will fail. Use different ports for your Ingress resources.
If you manage the Service yourself, confirm that it exposes the ports you configured. To check the ports that HAProxy Unified Gateway published:
nixkubectl get service -n haproxy-unified-gateway haproxy-unified-gateway
nixkubectl get service -n haproxy-unified-gateway haproxy-unified-gateway
outputtextNAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S)haproxy-unified-gateway LoadBalancer 10.43.12.34 192.0.2.10 31024:31103/TCP,31060:32387/TCP,8080:31234/TCP,8443:32443/TCP
outputtextNAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S)haproxy-unified-gateway LoadBalancer 10.43.12.34 192.0.2.10 31024:31103/TCP,31060:32387/TCP,8080:31234/TCP,8443:32443/TCP
The HTTPS port appears after at least one managed Ingress declares a TLS secret.
Ingress startup arguments Jump to heading
Use these startup arguments to customize how the controller will manage Ingress resources:
| Argument | Default | Purpose |
|---|---|---|
--enable-ingress |
false |
Watch Ingress and IngressClass resources and translate them. |
--ingress-class |
empty | Suffix on the controller name that this instance manages. When unset, the controller name is haproxy.org/ingress-controller. |
--empty-ingress-class |
false |
Along with the Ingress resources with the specified --ingress-class, also manage Ingress resources that have no IngressClass defined. |
--http-ingress-frontend-port |
8080 |
HTTP port for the Ingress frontend. |
--https-ingress-frontend-port |
8443 |
HTTPS port for the Ingress frontend. |
--disable-ingress-status-update |
false |
Stop writing status.loadBalancer.ingress on managed Ingress resources. |
Limitations Jump to heading
Ingress support covers routing and TLS termination for common Ingress resources, but it doesn’t reproduce the entire HAProxy Kubernetes Ingress Controller feature set. The table below illustrates the differences and describes the limitations:
| Area | Limitation |
|---|---|
| Annotations | Most Ingress annotations are ignored. The cr-backend annotation is supported for backend settings. Use Gateway API fields or filters for frontend settings. |
| Status | HAProxy Unified Gateway clears the status.loadBalancer.ingress property on Ingress resources it doesn’t manage, unless you set --disable-ingress-status-update. |
| TLS | Termination only. SSL passthrough, a separate TLS listener per host, and mTLS annotations, and per-host TLS annotations aren’t supported. |
| Path types | pathType: ImplementationSpecific is treated as Prefix. |
| Cross-namespace | An Ingress resource can’t reference a Backend CR in another namespace. |
| Custom resources | Only the ingress.v3.haproxy.org CR is supported by adding the cr-backend annotation to the Ingress resource. Other HAProxy Kubernetes Ingress Controller CRDs aren’t supported. |
| Ports | The Ingress frontends use dedicated ports, 8080 and 8443, by default. |
| Gateway API | The Gateway API CRDs are required, even when you use only Ingress resources. |
How HAProxy Unified Gateway supports Ingress Jump to heading
HAProxy Unified Gateway doesn’t render Ingress resources directly. It translates each Ingress rule into a synthetic HTTPRoute resource and attaches the routes to a synthetic Gateway that exists only in the controller’s memory. The routes then follow the same pipeline as hand-written Gateway API routes, which means they get the same listeners, maps, backends, certificates, and status handling. This is why you must install the Gateway API CRDs.
The controller creates one synthetic route per Ingress rule, plus one route for spec.defaultBackend. None of these synthetic objects exist in the cluster, so kubectl get gateway and kubectl get httproute won’t list them. Ingress traffic is served by two dedicated frontends:
| Frontend | Default port | Traffic |
|---|---|---|
hug_http_8080 |
8080 | HTTP |
hug_https_8443 |
8443 | HTTPS, after a managed Ingress declares a TLS secret |
The frontend names appear in the generated HAProxy configuration and in controller logs. They’re useful when you troubleshoot a route.
Now that Ingress support is enabled, configure Ingress resources. If a route doesn’t work, see Troubleshoot Ingress resources.