HAProxy to NGINX Ingress Migration Tool

Migrating from HAProxy? The HAProxy Kubernetes Ingress Controller is actively maintained; this guide is for teams standardizing on the NGINX data plane. It translates HAProxy's annotations, ConfigMap, and Global/Defaults/Backend/TCP CRDs into the NGINX Ingress Controller's ConfigMap + annotation + VirtualServer/Policy model, resource by resource.

Overview

This interactive guide helps you migrate from the HAProxy Kubernetes Ingress Controller (haproxytech/kubernetes-ingress) to NGINX Ingress Controller (nginx/kubernetes-ingress). It covers the haproxy.org/ annotations at all three HAProxy scopes (ConfigMap, Ingress, and Service; note that NGINX Ingress Controller has no Service-level annotation tier), the controller ConfigMap, the ingress.v3.haproxy.org CRDs (Global, Defaults, Backend, TCP, Frontend and ValidationRules) along with the deprecated ingress.v1.haproxy.org group that v3.2.19 still serves, the legacy tcp-services ConfigMap, and route-acl canary routing, across three tabs:

  • Getting started: why teams migrate, NGINX Ingress Controller CRD overviews, installation, and a migration checklist
  • HAProxy config analyzer: paste annotated Ingress/Service manifests, the HAProxy ConfigMap, or Global/Defaults/Backend/TCP CRs and get automatic migration suggestions with ready-to-use YAML
  • Reference guide: complete annotation, CRD, ConfigMap, and controller-flag mapping tables with side-by-side examples

Why migrate?

The HAProxy Kubernetes Ingress Controller is actively maintained, so moving off it is a choice rather than a forced migration. Teams that migrate usually do it to consolidate:

  • Standardize on the NGINX data plane: one proxy technology across VMs, containers, and Kubernetes means one config language to debug and consistent performance characteristics everywhere
  • Schema-validated CRDs over raw config: HAProxy's advanced features often reach for *-config-snippet escape hatches that inject raw HAProxy configuration; NGINX Ingress Controller's VirtualServer, Policy, and TransportServer CRDs are type-checked and validated by the API server
  • NGINX Plus upgrade path: F5 WAF for NGINX and F5 DoS for NGINX, JWT, OIDC, active health checks, and zone-sync are available as NGINX Plus policies with F5 commercial support (the analogue of HAProxy Enterprise's WAF, Global Profiling Engine, and Bot Management)
  • Commercial support from F5: enterprise support contracts cover the controller and the NGINX data plane together

The two controllers structure configuration differently, and knowing the mental model makes the mappings obvious:

  • HAProxy resolves haproxy.org/ annotations across four tiers (default < ConfigMap < Ingress < Service, highest wins), and its Global/Defaults/Backend/Frontend CRDs replace annotations when both are present
  • NGINX Ingress Controller keeps global defaults in one nginx-config ConfigMap that per-resource annotations and CRDs override; there is no Service-level annotation tier, so Service-scoped HAProxy annotations move to per-Ingress annotations or the ConfigMap
Fair warning: a few HAProxy behaviors differ on NGINX Ingress Controller: snippet content is a different configuration language (never copyable), redirect and rate-limit reject codes default differently (emit them explicitly), and there is no Service-level annotation tier. The Key Differences table covers these head-on.

Phased migration strategy

Rather than performing a "big bang" cutover, F5 recommends a phased migration that validates each application before decommissioning HAProxy. Because HAProxy's CRD group (ingress.v3.haproxy.org) and NGINX Ingress Controller's CRDs (k8s.nginx.org) are entirely separate API groups, both controllers coexist in one cluster without touching each other's resources; the migration is additive translation, not in-place mutation.

  1. Deploy side-by-side: install NGINX Ingress Controller alongside HAProxy with its own IngressClass (see Install alongside HAProxy Kubernetes Ingress Controller). Existing traffic is unaffected: an Ingress keeps the controller its class names.
  2. Translate service-by-service: create the VirtualServer, Policy, and TransportServer resources for one application at a time (the Config analyzer and nic-migrate generate them, reading the Ingress, the Services it routes to and the HAProxy ConfigMap together). Validate against the LoadBalancer IP of NGINX Ingress Controller with curl --resolve app.example.com:443:<NGINX-IP>, then flip that host's DNS record. To keep a plain Ingress instead, migrate its annotations and set its ingressClassName to the NGINX Ingress Controller class.
  3. Decommission: after every host has been cut over and validated, remove the HAProxy Deployment, its IngressClass, both *.haproxy.org CRD groups, and the CRs they managed.
Tip: Migrate certificates first. NGINX Ingress Controller has no on-the-fly certificate signing (HAProxy's generate-certificates has no equivalent); install cert-manager and issue certificates for each host before the DNS cutover, or pre-provision kubernetes.io/tls Secrets, so the new controller serves valid TLS from the first request.

Install alongside HAProxy Kubernetes Ingress Controller

HAProxy Kubernetes Ingress Controller's class is usually haproxy (an IngressClass with controller haproxy.org/ingress-controller), and NGINX Ingress Controller's Helm chart creates nginx, so the two classes do not collide. Each controller takes the Ingresses whose class names it:

Helm (example)

helm install nginx-ingress oci://ghcr.io/nginx/charts/nginx-ingress \
  --set controller.ingressClass.name=nginx \
  --set controller.config.name=nginx-config \
  --set controller.enableSnippets=true \
  --set controller.enableTLSPassthrough=true

Keep only the flags your migrated resources need:

  • controller.config.name: the examples on this page write the ConfigMap nginx-config, the name the manifests install. The chart names it after the release instead (nginx-ingress for this command) unless this is set, and NGINX Ingress Controller reads only the ConfigMap its -nginx-configmaps flag names, so keys written to any other one are silently unused.
  • controller.enableSnippets: off by default. With it off, NGINX Ingress Controller rejects any resource that carries a snippet, and every HAProxy *-config-snippet becomes one, as does a deny list inside an allow list. The ConfigMap snippet keys work without it.
  • controller.enableTLSPassthrough: off by default. ssl-passthrough becomes a TransportServer on the built-in tls-passthrough listener, which exists only with this flag.
  • controller.globalConfiguration.create: off by default. tcp-services entries and TCP custom resources become TransportServers on listeners a GlobalConfiguration declares: list them under controller.globalConfiguration.spec, and expose their ports on the controller Service.
  • controller.enableCertManager: off by default. cert-manager HTTP-01 challenges for a VirtualServer's host pass its HTTPS redirect and authentication only with this flag (v5.7.0 and later).
An Ingress with no class: HAProxy Kubernetes Ingress Controller, run without --ingress.class, takes an Ingress that names no class when the cluster has no default IngressClass; NGINX Ingress Controller never takes one. A VirtualServer or TransportServer with no class is the opposite: every NGINX Ingress Controller in the cluster takes it. Give each HAProxy Ingress an explicit class before you start, and the migrated resources the NGINX Ingress Controller class: the analyzer leaves a class naming HAProxy off them, and nic-migrate --class sets one.
Note: The NGINX Ingress Controller documentation covers this in Run multiple Ingress controllers.

Defaults that change

A setting you never configured still changes if the two controllers default it differently. Set the NGINX Ingress Controller value in the nginx-config ConfigMap, or per resource, wherever the old default matters to you.

SettingHAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerWhat to check
Request body sizeNo limit1m (client-max-body-size)Uploads over 1 MB get 413. Set client-max-body-size to the largest body you accept.
Response bufferingStreamedOn (proxy-buffering)Server-sent events and streamed responses arrive in chunks. Set proxy-buffering: "false" for them.
HTTP/2Offered (tls-alpn h2,http/1.1)Off (http2)Clients fall back to HTTP/1.1, and gRPC fails. Turn it on per host with nginx.org/http2 or VirtualServer spec.http2, or for every host with http2: "true".
Upstream connect timeout5s (timeout-connect)60s (proxy-connect-timeout)An unreachable Pod is given up on later.
Upstream response timeout50s (timeout-server)60s (proxy-read-timeout)A slow backend is given longer.
Client keep-alive idle timeout1m (timeout-http-keep-alive)75s (keepalive-timeout)Idle client connections stay open longer.
WebSocket idle timeout1h (timeout-tunnel)60s (proxy-read-timeout, proxy-send-timeout)An idle WebSocket or other upgraded connection closes after a minute. Raise both timeouts for the backends that hold one open.
Load-balancing methodRound robinrandom two least_conn (lb-method)Request distribution changes.
Health checksActive probes (check)Passive: 1 failure in 10s (max-fails, fail-timeout)An idle Pod is never probed. Active health checks need NGINX Plus.
HTTP-to-HTTPS redirect code302 (ssl-redirect-code)301 (http-redirect-code)Clients and caches treat the redirect as permanent. The analyzer sets 302.
Server headerThe backend's ownNGINX and its version (server-tokens)Set server-tokens: "false" to hide the NGINX version.

Gateway API

HAProxy Kubernetes Ingress Controller implements only the Gateway API's TCPRoute. NGINX Gateway Fabric is the NGINX implementation of the Gateway API, and ingress2gateway converts Ingress resources to it. This tool covers the move to NGINX Ingress Controller, which keeps the Ingress API.

CRDs summary

NGINX Ingress Controller uses Custom Resource Definitions (CRDs) to extend Kubernetes with NGINX-specific configuration. CRDs provide type-safe, validated configuration that goes beyond what standard Ingress annotations can offer.

VirtualServer CRD

The primary CRD for configuring HTTP/HTTPS load balancing. It replaces Ingress resources and provides advanced traffic management capabilities with full validation.

  • Traffic Splitting: Route percentages of traffic to different backends for canary/blue-green deployments
  • Content-Based Routing: Route based on headers, cookies, arguments, or variables
  • Path Rewriting: Modify request URIs with regex support before forwarding to backends
  • Error Pages: Custom responses for specific HTTP error codes
  • Request/Response Headers: Add, modify, or remove headers in transit
  • Health Checks: Active health monitoring of upstream servers (NGINX Plus)
  • Session Persistence: Cookie-based sticky sessions

VirtualServerRoute CRD

Enables delegation of route configuration to different namespaces. Allows teams to manage their own routing rules while maintaining centralized control over the domain.

  • Cross-Namespace Routing: Reference services in different namespaces
  • Path Delegation: Delegate path prefixes to other teams/namespaces
  • Independent Updates: Teams update routes without modifying the parent VirtualServer
  • Access Control: Limit which namespaces can define routes for a host

Policy CRD

Reusable security and traffic policies that can be attached to VirtualServers or specific routes. Policies enable consistent security controls across multiple applications.

  • Rate Limiting: Limit request rates by IP, header, or custom key
  • Access Control: IP allowlists and denylists
  • Basic Auth: Username/password authentication via htpasswd
  • JWT Validation: Validate JSON Web Tokens (Plus)
  • OIDC: Native OpenID Connect integration (Plus)
  • API Key Auth: Authenticate via API keys in headers/query
  • mTLS: Client certificate verification (ingress) and backend TLS (egress)
  • WAF: F5 WAF for NGINX web application firewall (Plus)

TransportServer CRD

Configures TCP/UDP load balancing for non-HTTP protocols. Essential for databases, message queues, gaming servers, and other Layer 4 applications.

  • TCP Load Balancing: MySQL, PostgreSQL, Redis, custom TCP services
  • UDP Load Balancing: DNS, RADIUS, gaming protocols
  • TLS Passthrough: Pass encrypted traffic directly to backends
  • Health Checks: TCP/UDP health monitoring (NGINX Plus; ignored on NGINX Open Source)
  • Session Persistence: IP hash-based session affinity

GlobalConfiguration CRD

Cluster-wide listeners for NGINX Ingress Controller: the TCP, UDP and HTTP ports that TransportServers and VirtualServers reference by name.

  • TCP/UDP Listeners: Define ports for non-HTTP traffic
  • HTTP Listeners: Extra HTTP or HTTPS ports a VirtualServer selects in spec.listener

Installing CRDs

CRDs can be installed via Helm or manually using manifests, depending on your deployment method. See the NGINX Ingress Controller installation docs for full instructions.

Helm (example)

If you install NGINX Ingress Controller via Helm, CRDs are included automatically. To ensure they are enabled:

helm install nginx-ingress oci://ghcr.io/nginx/charts/nginx-ingress --version 2.8.0 --set controller.enableCustomResources=true

The controller.enableCustomResources flag is true by default. If you previously disabled it, re-enable it to use CRD resources. See the Helm installation guide for details.

Manifests (example)

If you deploy using manifests, install CRDs manually before deploying the controller:

kubectl apply -f https://raw.githubusercontent.com/nginx/kubernetes-ingress/v5.7.0/deploy/crds.yaml

Replace the version number with your target controller version. See the manifest installation guide for the full step-by-step process.

Note: The crds.yaml file contains all CRDs (VirtualServer, VirtualServerRoute, Policy, TransportServer, GlobalConfiguration) in a single manifest.
Note: Replace version numbers with your target controller version.

Migration checklist

Progress is saved in your browser.
  • Install the NGINX Ingress Controller CRDs via Helm (controller.enableCustomResources=true) or manifests (deploy/crds.yaml)
  • Inventory haproxy.org/ annotations at all three scopes: ConfigMap, Ingress, and Service objects (NGINX Ingress Controller has no Service-level annotation tier)
  • Catalog the HAProxy controller ConfigMap keys and any cr-* pointers (cr-global/cr-defaults/cr-backend/cr-frontend-*)
  • Inventory your CRs (ingress.v3.haproxy.org Global/Defaults/Backend/TCP/Frontend/ValidationRules, plus any on the deprecated ingress.v1.haproxy.org) and drop the cr-* pointer indirection: migrate the referenced CR's content, not the pointer
  • Convert auth-secret Secrets to one htpasswd file under the key htpasswd (concatenate the per-user entries; the Secret can stay Opaque)
  • Add the CA to client-ca/server-ca Secrets under ca.crt (HAProxy reads it from tls.crt); the Secret can stay Opaque
  • Convert allow-list/deny-list (and the deprecated whitelist/blacklist aliases) to accessControl Policies: allow XOR deny, and an allow Policy overrides a deny Policy on the same resource, so a rule needing both is one allow list with the overlapping denies ahead of it (see the allow-list row)
  • Convert rate-limit-* to a rateLimit Policy (or nginx.org/limit-req-*) and emit rejectCode: 403 explicitly (NGINX Ingress Controller defaults to 503 for the Policy and 429 for nginx.org/limit-req-reject-code)
  • Convert ssl-redirect/request-redirect and emit the redirect code 302 explicitly (NGINX Ingress Controller http-redirect-code/ActionRedirect default is 301)
  • Re-express route-acl canary as VirtualServer splits[] (from rand()) and matches[].conditions[] (cookie/header/argument); src/CIDR ACLs become accessControl Policies
  • Convert cookie-persistence to VirtualServer upstream sessionCookie (omit expires)
  • Collapse the cors-* annotations into one cors Policy attached via nginx.org/policies; emit maxAge explicitly and enumerate allowMethods (no *)
  • Convert the tcp-services ConfigMap and TCP CRs to GlobalConfiguration listeners + TransportServers; add an SNI spec.host for :ssl (TLS-terminated) entries
  • Convert ssl-passthrough to a TransportServer (tls-passthrough listener) and set the -enable-tls-passthrough flag
  • Re-author *-config-snippet content as NGINX directives (main/http/server/location context) and set -enable-snippets for resource snippets
  • Relocate Service-scoped annotations to per-Ingress annotations or the ConfigMap (NGINX Ingress Controller has no Service tier)
  • Split timeout-server into both nginx.org/proxy-read-timeout and nginx.org/proxy-send-timeout
  • Check each hand-written pathType: Prefix path: NGINX matches a plain /foo against /foobar, so write it as =/foo plus /foo/, as the analyzer does
  • Hand-translate log-format/log-format-tcp: HAProxy %-tokens become NGINX $-variables (never copy verbatim)
  • Re-author ModSecurity/CRS rules as an F5 WAF for NGINX waf Policy (NGINX Plus): HAProxy Enterprise WAF rules are not portable
  • Rebuild Prometheus/Grafana dashboards: NGINX Ingress Controller metric names (nginx_ingress_*) differ from HAProxy's on a dedicated :9113 port
  • Review the defaults that change (request body size, response buffering, HTTP/2, timeouts, load balancing, health checks) and set the ones that matter in nginx-config
  • Validate in a staging environment before cutover
  • Cut over DNS host-by-host (validate with curl --resolve app.example.com:443:<NGINX-IP>), then decommission the HAProxy Deployment, IngressClass, and CRDs

Command line tool

Beta: nic-migrate is new and under active development. Review its output before applying anything to a cluster: command names, flags, and the manifests it generates may still change.

The analyzer on this page works on one paste at a time. nic-migrate runs the same engine from a terminal with --source haproxy, across a directory of manifests or read straight from a running cluster. It loads the mapping database out of this site's own source rather than keeping a second copy, so it cannot drift from the tables in the reference guide. It is not distributed as a download; clone the repository for this site and run it with Node 18 or newer, with nothing to install.

Review what would change

Reads every kind HAProxy Kubernetes Ingress Controller keeps configuration on (annotated Ingress and Service objects, the controller ConfigMap, and the Global, Defaults, Backend, Frontend and TCP custom resources), from files or with --kubectl, and prints the annotation swaps, the Policies and CRDs required, and anything the analyzer cannot express on its own, graded blocking, review, or note.

node tools/nic-migrate/nic-migrate.js report --source haproxy -f ./manifests

Generate manifests

Merges those results into resources you can apply: one VirtualServer per host carrying every route and backend, with Policies referenced, TLS preserved, and the namespace kept. --target ingress instead keeps your Ingress resources and rewrites their annotations. Pass --class to set NGINX Ingress Controller's IngressClass; a class naming HAProxy is left off the output, because NGINX Ingress Controller ignores a resource claiming a class it does not own, and does so without erroring.

node tools/nic-migrate/nic-migrate.js convert --source haproxy --class nginx -f ./manifests --validate

Both commands apply each setting where HAProxy Kubernetes Ingress Controller applies it: a backend setting from the Service the path routes to, then the Ingress, then the ConfigMap; a cr-backend Backend in place of the annotations it replaces; a Global or Defaults custom resource only when the ConfigMap names it. What applies to the whole controller, such as tcp-services and the ConfigMap-only keys, is written once. Neither command drops anything silently: where a construct has no equivalent on the target you choose, it is named rather than omitted. Read the notes each run prints, keep --validate on so the output is checked against a live cluster with kubectl apply --dry-run=server, and see the full option reference and known limitations.

Additional resources