Ingress
Migrate from an NGINX ingress controller
If you’re migrating from the retiring NGINX ingress controller, HAProxy Unified Gateway can take over the Ingress resources you already have. Start with routes that use only host, path, and TLS termination. Move routes that depend on annotations after the traffic is on HAProxy Unified Gateway.
Ingress resources have no field that corresponds to most NGINX annotations, and HAProxy Unified Gateway ignores those annotations. In most cases, you’ll need to implement these settings using a Gateway API route with filters or a Backend CR. Treat the migration as two parts: use HAProxy Unified Gateway as the destination for your existing Ingress traffic first, then, one route at a time, replace each Ingress rule with a real HTTPRoute when you need routing features that Ingress alone doesn’t support.
Migrating from HAProxy Kubernetes Ingress Controller?
If you’re moving from HAProxy Kubernetes Ingress Controller instead, see Migrate from HAProxy Kubernetes Ingress Controller.
Migrate the NGINX traffic Jump to heading
-
Inspect the annotations on your Ingress resources. These are the behaviors to replace or verify before you cut over. For example, here is an Ingress that uses the NGINX annotation
rewrite-target:nixkubectl get ingress -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.metadata.annotations}{"\n"}{end}'nixkubectl get ingress -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.metadata.annotations}{"\n"}{end}'outputtextweb {"nginx.ingress.kubernetes.io/rewrite-target":"/"}outputtextweb {"nginx.ingress.kubernetes.io/rewrite-target":"/"} -
Compare the annotations and current behavior of your Ingress resources against the behaviors described in the table below. You’ll need to make adjustments to your Ingress resources to replicate some behaviors once the Ingress is managed by HAProxy Unified Gateway:
HAProxy Unified Gateway translates each Ingress into a Gateway API route and builds a backend from the Service. It ignores NGINX annotations that change the backend, such as proxy timeouts or load balancing. To change the translated backend, attach an
ingress.v3.haproxy.orgBackend CR with thecr-backendannotation. For examples, see Customize backend behavior.Check regex paths before you cut over
Ingress resources often use
pathType: ImplementationSpecificfor regex paths, and NGINX interprets those paths as regular expressions. HAProxy Unified Gateway treatsImplementationSpecificasPrefix. Routes that depend on regex matching can behave differently, so test them before you move production traffic.The table below lists Ingress behaviors that are incompatible with what HAProxy Unified Gateway supports for Ingress and what you can do to configure the equivalent functionality:
Behavior NGINX setting and replacement Rewrite paths rewrite-targetmaps to an HTTPRouteURLRewritefilter. See Rewrite the requested URL path.Redirect to HTTPS ssl-redirectandforce-ssl-redirectmap to an HTTPRouteRequestRedirectfilter. See Redirect to HTTPS.Modify headers proxy-set-headersandadd-headersmap to HTTPRoute request or response header modifier filters. See Modify request headers and Modify response headers.Enable CORS enable-corsmaps to the HTTPRoute CORS filter. See Enable CORS.Keep clients on one pod Session affinity maps to HTTPRoute session persistence or a Backend CR cookie. See Enable session persistence. Change proxy timeouts Set timeouts in a Backend CR. See Customize backend behavior. Match paths with a regex use-regexpaths need aPrefixorExactmatch, or an HTTPRoute with aRegularExpressionpath match. See Implement path-based routing.Limit requests or add authentication limit-rps,limit-connections,auth-*, andwhitelist-source-rangehave no Ingress-level equivalent. Move the route to Gateway API or configure the behavior through HAProxy Unified Gateway CRDs.Caution
Some cases, such as the
limit-rps,limit-connections,auth-*, andwhitelist-source-rangeexamples in the table, can’t be configured using Ingress. In this case, you’ll have to implement these using the Gateway API conventions instead of Ingress. -
Install HAProxy Unified Gateway 1.1 or newer and enable Ingress support.
-
Create an IngressClass named
hugwithspec.controller: haproxy.org/ingress-controller. -
Change each Ingress from the
nginxclass tohug:ingress.yamlyamlspec:ingressClassName: hugingress.yamlyamlspec:ingressClassName: hugIf your Ingress resources rely on a default class, make the
hugIngressClass the default and removeingressClassNamefrom them. Don’t leave two default classes.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: hugannotations:ingressclass.kubernetes.io/is-default-class: "true"spec:controller: haproxy.org/ingress-controlleringressclass.yamlyamlapiVersion: networking.k8s.io/v1kind: IngressClassmetadata:name: hugannotations:ingressclass.kubernetes.io/is-default-class: "true"spec:controller: haproxy.org/ingress-controllerApply the updated Ingress:
nixkubectl apply -f ingress.yamlnixkubectl apply -f ingress.yamloutputtextingress.networking.k8s.io/web configuredoutputtextingress.networking.k8s.io/web configured -
Point DNS or your external load balancer at the HAProxy Unified Gateway Service on the Ingress HTTP and HTTPS ports, 8080 and 8443 by default. The HTTPS frontend appears after a managed Ingress declares a TLS secret. If you need the Ingress frontends to use the ports you use today, set
--http-ingress-frontend-portand--https-ingress-frontend-portand restart the controller. See Expose the Ingress ports. -
Stop the NGINX ingress controller after traffic moves to HAProxy Unified Gateway and you’ve verified the routing. The ingress-nginx documentation does not have a dedicated uninstall page; remove the controller using the same method you used to install it. For a Helm install, run
helm uninstall ingress-nginx --namespace ingress-nginx, using your release and namespace names. For a manifest install, delete the same manifests you applied. The ingress-nginx installation guide lists the install methods.
If a route doesn’t work, see Troubleshoot Ingress resources.