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.

  1. Install HAProxy Unified Gateway 1.1 or newer.

  2. Enable Ingress support.

  3. Check the controller name in your IngressClass resources:

    nix
    kubectl get ingressclass -o custom-columns=NAME:.metadata.name,CONTROLLER:.spec.controller
    nix
    kubectl get ingressclass -o custom-columns=NAME:.metadata.name,CONTROLLER:.spec.controller
    output
    text
    NAME CONTROLLER
    haproxy haproxy.org/ingress-controller
    output
    text
    NAME CONTROLLER
    haproxy haproxy.org/ingress-controller

    If the controller name has a suffix, start HAProxy Unified Gateway with the matching --ingress-class value. For example, haproxy.org/ingress-controller/prod matches --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.yaml
    yaml
    apiVersion: networking.k8s.io/v1
    kind: IngressClass
    metadata:
    name: haproxy
    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: haproxy
    annotations:
    ingressclass.kubernetes.io/is-default-class: "true"
    spec:
    controller: haproxy.org/ingress-controller
  4. Optional: To tune backend behavior with an HAProxy Unified Gateway Backend CR, annotate the Service:

    service.yaml
    yaml
    apiVersion: v1
    kind: Service
    metadata:
    name: web-svc
    namespace: default
    annotations:
    gate.v3.haproxy.org/cr-backend: web-backend
    spec:
    selector:
    app: web-svc
    ports:
    - port: 80
    targetPort: 5678
    service.yaml
    yaml
    apiVersion: v1
    kind: Service
    metadata:
    name: web-svc
    namespace: default
    annotations:
    gate.v3.haproxy.org/cr-backend: web-backend
    spec:
    selector:
    app: web-svc
    ports:
    - port: 80
    targetPort: 5678

    HAProxy Unified Gateway merges the gate.v3.haproxy.org Backend CR named web-backend into the backend it builds for this Service. The annotation applies to every Ingress or Gateway API route that uses the Service. Use the Ingress-level cr-backend annotation for HAProxy Kubernetes Ingress Controller ingress.v3.haproxy.org Backend 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.

  5. 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-port and --https-ingress-frontend-port and restart the controller. See Expose the Ingress ports. If a route doesn’t work, see Troubleshoot Ingress resources.

  6. Stop and uninstall the old controller after the traffic moves. See Uninstall HAProxy Kubernetes Ingress Controller for the Helm and kubectl steps.

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