HAProxy to NGINX Ingress Migration Tool
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-snippetescape 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-configConfigMap 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
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.
- 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. - 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 itsingressClassNameto the NGINX Ingress Controller class. - Decommission: after every host has been cut over and validated, remove the HAProxy Deployment, its IngressClass, both
*.haproxy.orgCRD groups, and the CRs they managed.
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 ConfigMapnginx-config, the name the manifests install. The chart names it after the release instead (nginx-ingressfor this command) unless this is set, and NGINX Ingress Controller reads only the ConfigMap its-nginx-configmapsflag 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-snippetbecomes one, as does a deny list inside an allow list. The ConfigMap snippet keys work without it.controller.enableTLSPassthrough: off by default.ssl-passthroughbecomes a TransportServer on the built-intls-passthroughlistener, which exists only with this flag.controller.globalConfiguration.create: off by default.tcp-servicesentries and TCP custom resources become TransportServers on listeners a GlobalConfiguration declares: list them undercontroller.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).
--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.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.
| Setting | HAProxy Kubernetes Ingress Controller | NGINX Ingress Controller | What to check |
|---|---|---|---|
| Request body size | No limit | 1m (client-max-body-size) | Uploads over 1 MB get 413. Set client-max-body-size to the largest body you accept. |
| Response buffering | Streamed | On (proxy-buffering) | Server-sent events and streamed responses arrive in chunks. Set proxy-buffering: "false" for them. |
| HTTP/2 | Offered (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 timeout | 5s (timeout-connect) | 60s (proxy-connect-timeout) | An unreachable Pod is given up on later. |
| Upstream response timeout | 50s (timeout-server) | 60s (proxy-read-timeout) | A slow backend is given longer. |
| Client keep-alive idle timeout | 1m (timeout-http-keep-alive) | 75s (keepalive-timeout) | Idle client connections stay open longer. |
| WebSocket idle timeout | 1h (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 method | Round robin | random two least_conn (lb-method) | Request distribution changes. |
| Health checks | Active 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 code | 302 (ssl-redirect-code) | 301 (http-redirect-code) | Clients and caches treat the redirect as permanent. The analyzer sets 302. |
Server header | The backend's own | NGINX 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.
crds.yaml file contains all CRDs (VirtualServer, VirtualServerRoute, Policy, TransportServer, GlobalConfiguration) in a single manifest.Migration checklist
- 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.orgGlobal/Defaults/Backend/TCP/Frontend/ValidationRules, plus any on the deprecatedingress.v1.haproxy.org) and drop thecr-*pointer indirection: migrate the referenced CR's content, not the pointer - Convert
auth-secretSecrets to one htpasswd file under the keyhtpasswd(concatenate the per-user entries; the Secret can stayOpaque) - Add the CA to
client-ca/server-caSecrets underca.crt(HAProxy reads it fromtls.crt); the Secret can stayOpaque - Convert
allow-list/deny-list(and the deprecatedwhitelist/blacklistaliases) toaccessControlPolicies: 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 theallow-listrow) - Convert
rate-limit-*to arateLimitPolicy (ornginx.org/limit-req-*) and emitrejectCode: 403explicitly (NGINX Ingress Controller defaults to 503 for the Policy and 429 fornginx.org/limit-req-reject-code) - Convert
ssl-redirect/request-redirectand emit the redirect code302explicitly (NGINX Ingress Controllerhttp-redirect-code/ActionRedirect default is 301) - Re-express
route-aclcanary as VirtualServersplits[](fromrand()) andmatches[].conditions[](cookie/header/argument);src/CIDR ACLs becomeaccessControlPolicies - Convert
cookie-persistenceto VirtualServer upstreamsessionCookie(omitexpires) - Collapse the
cors-*annotations into onecorsPolicy attached vianginx.org/policies; emitmaxAgeexplicitly and enumerateallowMethods(no*) - Convert the
tcp-servicesConfigMap and TCP CRs to GlobalConfiguration listeners + TransportServers; add an SNIspec.hostfor:ssl(TLS-terminated) entries - Convert
ssl-passthroughto a TransportServer (tls-passthroughlistener) and set the-enable-tls-passthroughflag - Re-author
*-config-snippetcontent as NGINX directives (main/http/server/location context) and set-enable-snippetsfor resource snippets - Relocate Service-scoped annotations to per-Ingress annotations or the ConfigMap (NGINX Ingress Controller has no Service tier)
- Split
timeout-serverinto bothnginx.org/proxy-read-timeoutandnginx.org/proxy-send-timeout - Check each hand-written
pathType: Prefixpath: NGINX matches a plain/fooagainst/foobar, so write it as=/fooplus/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
wafPolicy (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:9113port - 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
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
- NGINX Ingress Controller Documentation
- VirtualServer Reference
- Policy Reference
- TransportServer Reference
- NGINX Ingress Controller Migration Guide
- HAProxy Kubernetes Ingress Controller Documentation
- HAProxy Kubernetes Ingress Controller Repository
- cert-manager Documentation (replaces HAProxy's generate-certificates)
HAProxy config analyzer
Paste HAProxy Kubernetes resources to get migration suggestions for NGINX Ingress Controller: an Ingress or Service with haproxy.org/ annotations, the HAProxy controller ConfigMap, or Global/Defaults/Backend/Frontend/TCP CRs (ingress.v3.haproxy.org, or the deprecated ingress.v1.haproxy.org). Multiple YAML documents separated by --- are analyzed together.
Key differences
| Aspect | HAProxy Kubernetes Ingress Controller | NGINX Ingress Controller |
|---|---|---|
| Repository | haproxytech/kubernetes-ingress | nginx/kubernetes-ingress |
| Data plane | HAProxy | NGINX Open Source or NGINX Plus |
| Annotation prefix | haproxy.org/, haproxy.com/ or ingress.kubernetes.io/ (read the same) | nginx.org/ or nginx.com/ or appprotect.f5.com/ |
| ConfigMap name | haproxy-kubernetes-ingress | nginx-config |
| CRD support | Global, Defaults, Backend, TCP, Frontend, ValidationRules (ingress.v3.haproxy.org) | VirtualServer, VirtualServerRoute, Policy, TransportServer, GlobalConfiguration |
| Enterprise support | HAProxy Enterprise (Intelligent WAF, Global Profiling Engine, Bot Management) | NGINX Plus (F5 WAF for NGINX, F5 DoS for NGINX, JWT, OIDC, active health checks, zone sync) |
*-config-snippet keys and the NGINX Ingress Controller snippet keys (main-/http-/server-/location-/stream-snippets) are escape hatches in different configuration languages. Snippet content is never copyable: every directive must be re-authored as NGINX configuration (the analyzer wraps originals in # TODO rewrite as NGINX: comments). Resource-level snippets require the -enable-snippets flag.In NGINX Ingress Controller: nginx.org/proxy-http-version and a VirtualServer upstream's proxy-http-version set the HTTP version spoken to the backend, HTTP/2 included, where a snippet was needed before. nginx.org/http2 or spec.http2 turns HTTP/2 on per host. An Opaque Secret works wherever a CA, TLS, or htpasswd Secret did. The otel-trace-context ConfigMap key can continue an incoming trace, and the use-forwarded-headers key keeps the forwarded headers a proxy in front has set. least_time last_byte load balancing is now on NGINX Open Source. cert-manager HTTP-01 challenges pass the HTTPS redirect and authentication, and -enable-topology-aware-routing sends traffic to the endpoints in the controller pod's own zone when the Service asks for it.
For HAProxy users: haproxy.org/server-proto: h2 maps to nginx.org/proxy-http-version: "2", or the same field on a VirtualServer upstream. A Frontend CR's disable_h2_upgrade maps to nginx.org/http2 on each TLS host.
In NGINX Ingress Controller: nginx.org/custom-http-errors serves intercepted errors from the Ingress's spec.defaultBackend, and nginx.org/upstream-vhost sets the Host header sent upstream. The disable-forwarded-headers ConfigMap key stops the X-Forwarded-* headers. A new hsts Policy CRD sets HSTS on a VirtualServer, including preload on request. With NGINX Plus, the new oidcNative Policy runs OpenID Connect in the built-in module and attaches to an Ingress through nginx.com/policies.
For HAProxy users: haproxy.org/set-host maps to nginx.org/upstream-vhost on an Ingress, and haproxy.org/forwarded-for: "false" to the disable-forwarded-headers ConfigMap key.
In NGINX Ingress Controller: A new externalAuth Policy CRD sends each request to an external authentication service first. The egressMTLS, externalAuth, and ingressMTLS Policies attach directly to an Ingress, and so does waf (NGINX Plus, through nginx.com/policies). nginx.org/add-header (with nginx.org/add-header-inherit) adds response headers inline, and nginx.org/proxy-redirect-from / nginx.org/proxy-redirect-to rewrite the Location header.
For HAProxy users: haproxy.org/modsecurity needs no VirtualServer, since the waf Policy attaches to an Ingress. haproxy.org/response-set-header maps to nginx.org/add-header.
In NGINX Ingress Controller: The accessControl and cors Policy CRDs attach directly to an Ingress through nginx.org/policies, with no VirtualServer.
For HAProxy users: haproxy.org/allow-list, haproxy.org/deny-list and haproxy.org/cors-enable map to Policies an Ingress can reference, and haproxy.org/ssl-redirect-code maps to nginx.org/http-redirect-code. Look for the (Recommended) tab in the mapping examples.
NGINX mappings
These features are available in both NGINX Open Source and NGINX Plus editions. All items are annotations unless otherwise indicated with a badge (e.g. ConfigMap, Policy CRD, VirtualServer CRD). HAProxy annotations use the haproxy.org/ prefix; NGINX Ingress Controller annotations use nginx.org/.
- Annotation-to-annotation rows ▶: Direct mappings where you change the annotation name/prefix. Click to expand and see before/after Ingress YAML examples.
- CRD-based rows ▶: Annotations that map to a CRD (VirtualServer, Policy, or TransportServer). Click to expand for full CRD examples with installation instructions.
- Grouped annotations: Related annotations that work together are grouped in a single expandable row, showing how they map to a unified configuration.
- NGINX Ingress Controller-only rows: Rows marked No direct equivalent on the left are features unique to NGINX Ingress Controller with no HAProxy equivalent.
Access control
| HAProxy Kubernetes Ingress Controller | NGINX Ingress Controller |
|---|---|
haproxy.org/allow-list |
Policy CRD accessControl.allow— or —nginx.org/policies New v5.4.0 |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNew in v5.4.0: AccessControl policies can be referenced directly from Ingress resources using the
nginx.org/policies annotation. This is the simplest migration path: you stay on Ingress resources.HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerBoth lists on one Ingress: HAProxy denies a client outside
allow-list or inside deny-list. A Policy's accessControl sets exactly one of allow or deny, and when a resource references an allow and a deny Policy, NGINX Ingress Controller applies only the allow list, so two Policies would silently drop the deny list. NGINX takes the first allow or deny that matches, and a location with rules of its own inherits none from its server; a Policy in spec.policies or nginx.org/policies renders at server level. So a deny in a location snippet beside such a Policy lifts the allow list for every client (verified on NGINX 1.31.7: an address outside it got 200). Put the denies first in the same location instead: on a VirtualServer, reference the allow Policy from each route's routes[].policies, which renders after that route's location-snippets (deny 10.1.2.3;); on an Ingress, which cannot place a Policy after a snippet, drop the Policy and write the whole ordered list as nginx.org/location-snippets (deny 10.1.2.3; allow 10.0.0.0/8; deny all;). Both need -enable-snippets. The analyzer does this for every deny that overlaps an allowed range; a denied range that overlaps none needs nothing, because allow-only already blocks it.Note: Policy CRDs attach to Ingress resources via
nginx.org/policies since v5.4.0 (requires the controller flag -enable-custom-resources), or to VirtualServer/VirtualServerRoute spec.policies. accessControl matches on $remote_addr; behind another proxy, set the real-ip ConfigMap keys (set-real-ip-from, real-ip-header, real-ip-recursive) so the real client IP is evaluated. When a value starts with patterns/ it references a ConfigMap pattern file; inline those CIDRs into the Policy by hand. On mergeable Ingresses it goes on the master (every path) or on a minion (that minion's paths). | |
haproxy.org/deny-list |
Policy CRD accessControl.deny— or —nginx.org/policies New v5.4.0 |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNew in v5.4.0: AccessControl policies can be referenced directly from Ingress resources using the
nginx.org/policies annotation. This is the simplest migration path: you stay on Ingress resources.HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote:
deny blocks the listed IPs/CIDRs (returning 403) and permits everything else, the inverse of allow. A Policy sets exactly one of allow/deny, and an allow Policy overrides a deny Policy on the same resource, so an Ingress that needs both is one allow list with the overlapping denies ahead of it (see the allow-list row). | |
haproxy.org/forwarded-for |
Not needed (default behavior) |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: NGINX Ingress Controller always sends
X-Forwarded-For ($proxy_add_x_forwarded_for) . forwarded-for: "true" is a no-op, so drop the annotation. For forwarded-for: "false", the ConfigMap key disable-forwarded-headers: "true" New v5.6.0 stops it, but globally: it drops X-Forwarded-Host, -Port and -Proto as well, needs -enable-snippets, and cannot be combined with use-forwarded-headers. For one VirtualServer route only, set the header to an empty value with requestHeaders.set. The annotation nginx.org/proxy-set-headers cannot disable it: the template's own X-Forwarded-For line renders after it and wins. | |
haproxy.org/src-ip-header |
ConfigMap real-ip-header + set-real-ip-from + real-ip-recursive |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: Real-IP settings are controller-global in NGINX Ingress Controller (ConfigMap), not per-Ingress: one header applies to all applications. NGINX Ingress Controller ignores
real-ip-header unless the connecting peer matches set-real-ip-from, so that key is required. With -enable-tls-passthrough on, it ignores real-ip-header altogether (the address comes from the PROXY header the passthrough listener adds): enable passthrough only if ssl-passthrough is migrated. | |
Authentication
| HAProxy Kubernetes Ingress Controller | NGINX Ingress Controller |
|---|---|
haproxy.org/auth-realm |
Policy CRD basicAuth.realm— or —nginx.org/basic-auth-realm |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote:
basicAuth is not Ingress-attachable; this Policy is referenced from a VirtualServer or VirtualServerRoute spec.policies. See the auth-secret row for the full setup.HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: HAProxy replaces every space in the realm with a dash, so
Restricted Area reached browsers as Restricted-Area, and an unset realm as Protected-Content. NGINX Ingress Controller keeps the realm as written, and with none it turns basic auth off (auth_basic ""), so always set it. See the auth-secret row for the full setup. | |
haproxy.org/auth-secret |
Policy CRD basicAuth.secret— or —nginx.org/basic-auth-secret |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerHAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerSecret must be converted: HAProxy's
auth-secret Secret is Opaque with one key per user (each value the base64 of that user's crypt(3) hash). NGINX Ingress Controller needs a single htpasswd file under the key htpasswd; since v5.7.0 the Secret can stay Opaque. Base64-decode each per-user value, join them into user:hash lines, then base64 the whole file. MD5-crypt ($1$) and apr1 ($apr1$) hashes port directly; SHA-crypt ($5$/$6$) works only where the host crypt() supports it, and plaintext is rejected on both sides.Note: The
basicAuth Policy attaches to VirtualServer/VirtualServerRoute spec.policies only; it is not Ingress-attachable via nginx.org/policies. On plain Ingress resources use the nginx.org/basic-auth-secret and nginx.org/basic-auth-realm annotations instead. Only the first basicAuth Policy reference is applied. HAProxy references the Secret as <namespace>/<name>; NGINX Ingress Controller resolves it in the Policy's own namespace, so copy the Secret over if it lived elsewhere. | |
haproxy.org/auth-type |
No direct equivalent (use basicAuth) |
HAProxy Kubernetes Ingress ControllerNGINX Ingress Controllerbasic-auth is the only value HAProxy accepts here, and there is no global basic-auth ConfigMap key in NGINX Ingress Controller. Drop auth-type: the Secret reference is what enables basic auth, through a basicAuth Policy in a VirtualServer's spec.policies, or nginx.org/basic-auth-secret and nginx.org/basic-auth-realm on an Ingress. | |
Backend TLS
| HAProxy Kubernetes Ingress Controller | NGINX Ingress Controller |
|---|---|
haproxy.org/server-ca |
Policy CRD egressMTLS.trustedCertSecret + verifyServer |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerThe CA key changes: HAProxy's
server-ca Secret carries the CA under tls.crt; NGINX Ingress Controller reads the bundle from ca.crt. Add that key; since v5.7.0 the Secret can stay Opaque, so the existing one can be reused. verifyServer defaults to false, so set it to true explicitly or the backend certificate is never verified.The name is checked too: HAProxy's
server-ca sets verify required and no verifyhost, so it checked the certificate chain only. With verifyServer, NGINX also checks the certificate's name against sslName, which defaults to $proxy_host: on a VirtualServer that is the generated upstream name (vs_<namespace>_<name>_<upstream>), which no certificate carries, so every request fails with 502. Set sslName to a name in the backend certificate's subjectAltName (the analyzer uses <service>.<namespace>.svc, the name NGINX Ingress Controller checks on an Ingress), and serverName: true if the backend needs SNI.Note:
egressMTLS only renders proxy_ssl_* directives; it does not switch the upstream to HTTPS. Pair it with nginx.org/ssl-services (see the server-ssl row) or, on VirtualServer, upstreams[].tls.enable: true. Merge server-ca and server-crt into one egressMTLS Policy for full mutual TLS. Ingress-attach is supported since v5.5.0. | |
haproxy.org/server-crt |
Policy CRD egressMTLS.tlsSecret |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote:
server-crt presents a client certificate to the backend; on its own verifyServer stays false (HAProxy verify none), so the upstream certificate is not checked. Merge with server-ca for mutual TLS. Always pair with nginx.org/ssl-services so the upstream actually uses HTTPS. | |
haproxy.org/server-proto |
VirtualServer CRD upstreams[].proxy-http-version New v5.7.0— or —nginx.org/proxy-http-version New v5.7.0 |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: The annotation applies to every backend of the Ingress. For one Service only, set
appProtocol: kubernetes.io/h2c on its port instead, which NGINX Ingress Controller reads as HTTP/2.HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNew in v5.7.0: with
proxy-http-version set to "2", NGINX speaks HTTP/2 with prior knowledge to a plain backend, as HAProxy's proto h2 does. Over TLS (with server-ssl) it offers only h2, so there is no HTTP/1.1 fallback, and WebSocket cannot use an HTTP/2 upstream. For gRPC backends use nginx.org/grpc-services instead, which needs HTTP/2 enabled on the host (the http2 ConfigMap key or nginx.org/http2), not TLS; it is master-denylisted on mergeable Ingresses, so set it on a minion. | |
haproxy.org/server-ssl |
VirtualServer CRD upstreams[].tls.enable— or —nginx.org/ssl-services |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: The annotation moves from the Service to the Ingress, and its value is the Service name rather than
"true". List several Services comma-separated.HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote:
server-ssl is HAProxy verify none, and nginx.org/ssl-services likewise does not verify the upstream certificate on its own; add an egressMTLS Policy (server-ca) for verification. HAProxy negotiates HTTP/2 to the backend over ALPN; NGINX Ingress Controller uses HTTP/1.1 unless proxy-http-version is "2" (see the server-proto row), which forces HTTP/2 instead of negotiating it. On mergeable Ingresses this is master-denylisted (minion-only). | |
haproxy.org/send-proxy-protocol |
No direct equivalent |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNo direct equivalent: sending PROXY protocol to a backend does not exist as an NGINX Ingress Controller field. NGINX implements
proxy_protocol (send) only in the stream module, so HTTP/gRPC upstreams cannot receive a PROXY header at all; a location-snippet proxy_protocol on; is invalid. For TCP/UDP services a TransportServer serverSnippets proxy_protocol on; works but emits PROXY v1 only (not streamSnippets, which renders at stream level and affects every TransportServer), so the proxy-v2, proxy-v2-ssl, and proxy-v2-ssl-cn variants are not reproducible. This is distinct from inbound proxy-protocol (accepting PROXY from a fronting load balancer), which NGINX Ingress Controller does support. | |
Configuration snippets
nginx.org/*-snippets, VirtualServer/TransportServer snippet fields) require the controller flag -enable-snippets; ConfigMap snippet keys are always available.| HAProxy Kubernetes Ingress Controller | NGINX Ingress Controller |
|---|---|
haproxy.org/backend-config-snippet |
VirtualServer CRD routes[].location-snippets— or —nginx.org/location-snippets— or —ConfigMap location-snippets |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerHAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerHAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerDifferent scope: the ConfigMap key applies to every location the controller generates, not just this Ingress. Use it only for a snippet that genuinely belongs everywhere; otherwise keep it on the Ingress.
Snippet content is not portable: HAProxy directives are not NGINX directives; the generator wraps each original line in a
# TODO rewrite as NGINX: comment, and you must translate every one. NGINX Ingress Controller does not read snippet annotations from Service objects, so a Service-scoped backend-config-snippet must move onto the Ingress (or a VirtualServer route's location-snippets field).Note: There is no per-upstream snippet context. Stick-table session persistence expressed in a backend snippet should become a VirtualServer
upstreams[].sessionCookie instead of a snippet. | |
Connection handling
| HAProxy Kubernetes Ingress Controller | NGINX Ingress Controller |
|---|---|
haproxy.org/pod-maxconn |
VirtualServer CRD upstreams[].max-conns— or —nginx.org/max-conns |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerHAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: HAProxy divides
pod-maxconn by the controller instance count automatically; NGINX Ingress Controller does not. Divide by your replica count yourself. | |
CORS
cors-enable and configures it through five more cors-* annotations. NGINX Ingress Controller folds all six into a single cors Policy attached via nginx.org/policies (Ingress-attachable) or VirtualServer spec.policies; no VirtualServer conversion is required.| HAProxy Kubernetes Ingress Controller | NGINX Ingress Controller |
|---|---|
haproxy.org/cors-allow-credentials |
Policy CRD cors.allowCredentials |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: When
allowCredentials is true, NGINX Ingress Controller validation rejects a wildcard "*" origin; enumerate explicit origins in allowOrigin instead. allowCredentials is an optional boolean and defaults to false. | |
haproxy.org/cors-allow-headers |
Policy CRD cors.allowHeaders |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: The comma-separated list becomes a YAML sequence and is joined back into the
Access-Control-Allow-Headers response header. Omit the field entirely if the annotation was unset. | |
haproxy.org/cors-allow-methods |
Policy CRD cors.allowMethods |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: NGINX Ingress Controller validates
allowMethods against a fixed seven-method set (GET, HEAD, POST, PUT, DELETE, OPTIONS, PATCH) but rejects the Policy if HEAD is listed alongside GET (browsers automatically support HEAD for any GET endpoint). There is no "*" wildcard: it expands to GET, POST, PUT, DELETE, OPTIONS, PATCH (HEAD omitted). HAProxy's CONNECT / TRACE are rejected outright; drop them. | |
haproxy.org/cors-allow-origin |
Policy CRD cors.allowOrigin |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote:
allowOrigin is required (at least one entry). NGINX Ingress Controller accepts only exact origins, a single leading-label wildcard, or "*"; there is no regex support, so a HAProxy regex origin must be enumerated as explicit origins. A wildcard "*" is rejected when allowCredentials is true. | |
haproxy.org/cors-enable |
Policy CRD cors— or —nginx.org/policies New v5.4.0 |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerHAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote:
cors-enable is the on switch; in NGINX Ingress Controller the presence of the cors Policy is the enable, so drop the key and create the Policy. All six cors-* annotations collapse into this one Policy. Referencing it from an Ingress via nginx.org/policies is new in v5.4.0, so you can migrate CORS without leaving Ingress resources. | |
haproxy.org/cors-max-age |
Policy CRD cors.maxAge |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerDefault delta: HAProxy
cors-max-age defaults to 5s while NGINX Ingress Controller maxAge defaults to 86400s (24h); always emit the value explicitly so the shorter preflight cache is preserved. The value is an integer number of seconds and renders the Access-Control-Max-Age header. | |
haproxy.org/cors-respond-to-options |
Not needed (built into cors Policy) |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerHAProxy answers the preflight with 204 only when this annotation is "true"; without it the OPTIONS request reaches the backend. Wherever a cors Policy applies, NGINX Ingress Controller answers every OPTIONS request at the edge with 204 and the CORS headers, with no way to pass preflights on. Drop the annotation, and let a backend that answered them itself stop doing so. | |
Deprecated
| HAProxy Kubernetes Ingress Controller | NGINX Ingress Controller |
|---|---|
haproxy.org/blacklist |
Policy CRD accessControl.deny— or —nginx.org/policies |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerHAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote:
blacklist is a deprecated HAProxy alias of deny-list (it logs a deprecation warning); migrate it exactly as deny-list to a single accessControl.deny Policy. | |
haproxy.org/whitelist |
Policy CRD accessControl.allow— or —nginx.org/policies |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerHAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote:
whitelist is a deprecated HAProxy alias of allow-list (it logs a deprecation warning); migrate it exactly as allow-list to a single accessControl.allow Policy. | |
Headers
| HAProxy Kubernetes Ingress Controller | NGINX Ingress Controller |
|---|---|
haproxy.org/request-set-header |
VirtualServer CRD action.proxy.requestHeaders.set— or —nginx.org/proxy-set-headers |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerRouting is unaffected: HAProxy picks the backend from the original Host and path (its
set-var rules run first), then applies request-set-header only to requests already routed to the Ingress, so a set header, Host included, never steered routing; nor does it on NGINX Ingress Controller. To override the Host header sent upstream, use the set-host row.HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote:
nginx.org/proxy-set-headers takes literal values only: NGINX Ingress Controller rejects the Ingress for a value containing $, and a HAProxy %[...] sample fetch is not NGINX syntax. A header given with no value forwards its $http_ default (e.g. X-Forwarded-ABC → $http_x_forwarded_abc). A value containing a comma also needs it, since the annotation splits entries on commas. For a value built from a variable, use the VirtualServer approach, whose values take NGINX variables in braces (%[src] becomes ${remote_addr}). To remove a request header, give it an empty value (X-Foo:): NGINX does not pass a header set to an empty string. For Host, use the set-host row. | |
haproxy.org/response-set-header |
VirtualServer CRD action.proxy.responseHeaders.add— or —nginx.org/add-header New v5.5.0 |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerReplace vs append: HAProxy
response-set-header replaces the header; NGINX add_header appends, so a header the upstream also sends would arrive twice. The migration hides the upstream's copy first (responseHeaders.hide, or nginx.org/proxy-hide-headers on an Ingress), so only the new value is sent (checked on NGINX 1.31.7).HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNew in v5.5.0: the
nginx.org/add-header annotation (and matching ConfigMap key). Values may not contain $, newlines, unescaped double quotes, a comma (it starts a new entry) or a colon (NGINX Ingress Controller reads the text after it as the always flag and rejects the Ingress); use responseHeaders.add on a VirtualServer for those. Append : always to a pair to add the header on all response codes. nginx.org/proxy-hide-headers removes an upstream response header. | |
haproxy.org/set-host |
VirtualServer CRD action.proxy.requestHeaders.set (Host)— or —nginx.org/upstream-vhost New v5.6.0 |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNew in v5.6.0:
nginx.org/upstream-vhost sets the Host header sent to the backend. NGINX Ingress Controller rejects the Ingress unless the value is a lowercase hostname with no port and no variable, so a set-host with a port takes the CRD approach.HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: Do not use
nginx.org/proxy-set-headers for Host: the generated config emits proxy_set_header Host $host after it, which wins. | |
Health checks
upstreams[].healthCheck) require NGINX Plus, so check-http, check-interval and timeout-check are mapped under Active health checks in the NGINX Plus section.| HAProxy Kubernetes Ingress Controller | NGINX Ingress Controller |
|---|---|
haproxy.org/check |
VirtualServer CRD upstreams[].max-fails— or —nginx.org/max-fails |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerHAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerChecks off: with
check: "false" HAProxy never marks a server down. NGINX Ingress Controller marks one failed after max-fails errors (default 1 in 10s) even with no probes, so set max-fails to 0 to match. check: "true", the default, needs nothing: NGINX's passive checks are already on.Passive vs active: HAProxy
check runs active TCP probes; the NGINX Ingress Controller equivalent on NGINX Open Source is passive: a server is ejected only after real client requests fail (idle backends are never probed). For a true active probe, use the NGINX Plus upstreams[].healthCheck in Active health checks. | |
Load balancing
| HAProxy Kubernetes Ingress Controller | NGINX Ingress Controller |
|---|---|
haproxy.org/cr-backend |
VirtualServer CRD upstreams[] fields |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: NGINX Ingress Controller has no resource for a pointer to name, so the Backend's fields go on the upstream of each Service it served, and the pointer is dropped. HAProxy ignored every backend annotation where a Backend applied, so
load-balance above is left out, and the analyzer says so. A cr-backend in the ConfigMap applied to every backend, so its fields go on every upstream. | |
haproxy.org/load-balance |
VirtualServer CRD upstreams[].lb-method— or —nginx.org/lb-method |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerHAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerToken map:
roundrobin → round_robin; leastconn → least_conn; source → ip_hash; uri → hash $request_uri consistent; url_param <name> → hash $arg_<name> consistent; hdr(<name>) → hash $http_<name> consistent; random / random(n) → random / random two; static-rr → round_robin (loses the static-assignment guarantee). first and rdp-cookie have no NGINX Ingress Controller equivalent; choose round_robin or least_conn. least_time header or least_time last_byte also works on NGINX Open Source since v5.7.0 (NGINX 1.31). On a TransportServer the field is upstreams[].loadBalancingMethod, not lb-method. Set in the HAProxy ConfigMap, load-balance applies to every backend: the analyzer writes it to the lb-method key of the nginx-config ConfigMap, which every upstream inherits. | |
haproxy.org/scale-server-slots |
Not applicable |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerHAProxy pre-provisions server slots for reload-free scaling. NGINX Ingress Controller re-renders and reloads (NGINX Open Source) or updates upstreams dynamically (NGINX Plus), so this knob has no counterpart; remove it. | |
haproxy.org/standalone-backend |
Not applicable |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerHAProxy builds one backend per Service and port, owned by the first Ingress to route to it (oldest, then by name). A later Ingress loses its own backend annotations to it, or gets no route at all when its ssl-passthrough differs; standalone-backend gives it a backend of its own. NGINX Ingress Controller already generates a separate upstream per Ingress or VirtualServer, so each one keeps its settings; remove the annotation. The analyzer applies the ownership rule to what it migrates, and names any setting HAProxy dropped. | |
Miscellaneous
| HAProxy Kubernetes Ingress Controller | NGINX Ingress Controller |
|---|---|
haproxy.org/abortonclose |
Not needed (default behavior) |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNGINX already aborts the upstream request when the client closes ( proxy_ignore_client_abort is off by default), as abortonclose did. Remove the annotation. Two not-applicable knobs, haproxy.org/scale-server-slots and haproxy.org/standalone-backend, are documented under Load balancing. | |
Observability
%-tokens; NGINX uses $-variables. The two are different DSLs, so log formats are re-authored, never copied. Access/stream logging and capture are all global ConfigMap settings in NGINX Ingress Controller (one HTTP format, one stream format), not per-Ingress.| HAProxy Kubernetes Ingress Controller | NGINX Ingress Controller |
|---|---|
haproxy.org/request-capturehaproxy.org/request-capture-len |
ConfigMap log-format with $http_* / $cookie_* |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: NGINX has no per-route capture slots: captured headers/cookies become
$http_*/$cookie_* variables appended to the single global log-format. There is no per-field length cap (request-capture-len has no equivalent; the full value is logged), and the req.fhdr vs hdr distinction is lost ($http_<name> is the full value). Set log-format-escaping: json for safe quoting. | |
Rate limiting
| HAProxy Kubernetes Ingress Controller | NGINX Ingress Controller |
|---|---|
haproxy.org/rate-limit-period |
Policy CRD rateLimit.rate |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNGINX has no separate rate-limit period: only r/s and r/m exist, so the period folds into the rate denominator. With rate-limit-requests: "10", a period of 1s becomes rate: 10r/s and 1m becomes rate: 10r/m (see the rate-limit-requests row). Arbitrary periods are normalized to a per-second rate and are inexact. | |
haproxy.org/rate-limit-requests |
Policy CRD rateLimit— or —nginx.org/limit-req-rate |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerHAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerBehavior differs: HAProxy rate limiting is a stick-table sliding-window counter that hard-denies once the rate is exceeded; NGINX
limit_req is a leaky bucket. HAProxy admits rate-limit-requests requests at once and denies the rest without queueing, so the burst is one less than that count with noDelay on: with rate: 10r/s, burst: 0 admitted 1 of 12 simultaneous requests on NGINX 1.31.7, and burst: 9 with noDelay admitted 10, as HAProxy does. The period folds into the rate denominator (only r/s and r/m exist), and zoneSize is a memory allocation rather than HAProxy's tracked-IP count, so both are approximate; validate under load. Always set rejectCode/limit-req-reject-code explicitly: HAProxy defaults to 403, while the Policy's rejectCode defaults to 503 and the nginx.org/limit-req-reject-code annotation defaults to 429. Cluster-wide aggregation needs NGINX Plus zone-sync (NGINX Open Source counts per pod). The rateLimit Policy is not Ingress-attachable; on a plain Ingress use the nginx.org/limit-req-* annotations. | |
haproxy.org/rate-limit-size |
Policy CRD rateLimit.zoneSize— or —nginx.org/limit-req-zone-size |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerHAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: HAProxy's
rate-limit-size is a count of tracked IP entries (default 100k); NGINX Ingress Controller's zoneSize/limit-req-zone-size is a memory allocation (roughly 16k states per 1M, so ~100k IPs → 10M). The units differ; treat the conversion as approximate. | |
haproxy.org/rate-limit-status-code |
Policy CRD rateLimit.rejectCode— or —nginx.org/limit-req-reject-code |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerHAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: Integer pass-through, but the two NGINX Ingress Controller paths have different defaults: the
rateLimit Policy's rejectCode defaults to 503, while the nginx.org/limit-req-reject-code annotation defaults to 429. HAProxy defaults to 403, so emit the code explicitly on either path to preserve the response. | |
haproxy.org/rate-limit-whitelist |
No direct equivalent |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNo direct equivalent: NGINX Ingress Controller has no rate-limit exclusion field: neither the
rateLimit Policy nor the nginx.org/limit-req-* annotations accept a whitelist. The only workaround is a ConfigMap http-snippets entry (no -enable-snippets needed: that flag gates resource snippets) that blanks the limit key for trusted CIDRs via a geo/map pair fed into nginx.org/limit-req-key, as shown. This follows the same precedent as the community controller's limit-whitelist. rate-limit-whitelist is new in HAProxy 3.2. | |
Redirects
| HAProxy Kubernetes Ingress Controller | NGINX Ingress Controller |
|---|---|
haproxy.org/request-redirect |
VirtualServer CRD routes[].action.redirect |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerDefault trap: no Ingress annotation performs a host-substitution redirect, so this converts to a VirtualServer
action.redirect. HAProxy defaults the redirect code to 302 but NGINX Ingress Controller's ActionRedirect.Code defaults to 301; the generator emits code: 302 explicitly to preserve behavior. HAProxy redirects to http:// when the value names no scheme, whatever the request used, and to https:// only when the value starts with it; write the scheme into the url. The url interpolates only ${scheme}, ${http_x_forwarded_proto}, ${request_uri}, and ${host}. | |
haproxy.org/request-redirect-code |
VirtualServer CRD action.redirect.code |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: This is not a standalone setting: it only sets the
code of the request-redirect action above. NGINX Ingress Controller restricts redirect codes to 301/302/307/308; any other HAProxy value (e.g. 303) has no equivalent and falls back to 302. | |
haproxy.org/ssl-redirect |
VirtualServer CRD spec.tls.redirect— or —nginx.org/redirect-to-https + nginx.org/ssl-redirect |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: Use
nginx.org/ssl-redirect when the controller terminates TLS, or nginx.org/redirect-to-https (which keys off X-Forwarded-Proto) when TLS ends at an upstream load balancer.HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: Both controllers default
ssl-redirect to true once the Ingress has a tls section. Use nginx.org/ssl-redirect when the controller terminates TLS, or nginx.org/redirect-to-https (which keys off X-Forwarded-Proto) when TLS ends at an upstream load balancer. VirtualServer spec.tls.redirect folds both into one field. ConfigMap twins are available. | |
haproxy.org/ssl-redirect-code |
VirtualServer CRD spec.tls.redirect.code— or —nginx.org/http-redirect-code New v5.4.0 |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerHAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNo direct equivalent: HAProxy's
303 is not in the NGINX Ingress Controller set (301/302/307/308). It falls back to 302 (the closest non-permanent, non-method-preserving code; not 301 or 308). Applies to both ssl-redirect and redirect-to-https. Set in the HAProxy ConfigMap, it becomes the http-redirect-code key of the nginx-config ConfigMap.Default trap: emit the code explicitly when
ssl-redirect is on: HAProxy ssl-redirect-code defaults to 302 while nginx.org/http-redirect-code defaults to 301, so leaving it unset silently flips the redirect to a permanent 301. | |
haproxy.org/ssl-redirect-port |
No direct equivalent |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerHAProxy redirects to ssl-redirect-port (default 8443, the port as the client sees it) without moving its listener. An Ingress redirects to the first port in nginx.org/listen-ports-ssl (default 443), and setting that also moves the listener; a VirtualServer tls.redirect sends no port at all. For a client-facing port alone, redirect plain HTTP in a VirtualServer route: match $scheme equal to http, set action.redirect to https://${host}:8443${request_uri} with code 302, and pass everything else to the backend. Without the $scheme match, the redirect also fires for HTTPS and loops. | |
Rewrites
| HAProxy Kubernetes Ingress Controller | NGINX Ingress Controller |
|---|---|
haproxy.org/path-rewrite |
VirtualServer CRD path + action.proxy.rewritePath— or —nginx.org/rewrite-target |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerHAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerHow it matches: HAProxy's
replace-path searches the path for its regex and, where it matches, replaces the whole path with the format; a request it does not match passes unchanged. The first route matches only the requests the rule rewrites (the leftmost match, as HAProxy finds it) and rewritePath takes its captures; the second carries every other request on the path. On NGINX 1.31.7, /old/a?q=1 became /new/a?q=1, /x/old/b became /new/b, and /other passed unchanged. On a path other than /, the route also checks the path in a lookahead, so it matches only that path's requests.On an Ingress: only the one-field form (
path-rewrite: /landing, which replaces the whole path) has an annotation: nginx.org/rewrite-target without nginx.org/path-regex rewrites every request of the path to it. The two-field form keeps captures from its own regex, which nginx.org/rewrite-target cannot do (it captures from the Ingress rule path), so the analyzer migrates it under CRD-first only. Multi-line rules, which HAProxy applies in turn, become one rewrite: fold them into the first by hand. | |
Routing
| HAProxy Kubernetes Ingress Controller | NGINX Ingress Controller |
|---|---|
kubernetes.io/ingress.class |
Ingress spec.ingressClassName |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: Move the class to
spec.ingressClassName. HAProxy Kubernetes Ingress Controller v3.2.19 never reads the kubernetes.io/ingress.class annotation: it treated such an Ingress as classless. NGINX Ingress Controller does read it, and it overrides spec.ingressClassName, so remove it. NGINX Ingress Controller requires an IngressClass named after its -ingress-class flag (spec.controller nginx.org/ingress-controller) to exist (it fails to start otherwise), and Ingresses must match it exactly (no classless fallthrough). | |
pathType(Exact / Prefix / ImplementationSpecific) |
VirtualServer CRD routes[].path |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerHAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerHAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: NGINX matches a plain
/foo prefix against /foobar, and HAProxy's Prefix did not, so Prefix becomes two routes, =/foo and /foo/. Exact becomes =/foo, and ImplementationSpecific stays a plain /foo prefix, which HAProxy also matched against /foobar. A trailing slash is dropped first, as HAProxy does. A migrated Ingress gets the same split, an Exact path /foo and a Prefix path /foo/, because NGINX Ingress Controller renders Prefix as a plain prefix too.Regex paths: NGINX Ingress Controller's regex engine is PCRE, and HAProxy's
-m reg differs on anchoring and lookaround; verify complex patterns after migrating. | |
spec.defaultBackend |
Ingress spec.defaultBackend |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerScope changes: HAProxy makes an Ingress's
spec.defaultBackend the default backend of its HTTP and HTTPS frontends, so every request no rule matches, on any host, goes there; when several Ingresses set one, the Ingress lowest by namespace and name wins. NGINX Ingress Controller uses it only for that Ingress's own hosts, as their / when no path covers it, and answers every other unmatched request from its default server with 404. It also rejects an Ingress with no rules, so a cluster-wide fallback is a host-less rule, as above, with -allow-empty-ingress-host. There is no --default-backend-service flag equivalent. (The separate -default-server-tls-secret flag is a TLS concern, not routing.) | |
Wildcard host *.example.com |
VirtualServer CRD spec.host— or —Ingress spec.rules[].host |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerHAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: Leading-label wildcards (
*.example.com) port unchanged. NGINX Ingress Controller, like HAProxy, does not support mid-label or bare-suffix wildcards, and spec.host must be single and unique across Ingress and VirtualServer resources. | |
| Several Ingresses on one host | VirtualServer CRD spec.routes[]— or —Ingress spec.rules[].http.paths[] |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: Each Ingress keeps its own upstreams, so the
timeout-server above stays with api, as in HAProxy, and its Policies go on its own routes. HAProxy matches exact paths first, then the longest prefix, which NGINX does whatever order the routes are in. HAProxy redirected HTTP to HTTPS only for web, the Ingress with TLS; the VirtualServer redirects every path.HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerSettings become host-wide: In one Ingress, only the per-Service annotations (
nginx.org/ssl-services, nginx.org/grpc-services, nginx.org/websocket-services, nginx.org/rewrites, nginx.org/sticky-cookie-services) stay with the Service they name. Every other setting covers every path, so the timeout-server above, set only on api, applies to web too, where HAProxy kept it to api's paths. The analyzer names each setting that changes scope. To keep them per Ingress, use the VirtualServer approach, where each Ingress keeps its own upstreams.One host, one resource: HAProxy serves every Ingress from one frontend, routing by host and path maps, and applies each Ingress's settings to its own paths only. NGINX Ingress Controller gives a host to one resource and rejects a second that claims it, so the analyzer merges the Ingresses of a host into one. A path two Ingresses route goes, as in HAProxy, to the backend whose name sorts first. An Ingress that routes several hosts is split into one per host first.
A resource per team: NGINX Ingress Controller can also delegate a host's paths to VirtualServerRoutes, or to mergeable minion Ingresses under a master, and NGINX Gateway Fabric attaches several HTTPRoutes to one Gateway listener. Each gives a team a resource of its own, and each needs setting up with the result in mind. The analyzer does not emit them.
| |
Session persistence
| HAProxy Kubernetes Ingress Controller | NGINX Ingress Controller |
|---|---|
haproxy.org/cookie-persistence |
VirtualServer CRD upstreams[].sessionCookie— or —nginx.org/sticky-cookie-services |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerHAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: HAProxy inserts a session cookie with no
Expires; the VirtualServer sessionCookie likewise omits expires by default, so the sticky cookie lasts for the browser session. NGINX Ingress Controller stores an opaque hashed server identifier (cross-replica-safe), but HAProxy's dynamic-cookie-key has no NGINX Ingress Controller knob. HAProxy deprecates cookie-persistence at Ingress scope (moot after moving to the VirtualServer upstream above). | |
haproxy.org/cookie-persistence-no-dynamic |
VirtualServer CRD upstreams[].sessionCookie |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: Migrates exactly like
cookie-persistence. The only difference: HAProxy's no-dynamic mode writes the literal server name as the cookie value, whereas NGINX Ingress Controller always uses an opaque hashed identifier, functionally equivalent (and arguably more secure); the raw-name mode is not reproducible. Mutually exclusive with cookie-persistence. | |
TCP services
TCP CRD or the legacy --configmap-tcp-services ConfigMap. NGINX Ingress Controller uses TransportServer resources bound to TCP listeners defined once per cluster in a GlobalConfiguration (referenced via the -global-configuration <namespace>/<name> flag). L4 content-switching/ACL rules do not port.| HAProxy Kubernetes Ingress Controller | NGINX Ingress Controller |
|---|---|
| No direct equivalent | TransportServer CRD protocol: UDP + GlobalConfiguration CRD |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNGINX Ingress Controller-only capability: UDP load balancing is a migration gain: HAProxy Kubernetes Ingress Controller has no UDP ingress path, so DNS/syslog/etc. can move onto NGINX Ingress Controller. A UDP TransportServer forbids
spec.host; tune udpRequests/udpResponses to the datagrams your protocol exchanges per session. Active UDP health checks require NGINX Plus; NGINX Open Source checks passively. | |
Timeouts
ms/s/m/h/d) pass through; HAProxy Kubernetes Ingress Controller's parser has no us, so 5us is an error and the default applies; bare HAProxy integers are milliseconds and are converted to an NGINX time string (e.g. 5000 → 5s).| HAProxy Kubernetes Ingress Controller | NGINX Ingress Controller |
|---|---|
haproxy.org/timeout-server |
VirtualServer CRD upstreams[].read-timeout + upstreams[].send-timeout— or —nginx.org/proxy-read-timeout + nginx.org/proxy-send-timeout |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerHAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: One HAProxy
timeout-server governs both directions; NGINX splits it into proxy_read_timeout and proxy_send_timeout (each default 60s). Set both: mapping only one silently leaves the other at 60s. ConfigMap and VirtualServer twins are available. | |
TLS & certificates
| HAProxy Kubernetes Ingress Controller | NGINX Ingress Controller |
|---|---|
haproxy.org/ssl-passthrough |
TransportServer CRD protocol: TLS_PASSTHROUGH |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: TLS passthrough becomes a separate
TransportServer (SNI-routed, spec.host required, spec.tls forbidden). HAProxy reads ssl-passthrough per path, from the Service the path routes to first, then the Ingress, then the ConfigMap, and keys the route on the host alone, so a host with one passthrough path sends all its TLS there. NGINX Ingress Controller gives a host to one resource, so such a host is the TransportServer; another host of the same Ingress stays a VirtualServer. Like HAProxy, which needs a host for a passthrough route, NGINX Ingress Controller has no catch-all SNI route; enable the feature with -enable-tls-passthrough (port via -tls-passthrough-port).What still applies: HAProxy enforces
allow-list and deny-list on passthrough traffic, and the backend's load-balance, pod-maxconn and timeout-server. They carry over: the access lists as the TransportServer's serverSnippets (the -enable-snippets flag; a TransportServer takes no Policy), the rest as loadBalancingMethod, maxConns and sessionParameters.timeout. The HTTP annotations do not apply to this traffic. | |
| No direct equivalent | Controller flag -enable-cert-manager + VirtualServer CRD spec.tls.cert-manager |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNGINX Ingress Controller-only integration: neither controller ships a built-in ACME client, but NGINX Ingress Controller integrates with cert-manager for automatic certificate issuance (
-enable-cert-manager + spec.tls.cert-manager). Pre-issue certificates before cutover: HAProxy's generate-certificates on-the-fly signing has no equivalent. | |
Traffic splitting
route-acl injects a raw use_backend rule (first match wins, config order) with no weight field; canary is expressed purely as an ACL. NGINX Ingress Controller uses declarative VirtualServer splits[] (percentages) or matches[] (conditions). Only a small set of portable ACL primitives convert.| HAProxy Kubernetes Ingress Controller | NGINX Ingress Controller |
|---|---|
haproxy.org/route-acl |
VirtualServer CRD routes[].splits / matches |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNo direct equivalent for raw ACL strings: only a fixed set of primitives converts.
src/CIDR ACLs become a Policy accessControl (allow XOR deny): a gate, not a canary router; if two backends must serve different CIDRs, split them across hostnames. base / general path regex beyond NGINX Ingress Controller's match variables has no equivalent; re-express the intent with VirtualServer matches or split hostnames.Note: HAProxy
route-acl rules fire in config order (first match wins); NGINX Ingress Controller splits are declarative percentages, so the conversion assumes this is the only routing rule for the path. Other portable primitives map to matches[].conditions: cookie(NAME)/req.cook(NAME) → cookie: NAME ($cookie_NAME), urlp(NAME) → argument: NAME ($arg_NAME), hdr(NAME) -m str V → {header: NAME, value: V}, and method GET → {variable: $request_method}. | |
NGINX Plus mappings
HAProxy's commercial tier (HAProxy Enterprise) adds WAF, the Global Profiling Engine, and Bot Management (a commercial-to-commercial comparison). These map to NGINX Plus policies in NGINX Ingress Controller (F5 WAF for NGINX, F5 DoS for NGINX, distributed rate limiting via zone-sync). Some features of the community HAProxy Kubernetes Ingress Controller also land here, because a row belongs to this section whenever its NGINX Ingress Controller equivalent needs NGINX Plus, whatever surface it came from. Active health checks and request queueing are both that case, so their annotation, ConfigMap and CRD rows are mapped below rather than in NGINX mappings and ConfigMap mappings, which cross-reference them.
Active health checks
haproxy.org/check → max-fails + fail-timeout) is mapped under Health checks.| HAProxy Kubernetes Ingress Controller | NGINX Ingress Controller |
|---|---|
default_server.check / httpchk_params (Backend CRD) |
VirtualServer CRD NGINX Plus upstreams[].healthCheck |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNGINX Plus: active backend probes (
check/httpchk) require NGINX Plus: VirtualServer upstreams[].healthCheck. On NGINX Open Source, use passive ejection via max-fails + fail-timeout. The two are not equivalent: passive ejection only reacts to real traffic failing, so a dead backend stays in rotation until a request hits it. | |
haproxy.org/check-http |
VirtualServer CRD NGINX Plus upstreams[].healthCheck |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNGINX Plus only: the active HTTP probe maps to
upstreams[].healthCheck, which requires NGINX Plus. Only the URI ports: the request method (probes are GET-only) and any HTTP/x.y version token are dropped. On NGINX Open Source there is no HTTP-status probe; fall back to the passive haproxy.org/check row under Health checks. | |
haproxy.org/check-interval |
VirtualServer CRD NGINX Plus healthCheck.interval |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote:
interval (default 5s) is meaningful only for the active (Plus) probe. It sets how often the probe fires (distinct from fail-timeout, which governs passive ejection). | |
haproxy.org/timeout-check |
VirtualServer CRD NGINX Plus healthCheck.read-timeout |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: HAProxy's post-connect
timeout check maps to the active probe's read-timeout (Plus). There is no NGINX Open Source equivalent: passive health has no probe timeout. | |
Enterprise features
controller.mgmt.licenseTokenSecretName), and for the WAF and DoS modules the -enable-app-protect and -enable-app-protect-dos flags.modsecurity row). Their settings are HAProxy configuration, and it reaches a cluster two ways, both shown in the examples. Directives that belong inside a section the controller generates travel in the global-config-snippet and frontend-config-snippet ConfigMap keys, because a second file cannot reopen a section the controller already wrote. Whole new sections travel in a secondary config file mounted at /etc/haproxy/haproxy-aux.cfg, which the controller loads alongside its own generated config, watches for changes, and never rewrites. Running the controller in external mode puts all of it back into one config file you own. So there is something to inventory in the cluster (two ConfigMaps and a volume mount), but nothing that names the feature, and the contents are HAProxy's configuration language, which is re-authored rather than translated.| HAProxy Kubernetes Ingress Controller | NGINX Ingress Controller |
|---|---|
Bot Management |
NGINX Plus F5 DoS for NGINX app-protect-dos-resource |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerDifferent mechanism: HAProxy Enterprise Bot Management has no Ingress annotation, ConfigMap key or CRD field, so it arrives as raw configuration: the profile section through the mounted haproxy-aux.cfg, the per-frontend lines through frontend-config-snippet. Mount the aux ConfigMap with subPath: haproxy-aux.cfg so it lands as a file rather than a directory. The botmgmt-profile section and botmgmt-evaluate are named in HAProxy Enterprise's release notes; the profile's own fields are portal-documented, so treat the body on the left as a placeholder. F5 DoS for NGINX provides behavioral DDoS and automated-traffic protection, not fingerprint-based bot scoring, and its interactive-challenge (CAPTCHA) counterpart has no NGINX equivalent (see the CAPTCHA and Fingerprint rows). F5 WAF for NGINX bot signatures cover a further slice.F5 DoS for NGINX is enabled per Ingress with the appprotectdos.f5.com/app-protect-dos-resource annotation (for example "default/my-app-dos"), backed by a DosProtectedResource CRD whose spec you author to match the protected object. It requires NGINX Plus. | |
Global Profiling Engine |
ConfigMap NGINX Plus zone-sync |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerClosest analogue: NGINX Plus zone synchronization (the
zone-sync ConfigMap keys) shares the rate-limit and key-value zones NGINX Ingress Controller generates across controller pods (built into the Plus data plane with no extra component). It has no equivalent for GPE's threat-scoring or bot-metrics collection (a scope mismatch). TLS-protected zone sync is only possible via the stream-snippets ConfigMap key. | |
Global Rate Limiting |
Policy CRD NGINX Plus rateLimit + ConfigMap zone-sync |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: Cross-replica aggregation requires the NGINX Plus
zone-sync ConfigMap keys (zone-sync, zone-sync-port default 12345, zone-sync-resolver-addresses, zone-sync-resolver-valid, zone-sync-resolver-ipv6): keys, not CLI flags. On NGINX Open Source each pod limits independently, as HAProxy's pods did; the Policy's scale: true or nginx.org/limit-req-scale: "true" divides the rate by the replica count to approximate one cluster-wide limit. The rateLimit Policy is not Ingress-attachable; on plain Ingress use nginx.org/limit-req-*. The key accepts ${binary_remote_addr}, ${request_uri}, ${uri}, ${args}, ${request_method} and arg_ / cookie_ / http_ / jwt_claim_ / apikey_-prefixed variables; ${host} is not allowed. See Rate limiting for the single-pod mapping. The mypeers/request_rates tables the HAProxy rules read are declared in the aux config file (see the Global Profiling Engine row above). | |
Intelligent WAF |
Policy CRD NGINX Plus waf |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: There is no configuration to import: it is a different engine, so re-author and re-tune the policy against F5 WAF for NGINX (see the
modsecurity row). No dedicated HAProxy Ingress annotation was located, so this collapses into the same waf Policy mapping. Requires NGINX Plus. | |
haproxy.org/modsecurity |
Policy CRD NGINX Plus waf via nginx.com/policies New v5.5.0 |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerRules are not portable: HAProxy Enterprise ModSecurity rules (
SecRule / OWASP CRS) cannot be imported: F5 WAF for NGINX uses its own declarative policy model (an APPolicy CRD or a compiled policy bundle). Re-author and re-tune the ruleset from scratch, and set the enforcement mode explicitly: HAProxy ships detection-only by default. This is NGINX Plus + F5 WAF for NGINX only (there is no WAF on NGINX Open Source), and the controller must run with -enable-app-protect, or every waf Policy is rejected.Note: Attach the
waf Policy via nginx.com/policies on an Ingress, or from VirtualServer / VirtualServerRoute spec.policies; it is rejected on nginx.org/policies. apPolicy, apBundle and apBundleSource New v5.6.0 are mutually exclusive (set at most one); apLogConf pairs only with apPolicy, and apLogBundle or apLogBundleSource only with a bundle. There is no securityLogBundle field. NGINX Ingress Controller has no cluster-wide modsecurity toggle; attach the Policy per Ingress or VirtualServer. You can also enable F5 WAF for NGINX directly with the appprotect.f5.com/ annotations (app-protect-enable, app-protect-policy, app-protect-security-log-enable, app-protect-security-log, app-protect-security-log-destination). | |
UDP module |
TransportServer CRD protocol: UDP + GlobalConfiguration CRD |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNo NGINX Plus needed: UDP load balancing is the one enterprise-labeled HAProxy module NGINX Ingress Controller covers on NGINX Open Source. Neither side uses a host. Requires the controller to run with
-global-configuration and custom resources enabled. Active UDP health checks are NGINX Plus; passive checks work on NGINX Open Source. | |
CAPTCHA module |
Not planned |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNGINX Ingress Controller has no CAPTCHA or JavaScript-challenge construct. F5 WAF for NGINX and F5 DoS for NGINX can detect and block or rate-limit automated traffic, but cannot serve an interactive challenge. On the HAProxy side there is no annotation, ConfigMap key or CRD field either: the captcha section is declared in the mounted haproxy-aux.cfg, and its section name comes from a third-party parser of Enterprise configuration rather than the (portal-only) module reference, so treat the keys as a placeholder. | |
Fingerprint module |
No direct equivalent |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNGINX Ingress Controller has no Ingress-level TLS/JA3 client fingerprinting. The HAProxy side has no Ingress construct either (the module's section is declared in the mounted haproxy-aux.cfg and its per-frontend lines arrive through frontend-config-snippet), so there is no annotation, ConfigMap key or CRD field to carry across. | |
ConfigMap mappings
HAProxy's controller ConfigMap keys map to the NGINX Ingress Controller's global nginx-config ConfigMap. These settings apply controller-wide, not per application.
Client mTLS & PROXY protocol
spec.policies) or per Ingress (nginx.org/policies), and PROXY protocol acceptance is a global ConfigMap boolean. Apply each to every host that needs it.| HAProxy Kubernetes Ingress Controller | NGINX Ingress Controller |
|---|---|
client-ca |
Policy CRD ingressMTLS.clientCertSecret |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: HAProxy
client-ca Secrets carry the CA under tls.crt; NGINX Ingress Controller reads the bundle from ca.crt (optional CRL under ca.crl). Add that key; since v5.7.0 the Secret can stay Opaque. Requires TLS termination on the host: on a host without TLS, NGINX Ingress Controller rejects the Policy and the whole host answers 500. Verification failures return HTTP 400 (not 500). On mergeable Ingress it must sit on the master. Ingress-attachable since v5.5.0.Note: Scope shift: HAProxy configures client mTLS controller-wide (ConfigMap); NGINX Ingress Controller's
ingressMTLS attaches per VirtualServer (spec.policies) or per Ingress (nginx.org/policies, since v5.5.0), so apply the Policy to every host that needs it. On mergeable Ingresses it must sit on the master. | |
client-crt-optional |
Policy CRD ingressMTLS.verifyClient |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: Polarity: HAProxy defaults to enforced (
false). Map false → verifyClient: "on", true → verifyClient: "optional". Do not use optional_no_ca (it skips CA verification; HAProxy still verifies against client-ca when optional). verifyDepth defaults to 1 on both sides. client-crt-optional applies only beside client-ca: without a CA, HAProxy asks for no certificate at all. | |
client-strict-sni |
Controller flag -default-server-tls-secret unset |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerThere is no user-facing strict-SNI toggle in NGINX Ingress Controller: rejecting unknown SNI follows from the absence of a default server certificate, and it is controller-global, not per Ingress. Leave the -default-server-tls-secret controller flag unset, and NGINX answers an unknown SNI with ssl_reject_handshake. To serve a fallback certificate instead (client-strict-sni: false), set -default-server-tls-secret to a Secret of type kubernetes.io/tls. | |
proxy-protocol |
ConfigMap proxy-protocol + real-ip-header + set-real-ip-from |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: Incoming/client-side only. NGINX Ingress Controller enables PROXY protocol globally for all listeners; it cannot restrict acceptance to specific source IPs (HAProxy returns 400 if a listed source IP connects without sending the PROXY header). Every connection reaching NGINX must then send a PROXY header.
set-real-ip-from only scopes which peers' PROXY headers are trusted for the client IP. This is the inbound counterpart of send-proxy-protocol (outbound), which has no HTTP equivalent. | |
Configuration snippets
# TODO rewrite as NGINX: comment. ConfigMap snippet keys (main-/http-/server-/location-/stream-snippets) are always on; the -enable-snippets flag gates only resource snippets.| HAProxy Kubernetes Ingress Controller | NGINX Ingress Controller |
|---|---|
frontend-config-snippet |
ConfigMap server-snippets + http-snippets |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerContent not copyable:
server-snippets applies inside every server block. Per-application scoping uses nginx.org/server-snippets on the Ingress (-enable-snippets).Note: HAProxy frontend
http-request/http-response rules and ACLs have no 1:1 server-context equivalent; re-express each as native NGINX Ingress Controller constructs (Policies, VirtualServer matches) where possible before falling back to a snippet. | |
global-config-snippet |
ConfigMap main-snippets / http-snippets (native ssl-* keys preferred) |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: Route
ssl-default-bind-* directives to native ConfigMap keys (ssl-ciphers, ssl-protocols, ssl-prefer-server-ciphers, ssl-dhparam-file) and reserve main-snippets / http-snippets for directives with no native key (tune.*, ssl_ecdh_curve, and similar). | |
stats-config-snippet |
No direct equivalent |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNGINX Ingress Controller on NGINX Open Source has no stats frontend to inject configuration into, and the HAProxy stats page has no equivalent. Scrape Prometheus /metrics instead (-enable-prometheus-metrics, port 9113) into Grafana; the live activity dashboard is NGINX Plus only. stats auth ... has no equivalent. | |
Connection handling
| HAProxy Kubernetes Ingress Controller | NGINX Ingress Controller |
|---|---|
http-connection-mode |
ConfigMap keepalive + keepalive-timeout |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: No single toggle: the mode splits into upstream keep-alive (the
keepalive count, off by default) and client keep-alive (keepalive-timeout, on by default). http-server-close maps to keepalive: "0" (a VirtualServer's default; an Ingress would keep 32 idle upstream connections); httpclose maps to keepalive-timeout: "0". | |
maxconn |
ConfigMap worker-connections |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerApproximate: HAProxy
maxconn is process-wide; NGINX worker-connections is per-worker and counts client + upstream + internal connections. Effective capacity → worker-connections × worker-processes. Divide accordingly. | |
nbthread |
ConfigMap worker-processes |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerApproximate: HAProxy runs threads in one process; NGINX scales with multiple worker processes. The count transfers, the model differs. Leave it unset (or
auto) to match CPU count. | |
Deprecated
http-connection-mode and log a deprecation warning at v3.2.19. Migrate them as that key does, under Connection handling.| HAProxy Kubernetes Ingress Controller | NGINX Ingress Controller |
|---|---|
http-keep-alive |
ConfigMap keepalive |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote:
http-keep-alive is a deprecated HAProxy alias of http-connection-mode (it logs a deprecation warning). Upstream keep-alive is a connection count. NGINX Ingress Controller leaves it at 0, so a VirtualServer closes each upstream connection and an Ingress falls back to NGINX's own default of 32 idle connections per worker; set it explicitly for either. | |
http-server-close |
VirtualServer default; ConfigMap keepalive: "0" for an Ingress |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote:
http-server-close is a deprecated HAProxy alias of http-connection-mode. Its effect is client keep-alive on, the server connection closed after each response. That is a VirtualServer's default; an Ingress on NGINX 1.31.7 keeps upstream connections alive by default, so set keepalive: "0" where the server side must close. | |
Global & lifecycle
| HAProxy Kubernetes Ingress Controller | NGINX Ingress Controller |
|---|---|
clean-certs |
Not applicable |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNGINX Ingress Controller loads certificates from Secrets and manages its own storage, so there are no certificate files to clean up. Remove the key. | |
hard-stop-after |
ConfigMap worker-shutdown-timeout |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: Semantic delta: HAProxy caps the whole-process soft-stop; NGINX Ingress Controller's
worker_shutdown_timeout caps how long an old worker may drain after a reload. It is a reload/drain analogue, not a request timeout. Carry the value explicitly (NGINX Ingress Controller's default of 0 means indefinite). | |
Logging
| HAProxy Kubernetes Ingress Controller | NGINX Ingress Controller |
|---|---|
log-format |
ConfigMap log-format |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerHand-translation required: HAProxy
%-tokens are a different DSL from NGINX $-variables (%ci → $remote_addr, %ST → $status, %Tr → $upstream_response_time); never copy them verbatim. Several HAProxy timers (%Tw/%Tc/%Ta) have no NGINX variable. log-format is global (one HTTP format). | |
log-format-tcp |
ConfigMap stream-log-format |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerHand-translation required: tcplog tokens become NGINX stream
$-variables (%ci:%cp → $remote_addr:$remote_port, %B → $bytes_sent). stream-log-format applies globally to all TransportServer traffic (not per TCP service). HAProxy reads log-format-tcp only from the tcp-services ConfigMap; in the controller ConfigMap it does nothing, and TCP custom resources set their own format. | |
syslog-server |
ConfigMap access-log (syslog: destination) |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: Access log only: there is no ConfigMap key to send the NGINX error log to syslog (only
error-log-level controls its verbosity). Single destination (no multi-server fan-out); HAProxy format/length/minlevel fields have no equivalent. NGINX Ingress Controller ignores any access-log value that does not start with syslog:. If HAProxy logged to stdout, that is already the NGINX Ingress Controller default; leave it unset. | |
dontlognull |
No direct equivalent |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerThere is no option dontlognull analogue, but it is generally moot: the NGINX HTTP access log records completed requests only, so connection probes without a request are not logged anyway. Remove the annotation. | |
logasap |
No direct equivalent |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNGINX has no early-log ( option logasap) toggle: it writes the access-log entry when the request completes, so a long download appears in the log only once it finishes. Remove the annotation. | |
TCP services
tcp-services ConfigMap both become a GlobalConfiguration TCP listener plus a TransportServer per entry. The listener port must be pre-declared in the single GlobalConfiguration (-global-configuration <ns>/<name>) and exposed on the controller Service. L4 content-switching/ACL rules do not port (streamSnippets only).--configmap-tcp-services flag that names it.| HAProxy Kubernetes Ingress Controller | NGINX Ingress Controller |
|---|---|
tcp-services entry with :ssl |
TransportServer CRD spec.tls.secret |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: HAProxy ended TLS on the port with the certificates it already loaded for its HTTPS frontend. A TransportServer ends it with the
kubernetes.io/tls Secret in spec.tls.secret, in its own namespace, and needs no spec.host; add one only to tell apart several TransportServers on one listener. This ends TLS at the controller; to pass it through to the backend, see ssl-passthrough. | |
Timeouts
s to bare millisecond counts (5000 → 5s).| HAProxy Kubernetes Ingress Controller | NGINX Ingress Controller |
|---|---|
timeout-client |
ConfigMap http-snippets |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNo direct equivalent: NGINX Ingress Controller has no first-class ConfigMap key for client-side inactivity timeouts (confirmed absent). The
http-snippets escape hatch above approximates it with the raw NGINX directives; ConfigMap snippet keys are always available (the -enable-snippets flag only gates resource snippets). | |
timeout-connect |
ConfigMap proxy-connect-timeout |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: Direct equivalent (global default; override per resource with
nginx.org/proxy-connect-timeout or VirtualServer upstreams[].connect-timeout). HAProxy defaults to 5s but NGINX defaults to 60s, so emit the value explicitly to preserve behavior. | |
timeout-http-keep-alive |
ConfigMap keepalive-timeout |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: Governs the client keep-alive idle timeout only. It does not control upstream keep-alive; that is the separate
keepalive ConfigMap key (a connection count). See Connection handling. | |
timeout-http-request |
ConfigMap http-snippets |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNo direct equivalent: NGINX has no single "whole request" timeout directive.
client_header_timeout (via http-snippets) is the closest analogue (approximate, not exact). | |
timeout-queue |
VirtualServer CRD NGINX Plus upstreams[].queue |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNGINX Plus only: request queueing when every server is at
max-conns exists only in NGINX Plus: VirtualServer upstreams[].queue ({size, timeout}, timeout default 60s vs HAProxy's 5s), paired with max-conns. NGINX Open Source has no request queue; excess requests fail fast instead. The queue is a per-upstream VirtualServer field, so a single global HAProxy timeout-queue becomes one queue block per upstream that needs it. | |
timeout-tunnel |
ConfigMap proxy-read-timeout + proxy-send-timeout |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: NGINX Ingress Controller has no dedicated tunnel timeout: raising the proxy read/send timeouts affects every upstream, not just long-lived connections. WebSocket is automatic for VirtualServer; on a plain Ingress it additionally needs
nginx.org/websocket-services naming the Service. | |
timeout-client-fin |
No direct equivalent |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNGINX has no half-closed (FIN_WAIT) client-side connection timeout. Remove the annotation. | |
timeout-server-fin |
No direct equivalent |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNGINX has no half-closed (FIN_WAIT) server-side connection timeout. Remove the annotation. | |
TLS & certificates
spec.tls or VirtualServer spec.tls.secret.| HAProxy Kubernetes Ingress Controller | NGINX Ingress Controller |
|---|---|
generate-certificates-signer |
No direct equivalent |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerHAProxy's on-the-fly per-connection certificate signing (new in HAProxy 3.2) has no NGINX Ingress Controller analogue. Pre-issue certificates instead with cert-manager, which provisions real Secrets; name the issuer in a VirtualServer's spec.tls.cert-manager.cluster-issuer. | |
quic-alt-svc-max-age |
Not supported |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNGINX Ingress Controller has no QUIC or HTTP/3 support, so drop the key. | |
ssl-certificate |
Controller flag -default-server-tls-secret |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: The cluster default certificate is a deployment flag, not a per-object annotation. Multi-algorithm Secrets (
rsa.*/ecdsa.*/dsa.* keys) are not supported; use one kubernetes.io/tls certificate per Secret. | |
tls-alpn |
ConfigMap http2 (HTTP/2 on/off only) |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: Only the HTTP/2 dimension maps. The
http2 ConfigMap key turns HTTP/2 on for every host, over TLS and as cleartext h2c on the default listeners; nginx.org/http2 (Ingress) or spec.http2 (VirtualServer) overrides it per host New v5.7.0. Note the polarity flip: HAProxy advertises h2 by default, NGINX Ingress Controller has HTTP/2 off by default. Arbitrary ALPN protocol lists cannot be reproduced. | |
WAF
| HAProxy Kubernetes Ingress Controller | NGINX Ingress Controller |
|---|---|
modsecurity |
Policy CRD NGINX Plus waf on each resource |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: The ConfigMap key turned ModSecurity on for every Ingress. NGINX Ingress Controller has no cluster-wide WAF switch, so the analyzer attaches the
waf Policy to each VirtualServer or migrated Ingress. The rules do not carry over: see the haproxy.org/modsecurity row for re-authoring them and for what the Policy needs. | |
CRD mappings
Each HAProxy CR lands in a different place in NGINX Ingress Controller, and the tables below map its fields one by one:
- Backend: VirtualServer
upstreams[]fields, or the matchingnginx.org/*annotations. A TCP-mode Backend becomes a TransportServer upstream. - Defaults:
nginx-configConfigMap keys for timeouts, logging and connections. - Frontend (v3 only): GlobalConfiguration listeners and controller flags for its binds, ConfigMap keys for protocol and TLS defaults, and
server-snippetsfor raw directives. - Global:
nginx-configConfigMap keys for the process and TLS (worker-processes,ssl-protocols). - TCP: a GlobalConfiguration listener per port and a TransportServer per entry.
- ValidationRules: no direct equivalent, since NGINX Ingress Controller cannot define new annotations.
NGINX Ingress Controller has no resource for a cr-* pointer to name, so drop the pointer and migrate the CR it names. The tables use the ingress.v3.haproxy.org/v3 field paths. HAProxy deprecated the ingress.v1.haproxy.org/v1 Backend, Defaults, Global and TCP resources in 3.2, and its controller binary converts them to v3 (--input-file / --output-file); the analyzer reads both.
HAProxy Backend CRD
spec; on the deprecated v1 group they sit under spec.config, with spec.acls and spec.http-requests alongside. TCP-mode Backends migrate to a TransportServer (see TCP services).haproxy.org/cr-backend annotation, which names a Backend, under Load balancing.adv_check, httpchk_params and default_server.check/inter/rise/fall under Active health checks, since active probes require NGINX Plus.| HAProxy Kubernetes Ingress Controller | NGINX Ingress Controller |
|---|---|
balance |
VirtualServer CRD upstreams[].lb-method |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote:
first and rdp-cookie have no NGINX Ingress Controller equivalent (drop + warn). | |
connect_timeout / server_timeout |
VirtualServer CRD upstreams[].connect-timeout / read-timeout + send-timeout |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: int64 milliseconds → NGINX time. One HAProxy
server_timeout maps to both read-timeout and send-timeout; set both, or the one you leave out silently keeps NGINX's 60s default. | |
cookie |
VirtualServer CRD upstreams[].sessionCookie |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: The cookie name maps to
sessionCookie.name with enable: true. See Session persistence for the raw-name caveat. | |
default_server (maxconn / ssl / verify / sni) |
VirtualServer CRD upstreams[].max-conns + nginx.org/ssl-services / upstreams[].tls |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote:
maxconn → max-conns; ssl/verify/sni → nginx.org/ssl-services + VirtualServer upstream tls/egressMTLS (see the Backend TLS rows). ExternalName-backed upstreams and server_templates (DNS) are NGINX Plus. | |
retries / redispatch |
VirtualServer CRD upstreams[].next-upstream-tries + next-upstream |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote:
retries → next-upstream-tries plus one: HAProxy counts the retries after the first attempt, NGINX every attempt (verified on NGINX 1.31.7); retry_on → next-upstream: conn-failure and empty-response are error, response-timeout is timeout, junk-response is invalid_header, and status codes are http_403, http_404, http_429 and http_5xx; 401, 408, 421, 425, 501 and 0rtt-rejected have no NGINX condition. retry_on replaces HAProxy's default conn-failure rather than adding to it, and NGINX's default is "error timeout". redispatch is what next-upstream always does: the retry goes to another server. | |
acl_list / http_request_rule_list / server_switching_rule_list / stick_table |
No direct equivalent |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNo direct equivalent: ACLs,
http-request/http-response, and switching rules do not port as data; re-express as VirtualServer matches, Policies, or (last resort) snippets. Plain stick-table persistence becomes sessionCookie; other stick tables have no equivalent. Only path- and header-shaped ACLs translate this cleanly: anything sampling connection state or rates has no NGINX Ingress Controller construct at all. | |
HAProxy Defaults CRD
client-body-size field: the HAProxy Defaults CRD has no request-body-size field; do not map anything here to NGINX Ingress Controller's client-max-body-size. Drop the cr-defaults ConfigMap pointer and migrate the CR's contents into the NGINX Ingress Controller ConfigMap (defaults that per-resource annotations may override).spec; on the deprecated v1 group the same fields sit under spec.config. Every Defaults timeout is an int64 in milliseconds → NGINX time (5000 → 5s).| HAProxy Kubernetes Ingress Controller | NGINX Ingress Controller |
|---|---|
balance |
ConfigMap lb-method |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote:
roundrobin → round_robin, leastconn → least_conn, source → ip_hash. See the Backend CRD / load-balance rows for the full value map; first and rdp-cookie have no equivalent. | |
connect_timeout |
ConfigMap proxy-connect-timeout |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: int64 milliseconds → NGINX time. Direct equivalent, but set it explicitly, because the NGINX default (60s) is twelve times HAProxy's (5s).
| |
http_keep_alive_timeout |
ConfigMap keepalive-timeout |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: Client keep-alive idle timeout (NGINX Ingress Controller default 75s). Does not govern upstream keep-alive.
| |
httplog / log_format |
ConfigMap log-format |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerHand-translation required: HAProxy
%-tokens must be rewritten as NGINX $-variables (see the Logging row). tcplog maps to stream-log-format the same way. | |
server_timeout |
ConfigMap proxy-read-timeout + proxy-send-timeout |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: One HAProxy timeout governs both directions; set both
proxy-read-timeout and proxy-send-timeout, or the unset one silently stays at NGINX's 60s default. | |
tcplog |
ConfigMap stream-log-format |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: Stream (TCP/UDP) access-log format: hand-translate the tcplog tokens to NGINX stream
$-variables. It applies to all TransportServer traffic, not one service. | |
client_timeout / http_request_timeout |
ConfigMap http-snippets |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNo direct equivalent: NGINX Ingress Controller has no first-class client-side timeout key; use
http-snippets with client_header_timeout (the closest analogue). Idle client keep-alive belongs on keepalive-timeout. ConfigMap snippet keys are always available; the -enable-snippets flag only gates resource snippets. | |
forwardfor |
Not needed (default behavior) |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote:
X-Forwarded-For is automatic in NGINX Ingress Controller (both templates emit $proxy_add_x_forwarded_for); drop the field. Emitting the header and trusting one are different settings: the second is the real-IP pair above, and NGINX ignores real-ip-header unless the peer matches set-real-ip-from. | |
mode |
http: VirtualServer CRDtcp: TransportServer CRD |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerThere is no mode key: the resource kind decides. mode: http is an Ingress or a VirtualServer; mode: tcp is a TransportServer and a GlobalConfiguration listener (see the TCP services rows). | |
redispatch |
nginx.org/proxy-next-upstream |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: Retrying on another server is per-resource in NGINX Ingress Controller; there is no global ConfigMap key. Default
nginx.org/proxy-next-upstream is "error timeout". | |
retries |
nginx.org/proxy-next-upstream-tries |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: Retries are per-resource in NGINX Ingress Controller:
nginx.org/proxy-next-upstream-tries (or VirtualServer upstreams[].next-upstream-tries). No global ConfigMap key. It counts every attempt, the first included, where HAProxy's retries counts only the retries, so add one. | |
queue_timeout / tunnel_timeout / *_fin_timeout / check_timeout / compression / error_files |
No direct equivalent |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNo direct equivalent: the tarpit and
*-fin timeouts and check_timeout have no NGINX Ingress Controller key. tunnel_timeout is the proxy timeouts, which also cover every other request, so a 1h value keeps WebSockets but also lets a hung backend hold a request an hour: set it per VirtualServer upstream (read-timeout, send-timeout) where you can. queue_timeout is the NGINX Plus upstreams[].queue.timeout, rejected on NGINX Open Source; compression uses http-snippets (gzip, no ConfigMap key); error_files becomes per-route VirtualServer errorPages. See the per-topic reference tables for guidance. | |
HAProxy Frontend CRD (v3-only)
server-snippets. A misconfigured listener can take down every application behind the controller; test the decomposition in pre-production first.| HAProxy Kubernetes Ingress Controller | NGINX Ingress Controller |
|---|---|
binds (address / port) |
GlobalConfiguration CRD spec.listeners[]— or —Controller flag -default-http-listener-port / nginx.org/listen-ports |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerHAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote:
nginx.org/listen-ports is per-Ingress and needs a host on the rule: it is not supported on an Ingress without one; use the -default-http-listener-port command-line argument for that case.Note: Hosts listen on 80 and 443 unless moved: an Ingress by
nginx.org/listen-ports / -ssl, a VirtualServer by naming a GlobalConfiguration listener (the GlobalConfiguration referenced by -global-configuration <ns>/<name>) in spec.listener. -default-http-listener-port / -default-https-listener-port move only the catch-all default server. A listener may not take 80, 443, or a port the controller uses itself (stub_status 8080, metrics 9113, service insight 9114, while each is on). Expose the ports on the controller Service. | |
ssl / ssl_certificate |
VirtualServer CRD spec.tls.secret |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: Listener TLS moves to the application resource's
spec.tls (Ingress spec.tls[].secretName or VirtualServer spec.tls.secret): NGINX Ingress Controller has no listener-level certificate binding. A filesystem certificate path has no equivalent either: the certificate must be a Secret. | |
accept_proxy |
ConfigMap proxy-protocol |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: Accepting PROXY protocol is the global
proxy-protocol: "true" ConfigMap key (see Client mTLS & PROXY protocol). It cannot be scoped to one listener, so every port starts expecting a PROXY header: anything still connecting directly breaks. | |
httplog / log_target_list |
ConfigMap log-format / access-log |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: Listener logging becomes the global
log-format / access-log ConfigMap keys; hand-translate the tokens (see Logging). Per-listener logging does not survive the move: one format and one destination cover the whole controller. | |
http_request_rule_list / http_response_rule_list |
ConfigMap server-snippets |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerContent not copyable: frontend
http-request/http-response rules become server-snippets; rewrite each by hand. Prefer native NGINX Ingress Controller constructs (Policies, VirtualServer matches) first. | |
disable_h2_upgrade |
nginx.org/http2 New v5.7.0 |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerPartial:
disable_h2_upgrade keeps h2 over TLS and refuses only the cleartext upgrade. NGINX Ingress Controller does the same when the http2 ConfigMap key stays off and nginx.org/http2 (or VirtualServer spec.http2) turns HTTP/2 on for each TLS host. | |
binds alpn / no_alpn |
No direct equivalent |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNGINX Ingress Controller has no ALPN advertisement control: no ConfigMap key, annotation or CRD field sets the protocol list. HTTP/2 on TLS is nginx.org/http2 or VirtualServer spec.http2 per host (see disable_h2_upgrade above). Test any client that depends on a particular ALPN list after migrating. | |
binds quic-* / quic_initial_rule_list |
Not supported |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNGINX Ingress Controller has no QUIC or HTTP/3 support, so drop the QUIC binds and their options ( quic-cc-algo, quic-force-retry, quic-socket, quic_cc_algo_burst_size, quic_cc_algo_max_window) and the frontend's quic_initial_rule_list, and any UDP port they used on the Service. | |
HAProxy Global CRD
cr-global ConfigMap pointer. NGINX Ingress Controller has no CR indirection; migrate the referenced CR's content.ingress.v3.haproxy.org/v3 inlines fields under spec. On the deprecated ingress.v1.haproxy.org/v1 the same fields sit under spec.config (Global also carries spec.log_targets) and migrate to the same NGINX Ingress Controller ConfigMap keys.| HAProxy Kubernetes Ingress Controller | NGINX Ingress Controller |
|---|---|
cpu_maps / cpu_set / cpu_policy |
ConfigMap worker-cpu-affinity |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerApproximate: the NGINX CPU-affinity bitmask format (e.g.
"0001 0010") differs from HAProxy's cpu-map; translate the pinning manually. The analyzer emits a # TODO placeholder. | |
hard_stop_after / grace |
ConfigMap worker-shutdown-timeout |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: int64 milliseconds → NGINX time. Caps old-worker drain after a reload (approximate analogue of HAProxy's whole-process soft-stop cap).
| |
log_target_list |
ConfigMap access-log + error-log-level |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: Log targets become the
access-log key (syslog: destination only); NGINX error-log verbosity is set by error-log-level. There is no error-log-to-syslog key. One destination only: NGINX Ingress Controller ignores any access-log value that does not start with syslog:. | |
maxconn |
ConfigMap worker-connections |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerApproximate:
worker-connections is per-worker where HAProxy maxconn is process-wide; divide by worker-processes. | |
nbthread |
ConfigMap worker-processes |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerApproximate: the count transfers, but NGINX scales with processes, not threads.
auto is supported. | |
ssl_options.default_bind_ciphers |
ConfigMap ssl-ciphers |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: Direct equivalent: the OpenSSL cipher string ports verbatim.
| |
ssl_options.default_bind_options |
ConfigMap ssl-protocols (+ ssl-prefer-server-ciphers) |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: One HAProxy string mixes protocol floors with independent flags, so it splits across several NGINX Ingress Controller keys: the protocol versions become
ssl-protocols (an explicit list, not a floor), prefer-client-ciphers inverts to ssl-prefer-server-ciphers: "false", and the remaining bind flags have no key at all (snippet or drop). | |
ssl_options.dh_param_file |
ConfigMap ssl-dhparam-file |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNot a path: despite the key name,
ssl-dhparam-file takes the contents of the DH parameter file: NGINX Ingress Controller writes them to disk itself and points ssl_dhparam at the file it created. A HAProxy filesystem path carries over as a value that NGINX Ingress Controller will treat as PEM and NGINX will reject, so paste the parameters instead. | |
ulimit_n |
ConfigMap worker-rlimit-nofile |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: Direct equivalent: the per-worker open-file limit.
| |
runtime_apis / stats socket / tune.* / set_var |
No direct equivalent |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNo direct equivalent: re-express via
main-snippets / http-snippets where NGINX has an equivalent directive, otherwise drop; runtime APIs, the stats socket, and tune.* knobs have no analogue. | |
daemon / master-worker / pidfile / user / group / chroot |
Not applicable |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNothing to migrate: the NGINX Ingress Controller image already runs NGINX in master/worker mode as an unprivileged user, and no ConfigMap key or flag exposes these fields, or uid, gid, localpeer and default_path. Process identity is a pod concern instead, set in the Deployment's spec.template.spec.containers[].securityContext (runAsUser: 101, the nginx user, and runAsNonRoot: true). | |
HAProxy TCP CRD
spec[] entry is a listener plus a backend, so it splits in two: the listener is declared once per cluster on the GlobalConfiguration, and each entry becomes its own TransportServer.| HAProxy Kubernetes Ingress Controller | NGINX Ingress Controller |
|---|---|
spec[] (one entry per listener) |
TransportServer CRD + GlobalConfiguration CRD |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNo direct equivalent for L4 rules: TransportServer has no ACL / content-switching / tcp-request fields (
acl_list, backend_switching_rule_list, tcp_request_rule_list, capture_list, filter_list); the only escape hatch is spec.streamSnippets (-enable-snippets). Extra services[] on one entry have no routing mechanism; each backend needs its own listener + TransportServer.Note: The GlobalConfiguration port must be exposed on the controller Service. For SSL offload (a bind with
ssl: true), add spec.tls.secret (a kubernetes.io/tls Secret in the TransportServer namespace). NGINX Ingress Controller terminates TLS over TCP from the Secret alone, so spec.host is not required (add an SNI spec.host only to differentiate multiple TransportServers sharing one listener). Per-service TCP logs collapse into the global stream-log-format. | |
HAProxy ValidationRules CRD
| HAProxy Kubernetes Ingress Controller | NGINX Ingress Controller |
|---|---|
spec (whole CR) |
No direct equivalent |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerThe ValidationRules CRD (and its --custom-validation-rules / --enable-custom-annotations-on-ingress flags) has no analog: NGINX Ingress Controller has a fixed annotation vocabulary and no CEL or template custom-annotation framework. Migrate what each custom annotation set to the annotation, VirtualServer field or Policy that covers it. The validation and templating layer is lost. | |
Controller flag mappings
HAProxy controller command-line flags and their NGINX Ingress Controller equivalents. These are deployment-time settings, set on the controller Deployment rather than on an Ingress.
Controller CLI flags
args), not config resources. NGINX Ingress Controller flag names differ from HAProxy's; direct maps are listed first, then partial maps, then flags with no equivalent.args block below is spec.template.spec.containers[].args on the controller Deployment: haproxy-kubernetes-ingress in namespace haproxy-controller, nginx-ingress in namespace nginx-ingress. Watch the dash count: HAProxy flags are --flag=value, NGINX Ingress Controller's are -flag=value. $(POD_NAMESPACE) is the downward-API variable NGINX Ingress Controller's own manifests use.| HAProxy Kubernetes Ingress Controller | NGINX Ingress Controller |
|---|---|
--configmap |
Controller flag -nginx-configmaps <ns>/<name> |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: Same syntax, but NGINX Ingress Controller has no default ConfigMap (unset by default) and the keys differ entirely. NGINX Ingress Controller fails to start if the named ConfigMap is missing.
| |
--configmap-errorfiles |
VirtualServer CRD routes[].errorPages[] |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: No flag equivalent: custom error responses become per-route VirtualServer
errorPages (structured return/redirect, not raw HTTP files). See the Error Handling reference. One controller-wide ConfigMap becomes a block repeated on every route that needs it. Behaviour changes too: HAProxy's errorfiles replace only the errors HAProxy itself generates, while errorPages turn on proxy_intercept_errors for the route, so an application's own response with a listed code is replaced as well. On an Ingress, nginx.org/custom-http-errors New v5.6.0 is the alternative: it sends the listed codes to the Ingress's spec.defaultBackend, so the pages come from a Service you run rather than from inline bodies. | |
--configmap-tcp-services |
GlobalConfiguration CRD + TransportServer CRD |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: No flag equivalent: each entry becomes a GlobalConfiguration TCP listener + TransportServer (see TCP services). The ports must also be exposed on the controller Service.
| |
--default-ssl-certificate |
Controller flag -default-server-tls-secret <ns>/<name> |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote:
-default-server-tls-secret is the default-server cert (unmatched SNI); -wildcard-tls-secret is a per-host fallback cert. Unset with no fallback → ssl_reject_handshake. | |
--disable-config-snippets |
Controller flag -enable-snippets (inverse polarity) |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: Inverse polarity: HAProxy disables per-kind and is on by default; NGINX Ingress Controller's
-enable-snippets is off by default and all-or-nothing for resource snippets. ConfigMap snippets are always on. | |
--disable-ingress-status-update |
Controller flag -report-ingress-status left out (Helm controller.reportIngressStatus.enable=false) |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: The binary's default is off, but NGINX Ingress Controller's manifests pass
-report-ingress-status -external-service=nginx-ingress, and the Helm chart sets controller.reportIngressStatus.enable: true, so an install updates status unless you turn it off as above. | |
--disable-ipv6 |
Controller flag -disable-ipv6 |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: Like-for-like: same name, one dash. This is the only one of HAProxy's protocol toggles with an NGINX Ingress Controller counterpart (there is no
-disable-ipv4). | |
--http-bind-port |
Controller flag -default-http-listener-port (default 80) |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerOnly the default server moves: HAProxy's
--http-bind-port moves the HTTP listener every route uses. -default-http-listener-port moves only the catch-all default_server and host-less Ingresses: every Ingress host keeps listening on 80 unless nginx.org/listen-ports moves it, and a VirtualServer stays on 80 unless it names a GlobalConfiguration listener in spec.listener. So the pod still binds 80 (the manifests grant NET_BIND_SERVICE), and a controller Service targeting 8080 reaches only the default server, which answers 404. Point the Service at 80, or move each host. | |
--https-bind-port |
Controller flag -default-https-listener-port (default 443) |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerOnly the default server moves: like the HTTP flag,
-default-https-listener-port moves only the catch-all default_server. Ingress hosts keep 443 unless nginx.org/listen-ports-ssl moves them, and VirtualServers keep 443 unless they name a GlobalConfiguration listener in spec.listener. A controller Service targeting 8443 reaches only the default server. | |
--ingress.class |
Controller flag -ingress-class <name> (default nginx) |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: You must also deploy an IngressClass named
<name> (spec.controller nginx.org/ingress-controller) or NGINX Ingress Controller fails to start. | |
--log |
Controller flag -log-level <level> + -log-format (glog|text|json) |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: Keep
warning. The levels NGINX Ingress Controller sets are trace/debug/info/warning/error/fatal: -log-level=warn matches none of them and runs at info. At startup it also prints "Invalid log level: warning … Falling back to default: info", which is wrong: the level stays warning. Controls the controller log, not the data plane; NGINX's own verbosity is the error-log-level ConfigMap key. | |
--namespace-whitelist |
Controller flag -watch-namespace <a,b>— or —Controller flag -watch-namespace-label |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerHAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: Collapse repeated flags into one comma list.
-watch-namespace XOR -watch-namespace-label. Secrets: -watch-secret-namespace. | |
--prometheus |
Controller flag -enable-prometheus-metrics + -prometheus-metrics-listen-port (9113) |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: The
/metrics path is the same; the port differs (HAProxy's 6060 controller port → NGINX Ingress Controller's dedicated 9113). Metric names differ (nginx_ingress_* vs haproxy_*); rebuild dashboards. Optional TLS via -prometheus-tls-secret. Remember the scrape annotations or ServiceMonitor that pointed at the old port. | |
--publish-service |
Controller flag -external-service <svc> (+ -report-ingress-status) |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNote: Drop the namespace prefix (the Service lives in the controller namespace).
-external-service XOR -ingresslink (BIG-IP); or use the external-status-address ConfigMap key. Also reports VirtualServer/VirtualServerRoute status. One HAProxy flag becomes two: the reporting switch and the address source are separate on NGINX Ingress Controller. | |
--disable-service-external-name |
Not needed (default behavior) |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerPartial: NGINX Ingress Controller on NGINX Open Source never resolves ExternalName upstreams (that is NGINX Plus only), so the flag's hardening posture is already NGINX Ingress Controller's default; there is no cluster toggle. On NGINX Plus the capability is opt-in per Service, not cluster-wide.
| |
--empty-ingress-class |
No direct equivalent |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerPartial: VirtualServer/VirtualServerRoute/TransportServer always process an empty class; Ingress requires an explicit
ingressClassName (no classless opt-in). Do not conflate with -allow-empty-ingress-host. Any Ingress that relied on this flag is silently unrouted after the move until you add the field. | |
--enable-custom-annotations-on-ingress |
No direct equivalent |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerThe flag turns on the custom annotations a ValidationRules CR defines, which render into HAProxy configuration. NGINX Ingress Controller reads a fixed set of annotations and has no way to define new ones, so drop the flag and migrate what each custom annotation set: most settings have an annotation, a VirtualServer field or a Policy of their own in the tables above. | |
--namespace-blacklist |
No direct equivalent (use Controller flag -watch-namespace) |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerPartial: NGINX Ingress Controller only allowlists (by name or label); there is no "watch all except X". A label selector is the scalable substitute. The polarity flips with it: a namespace created later is watched by HAProxy and ignored by NGINX Ingress Controller.
| |
--cache-resync-period |
No direct equivalent |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerThe shared informer resync period is not exposed as a flag in NGINX Ingress Controller. Drop it; there is nothing to carry over. | |
--channel-size |
No direct equivalent |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNGINX Ingress Controller's internal event buffers are not configurable. To reduce how many objects the controller tracks, scope it with -watch-namespace or -watch-namespace-label instead. | |
--configmap-patternfiles |
No direct equivalent |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNo direct equivalent: NGINX Ingress Controller has no pattern-file indirection; inline the literal CIDRs/values at each reference site (accessControl Policy allow/deny lists). One shared list becomes as many copies as there were references, and they no longer update together.
| |
--default-backend-port |
No direct equivalent |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNo direct equivalent: set the port on the catch-all Ingress's backend. HAProxy keeps its own controller endpoints (Prometheus, pprof) on the separate
--controller-port (6060) and this backend port at 6061; NGINX Ingress Controller splits its endpoints across three ports instead: status 8080, metrics 9113, readiness 8081. | |
--default-backend-service |
No direct equivalent |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNo direct equivalent: no NGINX Ingress Controller flag routes unmatched traffic to a Service; deploy a host-less catch-all Ingress (it must have a rule: NGINX Ingress Controller rejects an Ingress with only
spec.defaultBackend), with -allow-empty-ingress-host on. NGINX Ingress Controller's default server returns 404. | |
--disable-http |
No direct equivalent |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNo direct equivalent: there is no global disable-HTTP flag; enforce HTTP→HTTPS per resource (
redirect-to-https/ssl-redirect) or don't expose port 80 at the Service level. A redirect is not a closed port: NGINX still listens and answers. | |
--disable-https |
No direct equivalent |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNo direct equivalent: no global disable-HTTPS flag; don't configure TLS or don't expose 443 (NGINX still configures an HTTPS default_server).
| |
--disable-ipv4 |
No direct equivalent |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNo direct equivalent: NGINX Ingress Controller has
-disable-ipv6 but no symmetric -disable-ipv4; shape IPv4 at the Service/network level. | |
--disable-quic / --quic-announce-port / --quic-bind-port |
Not supported |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNGINX Ingress Controller has no QUIC or HTTP/3 support, so there is nothing to bind, announce or turn off. Drop all three, and any UDP/443 port they needed on the Service. | |
--disable-writing-only-if-reload |
Not applicable |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNot applicable: this is a HAProxy file-write optimization with no NGINX Ingress Controller counterpart.
| |
--external / --program / --config-dir / --runtime-dir |
Not supported |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNGINX Ingress Controller always runs in-cluster, with NGINX in the same pod, and has no external mode. --program, --config-dir and --runtime-dir work only in that mode, so drop all four. -proxy runs the controller against a kubectl proxy for local testing only, not in production. | |
--gateway-controller-name |
No direct equivalent (see NGINX Gateway Fabric) |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNo direct equivalent: NGINX Ingress Controller has no Gateway API support; the Gateway API implementation is NGINX Gateway Fabric, a separate product. HAProxy's support is experimental and TCPRoute only; NGINX Gateway Fabric is HTTPRoute-first. This is a re-platform, not a flag map.
| |
--input-file / --output-file |
Not applicable |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerThis pair runs HAProxy's v1-to-v3 CRD converter as a one-shot utility. NGINX Ingress Controller has no conversion tool: the CRD mappings tables are the conversion. Drop both flags. | |
--ipv4-bind-address / --ipv6-bind-address |
No direct equivalent |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerThe default HTTP and HTTPS listeners, and every Ingress, bind all addresses ( 0.0.0.0 and IPv6). Constrain reachability outside the controller instead: a Service (type, ipFamilies, loadBalancerIP), or hostNetwork with a nodeSelector. -disable-ipv6 drops IPv6 entirely. A GlobalConfiguration listener does take an ipv4 and ipv6 address, for the VirtualServers and TransportServers that name it. | |
--job-check-crd |
No direct equivalent |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerThere is no run-and-exit check mode: CRDs are installed before the controller starts, as manifests ( kubectl apply -f deploy/crds.yaml) or by the Helm chart. See Installing CRDs for the version-pinned command. | |
--pprof |
No direct equivalent |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNo direct equivalent: NGINX Ingress Controller has no pprof/Go-profiling endpoint (confirmed absent); use
-log-level=debug/trace for diagnostics. | |
--sync-period |
No direct equivalent |
HAProxy Kubernetes Ingress ControllerNGINX Ingress ControllerNo direct equivalent: NGINX Ingress Controller is event-driven (informers), not polling. The closest (different) knobs are
-nginx-reload-timeout, -enable-config-safety, and -ssl-dynamic-reload. | |