We're announcing HAProxy Kubernetes Ingress Controller 3.4, bringing dynamic server management to applications that scale in Kubernetes.
Built on HAProxy 3.4, this release creates and removes endpoint servers at runtime, keeping backend server pools aligned with changes in the Kubernetes cluster. It also supports more controlled configuration through custom resource definitions (CRDs) and helps shared controllers recover from rejected resources.
Read the full release notes for the complete list of changes.
HAProxy Enterprise Kubernetes Ingress Controller 3.4 is coming soon with exclusive enterprise features.
What is HAProxy Kubernetes Ingress Controller?
HAProxy Kubernetes Ingress Controller is a free, open-source product providing high-performance Kubernetes-native application routing for the Ingress API. It supports HTTP/S and TCP (via CRD), and is built on HAProxy's legendary performance, flexibility, and reliability. Additionally, it provides a low-risk migration path to Gateway API via the HAProxy Unified Gateway.
New in HAProxy Kubernetes Ingress Controller 3.4
Feature | Benefit |
|---|---|
Dynamic server management | Create and remove backend servers at runtime as application endpoints change. |
Custom-resource-led configuration | Replace raw config snippets with supported custom resources or validated user-defined annotations. |
Invalid custom-resource isolation | Set aside a rejected resource and retry it after an edit. Keep other valid configuration changes moving. |
HAProxy 3.4 core | Improved performance and reliability, with greater configuration flexibility. |
Dynamic server management for Kubernetes
Kubernetes applications add or remove pods as demand changes; backend server pools need to follow those endpoints as applications grow or shrink.
Version 3.4 creates and deletes endpoint servers through the HAProxy Runtime API as pods appear or disappear. The controller also records those servers in its generated configuration, keeping the file aligned with runtime changes.
Endpoint management becomes part of your application's existing scaling workflow. Backend server pools grow and shrink with Kubernetes endpoints, without operators preallocating server slots.
The HAProxy Runtime API documentation explains runtime server creation. These operations manage servers within existing backends.
Customization with structured configuration
Custom resources give teams a structured way to configure application traffic, while resource-level error handling helps keep valid changes moving when a resource is rejected.
Build on custom resources and user-defined annotations
Previously, version 3.2 introduced user-defined annotations and Frontend custom resources; version 3.4 continues that configuration direction by removing raw config snippets.
Use supported custom resources or validated user-defined annotations for customization. For example, a Backend custom resource can hold supported backend settings alongside the Kubernetes resources that use them.
User-defined annotations let administrators define configuration templates and validation rules for application teams. This capability already exists and predates version 3.4.
The benefit is a more controlled way to expose supported HAProxy settings. You can check each snippet's behavior against its replacement rather than assuming every raw directive has a direct equivalent.
Recover from invalid custom resources
A shared controller may serve applications owned by several teams. Resource-specific recovery helps each team manage its configuration while other valid updates continue.
The controller can now set aside the rejected resource and retry synchronization without it. Other valid changes can proceed while the resource owner corrects the problem. Editing the resource triggers another attempt automatically.
Logs identify the rejected resource, and a Prometheus gauge exposes its rejected generation:
haproxy_rejected_custom_resource_generation{kind,namespace,name}
This gives operators a resource-specific signal for alerting and troubleshooting. It's recovery from a failed configuration check, rather than a replacement for validation.
While a resource is set aside, its customization is not applied: depending on the resource, configuration can fall back to annotations or omit its listeners. We recommend reviewing the rejection before assuming that the resource's intended policy is in effect.
Built on HAProxy 3.4
HAProxy Kubernetes Ingress Controller 3.4 uses the HAProxy 3.4 core and its default random algorithm, based on Power of Two Random Choices. It selects two servers at random and chooses the less-loaded one, an approach that has demonstrated better performance and fairer load distribution across uneven servers.
Existing policies configured through a Backend custom resource or the load-balance annotation remain unchanged. If you relied on the implicit round-robin default, configure roundrobin explicitly in a Backend custom resource before upgrading.
The load-balance annotation remains functional in version 3.4, but is deprecated and will be removed in version 3.6.
Scale centralized operations with HAProxy One
HAProxy Kubernetes Ingress Controller serves the free, in-cluster use case. Enterprises that need centralized control and application security across a larger deployment have a separate path through HAProxy One.
Coming with HAProxy Fusion 2.1, enterprises will be able to centrally manage Ingress and Gateway API resources using HAProxy Enterprise as the data plane. In that model, HAProxy Fusion reads those Kubernetes resources and configures a managed HAProxy Enterprise fleet from a central control plane.
HAProxy Enterprise adds an integrated web application firewall (WAF), bot management, and global rate limiting.
HAProxy Fusion provides fleet-wide load balancer management and observability. Together, HAProxy Fusion and HAProxy Enterprise support external load balancing for Kubernetes and multi-cluster routing.
HAProxy Edge supplies the platform's secure edge network.
This enterprise operating model combines Kubernetes routing with centralized security and management across your deployment.
Deprecations and breaking changes
Deprecated: Configuration annotations
Annotations superseded by custom resources are deprecated but remain functional in version 3.4—emitting deprecation notices. Their removal is planned for version 3.6.
Where a supported replacement exists, move the setting into the corresponding custom resource. Check the documented replacement for each setting; some annotations don't yet have a direct equivalent.
Deprecated: SSL passthrough
The ssl-passthrough annotation is deprecated but still functional in version 3.4. Its removal is planned for version 3.6. Check the supported migration procedure before changing workloads that depend on it.
Breaking change: Config snippets
Config snippets are removed in version 3.4. This breaking change affects global-config-snippet, frontend-config-snippet, stats-config-snippet, and backend-config-snippet, and we've also removed the --disable-config-snippets startup argument.
Migrate each supported setting to a custom resource or validated user-defined annotation, then check the generated configuration before upgrading.
Breaking change: Default load balancing algorithm
Version 3.4 inherits HAProxy's random default when no balancing policy is explicitly configured. Existing Backend custom resource settings and load-balance annotations remain effective. To retain the previous round-robin default, configure roundrobin explicitly in a Backend custom resource before upgrading.
Breaking change: Server-slot annotations
The server-slots, scale-server-slots, and servers-increment annotations are ignored in version 3.4 and produce warnings. Although the warnings describe deprecation, their behavior has already changed: these settings no longer control server allocation.
We consider this a breaking change for deployment automations that rely on slot sizing. Dynamic server management follows application endpoints instead.
Breaking change: Backend server-switching rules
The Backend custom resource no longer accepts server_switching_rule_list in version 3.4. This is a breaking change. We suggest reviewing and adapting configurations that currently use these rules to target individual servers before upgrading.
Breaking change: Experimental Gateway API integration
Version 3.4 removes the controller's experimental Gateway API integration. This is a breaking change for deployments using that integration.
Users who require Gateway API can migrate to HAProxy Unified Gateway, a separate open-source controller that supports both Gateway API and Ingress. Since version 1.0, HAProxy Unified Gateway has been out of beta and ready for production workloads. See the announcement of HAProxy Unified Gateway 1.1 for the latest features.
Review resource compatibility and deployment requirements before redirecting traffic. The Ingress controller continues to support Ingress routing and TCP through its own custom resources.
Feature or setting | Status in 3.4 | Replacement or action
|
|---|---|---|
Configuration annotations superseded by custom resources | Deprecated, still functional; removal planned for version 3.6 | Use the documented custom-resource replacement where available. |
| Deprecated, still functional; removal planned for version 3.6 | Plan migration before the removal release. |
Config snippets and | Breaking change, removed | Migrate supported settings to custom resources or validated user-defined annotations. |
Default load balancing algorithm | Breaking change for deployments without an explicit policy | Configure |
Server-slot annotations | Breaking change, ignored | Use dynamic server management; remove reliance on slot-sizing settings. |
Backend | Breaking change, removed | Adapt rules that target individual servers. |
Experimental Gateway API integration | Breaking change, removed | Migrate Gateway API workloads to a compatible HAProxy Unified Gateway release. |
Try HAProxy Kubernetes Ingress Controller
Review the breaking changes and deprecations before upgrading to version 3.4, particularly if your deployment uses config snippets or experimental Gateway API support:
Existing installations: follow the community upgrade instructions. Helm updates CRDs during upgrade;
kubectlinstallations require the documented CRD update procedure.New installations: choose Helm or kubectl, or follow the installation guide for your environment.
The Helm chart version and controller version are separate. Check the chart's appVersion and any image-tag override to confirm that you're deploying the intended version 3.4 release.
Test migrated configuration before directing production traffic to the updated controller. The configuration reference describes all supported settings and custom resources.
Next steps
We welcome feedback and contributions through the community project on GitHub. Tell us how dynamic server management works in your deployment, or report configuration cases that need attention.
Thank you to everyone who contributes code and helps test the controller.
Looking to simplify your Kubernetes traffic management while boosting performance? Download our free e-book, Unified Kubernetes, to explore a consistent model for high-speed routing, edge security, and fleet-wide observability.
