Ingress
Migrate from HAProxy Kubernetes Ingress Controller
HAProxy Unified Gateway uses the same controller name as HAProxy Kubernetes Ingress Controller: haproxy.org/ingress-controller. Existing IngressClass resources and Ingress resources that use the default controller name match the controller without changes.
Migrating from an NGINX ingress controller?
If you’re moving from an NGINX ingress controller instead, see Migrate from an NGINX ingress controller.
Treat the migration as two parts: move your existing Ingress traffic to HAProxy Unified Gateway first, then move individual routes to the Gateway API when they need behavior that Ingress alone does not support. Review the table below to determine how you may need to adjust your configuration. The table lists HAProxy Kubernetes Ingress Controller features and whether they have an equivalent implementation in HAProxy Unified Gateway using Ingress.
| Feature | Behavior after the move |
|---|---|
| Hosts and wildcard hosts | Work unchanged. |
Prefix and Exact paths |
Work unchanged. |
defaultBackend |
Works unchanged. |
| TLS termination | Works unchanged for spec.tls. |
| TLS hosts | Ignored. Certificates from all managed Ingress resources share one listener and SNI selects the certificate. |
| Service port by name or number | Works unchanged. |
| Ingress annotations | Most are ignored. The cr-backend annotation is supported for backend settings; frontend settings have no Ingress equivalent. Move the route to Gateway API or configure the behavior through HAProxy Unified Gateway CRDs. |
pathType: ImplementationSpecific |
Treated as Prefix. |
ssl-passthrough and per-host TLS |
Not supported. |
| Other Ingress Controller CRDs | Not supported. This includes TCP custom resources. |
| Ingress Controller Backend CR | Supported through the cr-backend annotation on the Ingress. |
HAProxy Kubernetes Ingress Controller annotations vs. HAProxy Unified Gateway annotations
HAProxy Unified Gateway ignores the haproxy.org/cr-backend Service annotation used by HAProxy Kubernetes Ingress Controller. HAProxy Unified Gateway uses the gate.v3.haproxy.org/cr-backend annotation on the Service to merge an HAProxy Unified Gateway gate.v3.haproxy.org Backend CR into the backend it builds for that Service. The annotation applies to every Ingress or Gateway API route that uses the Service.
There is an important distinction here: the Ingress-level cr-backend annotation points at an HAProxy Kubernetes Ingress Controller ingress.v3.haproxy.org Backend CR. This is the HAProxy Kubernetes Ingress Controller annotation, not the HAProxy Unified Gateway annotation. If you point the Ingress cr-backend annotation at an HAProxy Unified Gateway gate.v3.haproxy.org Backend, HAProxy Unified Gateway ignores it and builds the backend with defaults.
For examples, see Customize backend behavior.
Migrate the Ingress traffic Jump to heading
Running both controllers
If you run both controllers at the same time, they compete for the same Ingress status. Add --disable-ingress-status-update to the controller arguments as described in Ingress startup arguments, then restart the controller. Without it, HAProxy Unified Gateway overwrites the address on Ingress resources it handles and clears the address on Ingress resources it doesn’t.
-
Install HAProxy Unified Gateway 1.1 or newer.
-
Check the controller name in your IngressClass resources:
nixkubectl get ingressclass -o custom-columns=NAME:.metadata.name,CONTROLLER:.spec.controllernixkubectl get ingressclass -o custom-columns=NAME:.metadata.name,CONTROLLER:.spec.controlleroutputtextNAME CONTROLLERhaproxy haproxy.org/ingress-controlleroutputtextNAME CONTROLLERhaproxy haproxy.org/ingress-controllerIf the controller name has a suffix, start HAProxy Unified Gateway with the matching
--ingress-classvalue. For example,haproxy.org/ingress-controller/prodmatches--ingress-class=prod.If you need to create an IngressClass, see Create an IngressClass.
Tip
To make an IngressClass the cluster default, add the
ingressclass.kubernetes.io/is-default-class: "true"annotation:ingressclass.yamlyamlapiVersion: networking.k8s.io/v1kind: IngressClassmetadata:name: haproxyannotations:ingressclass.kubernetes.io/is-default-class: "true"spec:controller: haproxy.org/ingress-controlleringressclass.yamlyamlapiVersion: networking.k8s.io/v1kind: IngressClassmetadata:name: haproxyannotations:ingressclass.kubernetes.io/is-default-class: "true"spec:controller: haproxy.org/ingress-controller -
Optional: To tune backend behavior with an HAProxy Unified Gateway Backend CR, annotate the Service:
service.yamlyamlapiVersion: v1kind: Servicemetadata:name: web-svcnamespace: defaultannotations:gate.v3.haproxy.org/cr-backend: web-backendspec:selector:app: web-svcports:- port: 80targetPort: 5678service.yamlyamlapiVersion: v1kind: Servicemetadata:name: web-svcnamespace: defaultannotations:gate.v3.haproxy.org/cr-backend: web-backendspec:selector:app: web-svcports:- port: 80targetPort: 5678HAProxy Unified Gateway merges the
gate.v3.haproxy.orgBackend CR namedweb-backendinto the backend it builds for this Service. The annotation applies to every Ingress or Gateway API route that uses the Service. Use the Ingress-levelcr-backendannotation for HAProxy Kubernetes Ingress Controlleringress.v3.haproxy.orgBackend CRs. For the fields available in an HAProxy Unified Gateway Backend CR, see Backend CRD. For a complete example, see Use an HAProxy Unified Gateway Backend CR. -
Point DNS or your external load balancer at the HAProxy Unified Gateway Service. The Ingress frontends listen on 8080 and 8443 by default. The HTTPS frontend appears after a managed Ingress declares a TLS secret. If the Service must keep the old ports, set
--http-ingress-frontend-portand--https-ingress-frontend-portand restart the controller. See Expose the Ingress ports. If a route doesn’t work, see Troubleshoot Ingress resources. -
Stop and uninstall the old controller after the traffic moves. See Uninstall HAProxy Kubernetes Ingress Controller for the Helm and kubectl steps.