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:

  1. Add the startup argument.
  2. Restart the controller.
  3. Expose the Ingress ports.

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.

nix
helm upgrade haproxy-unified-gateway haproxytech/haproxy-unified-gateway \
--namespace haproxy-unified-gateway \
--reuse-values \
--set controller.extraArgs={--enable-ingress}
nix
helm upgrade haproxy-unified-gateway haproxytech/haproxy-unified-gateway \
--namespace haproxy-unified-gateway \
--reuse-values \
--set controller.extraArgs={--enable-ingress}
output
text
Release "haproxy-unified-gateway" has been upgraded. Happy Helming!
NAME: haproxy-unified-gateway
NAMESPACE: haproxy-unified-gateway
STATUS: deployed
output
text
Release "haproxy-unified-gateway" has been upgraded. Happy Helming!
NAME: haproxy-unified-gateway
NAMESPACE: haproxy-unified-gateway
STATUS: deployed

If you installed with kubectl, add --enable-ingress to the args list of the controller Deployment and re-apply the manifest:

controller.yaml
yaml
spec:
template:
spec:
containers:
- name: haproxy-unified-gateway
args:
- --hugconf-crd=haproxy-unified-gateway/hugconf
- --enable-ingress
controller.yaml
yaml
spec:
template:
spec:
containers:
- name: haproxy-unified-gateway
args:
- --hugconf-crd=haproxy-unified-gateway/hugconf
- --enable-ingress
nix
kubectl apply -f controller.yaml
nix
kubectl apply -f controller.yaml
output
text
deployment.apps/haproxy-unified-gateway configured
output
text
deployment.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:

nix
kubectl -n haproxy-unified-gateway rollout status deployment/haproxy-unified-gateway
nix
kubectl -n haproxy-unified-gateway rollout status deployment/haproxy-unified-gateway
output
text
deployment "haproxy-unified-gateway" successfully rolled out
output
text
deployment "haproxy-unified-gateway" successfully rolled out

If the rollout doesn’t start, restart the Deployment:

nix
kubectl -n haproxy-unified-gateway rollout restart deployment/haproxy-unified-gateway
nix
kubectl -n haproxy-unified-gateway rollout restart deployment/haproxy-unified-gateway
output
text
deployment.apps/haproxy-unified-gateway restarted
output
text
deployment.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:

nix
kubectl get service -n haproxy-unified-gateway haproxy-unified-gateway
nix
kubectl get service -n haproxy-unified-gateway haproxy-unified-gateway
output
text
NAME 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
output
text
NAME 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.

Do you have any suggestions on how we can improve the content of this page? Please leave feedback!