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

  1. 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:

    nix
    kubectl get ingress -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.metadata.annotations}{"\n"}{end}'
    nix
    kubectl get ingress -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.metadata.annotations}{"\n"}{end}'
    output
    text
    web {"nginx.ingress.kubernetes.io/rewrite-target":"/"}
    output
    text
    web {"nginx.ingress.kubernetes.io/rewrite-target":"/"}
  2. 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.org Backend CR with the cr-backend annotation. For examples, see Customize backend behavior.

    Check regex paths before you cut over

    Ingress resources often use pathType: ImplementationSpecific for regex paths, and NGINX interprets those paths as regular expressions. HAProxy Unified Gateway treats ImplementationSpecific as Prefix. 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-target maps to an HTTPRoute URLRewrite filter. See Rewrite the requested URL path.
    Redirect to HTTPS ssl-redirect and force-ssl-redirect map to an HTTPRoute RequestRedirect filter. See Redirect to HTTPS.
    Modify headers proxy-set-headers and add-headers map to HTTPRoute request or response header modifier filters. See Modify request headers and Modify response headers.
    Enable CORS enable-cors maps 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-regex paths need a Prefix or Exact match, or an HTTPRoute with a RegularExpression path match. See Implement path-based routing.
    Limit requests or add authentication limit-rps, limit-connections, auth-*, and whitelist-source-range have 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-*, and whitelist-source-range examples 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.

  3. Install HAProxy Unified Gateway 1.1 or newer and enable Ingress support.

  4. Create an IngressClass named hug with spec.controller: haproxy.org/ingress-controller.

  5. Change each Ingress from the nginx class to hug:

    ingress.yaml
    yaml
    spec:
    ingressClassName: hug
    ingress.yaml
    yaml
    spec:
    ingressClassName: hug

    If your Ingress resources rely on a default class, make the hug IngressClass the default and remove ingressClassName from 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.yaml
    yaml
    apiVersion: networking.k8s.io/v1
    kind: IngressClass
    metadata:
    name: hug
    annotations:
    ingressclass.kubernetes.io/is-default-class: "true"
    spec:
    controller: haproxy.org/ingress-controller
    ingressclass.yaml
    yaml
    apiVersion: networking.k8s.io/v1
    kind: IngressClass
    metadata:
    name: hug
    annotations:
    ingressclass.kubernetes.io/is-default-class: "true"
    spec:
    controller: haproxy.org/ingress-controller

    Apply the updated Ingress:

    nix
    kubectl apply -f ingress.yaml
    nix
    kubectl apply -f ingress.yaml
    output
    text
    ingress.networking.k8s.io/web configured
    output
    text
    ingress.networking.k8s.io/web configured
  6. 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-port and --https-ingress-frontend-port and restart the controller. See Expose the Ingress ports.

  7. 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.

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