Supported HAProxy Configuration¶
This document provides an overview of HAProxy configuration sections and child components supported by HAPTIC via the HAProxy Dataplane API.
Overview¶
The controller supports all configuration sections that can be managed through the HAProxy Dataplane API. Configuration changes are applied using fine-grained operations to minimize HAProxy reloads and maximize use of the Runtime API for zero-downtime updates.
API Version Support: The controller supports Dataplane API versions 3.0, 3.1, and 3.2. The API version is auto-detected at runtime.
HAProxy Editions: Both HAProxy Community and HAProxy Enterprise are supported. Enterprise-only features are automatically detected and enabled when connected to an Enterprise instance.
Coverage:
- 15 main configuration sections (global, defaults, frontends, backends, etc.)
- 23 child component types across frontends and backends (servers, ACLs, rules, etc.)
- 12 Enterprise-only sections (WAF, bot management, UDP load balancing, etc.)
- Complete Dataplane API compatibility - All manageable resources are supported
Supported Configuration Sections¶
| Section | Description | Priority | Implementation |
|---|---|---|---|
| Global | Global HAProxy settings (singleton) | 5 | Update only |
| Defaults | Default settings for proxies | 8 | Create/Update/Delete |
| Frontends | Frontend proxy definitions | 20 | Create/Update/Delete |
| Backends | Backend server pools | 30 | Create/Update/Delete |
| Peers | Peer sections for stick-table replication | 10 | Create/Update/Delete |
| Resolvers | DNS resolver configurations | 10 | Create/Update/Delete |
| Mailers | Email alert configurations | 10 | Create/Update/Delete |
| Caches | Cache configurations | 10 | Create/Update/Delete |
| Rings | Ring buffer configurations | 10 | Create/Update/Delete |
| HTTPErrors | HTTP error response sections | 10 | Create/Update/Delete |
| Userlists | User authentication lists | 10 | Create/Delete (no update) |
| Programs | External program configurations | 10 | Create/Update/Delete |
| LogForwards | Syslog forwarding sections | 10 | Create/Update/Delete |
| FCGIApps | FastCGI application configs | 10 | Create/Update/Delete |
| CrtStores | Certificate store sections | 10 | Create/Update/Delete |
Note: Lower priority numbers are processed first. Operations are automatically ordered by dependency and priority.
Child Components by Section¶
Frontend Child Components¶
Frontends support 9 child component types with individual Create/Update/Delete operations:
| Component | Description |
|---|---|
| Binds | Listen addresses and ports |
| ACLs | Access control lists |
| HTTP Request Rules | HTTP request processing rules |
| HTTP Response Rules | HTTP response processing rules |
| TCP Request Rules | TCP request processing rules |
| Backend Switching Rules | Dynamic backend selection rules |
| Filters | Data filters (compression, trace, etc.) |
| Captures | Request/response capture declarations |
| Log Targets | Logging destinations |
Backend Child Components¶
Backends support 14 child component types with individual Create/Update/Delete operations:
| Component | Description |
|---|---|
| Servers | Backend server definitions |
| Server Templates | Dynamic server templates |
| ACLs | Access control lists |
| HTTP Request Rules | HTTP request processing rules |
| HTTP Response Rules | HTTP response processing rules |
| HTTP After Response Rules | Post-response processing rules |
| TCP Request Rules | TCP request processing rules |
| TCP Response Rules | TCP response processing rules |
| Server Switching Rules | Dynamic server selection rules |
| Stick Rules | Session persistence rules |
| Filters | Data filters |
| HTTP Checks | HTTP health check configurations |
| TCP Checks | TCP health check configurations |
| Log Targets | Logging destinations |
Mailers, Resolvers, and Peers Child Components¶
The following sections support fine-grained child component management:
Mailers - Individual mailer entry operations:
| Component | Description |
|---|---|
| Mailer Entries | SMTP server definitions for email alerts |
Resolvers - Individual nameserver operations:
| Component | Description |
|---|---|
| Nameservers | DNS server definitions for service discovery |
Peers - Individual peer entry operations:
| Component | Description |
|---|---|
| Peer Entries | Peer server definitions for stick-table replication |
Other Section Components¶
The following sections use whole-section comparison via the models' .Equal() method, which includes all nested components:
- Rings: All ring attributes
- HTTPErrors: Includes errorfiles
- Userlists: Includes users and groups
- Programs: All program attributes
- LogForwards: Includes log targets
- FCGIApps: Includes pass-header and set-param directives
- CrtStores: Includes crt-load entries
Reload Behavior¶
The controller minimizes HAProxy reloads by leveraging the Runtime API when possible. However, only specific operations can avoid reloads.
Zero-Reload Operations (Runtime API)¶
The following changes are applied without reloading HAProxy:
Server Modifications (Specific Fields Only)¶
Server modifications avoid reloads only when changing these Runtime API-supported fields:
| Field | Description | API Endpoint |
|---|---|---|
| Weight | Server weight for load balancing | Runtime API /runtime/servers |
| Address | Server IP address | Runtime API /runtime/servers |
| Port | Server port number | Runtime API /runtime/servers |
| Maintenance | Enable/disable/drain server state | Runtime API /runtime/servers |
| AgentCheck | Agent check status | Runtime API /runtime/servers |
| AgentAddr | Agent check address | Runtime API /runtime/servers |
| AgentSend | Agent check send string | Runtime API /runtime/servers |
| HealthCheckPort | Health check port | Runtime API /runtime/servers |
Frontend Modifications¶
| Field | Description | API Endpoint |
|---|---|---|
| Maxconn | Maximum connections | Runtime API /runtime/frontends |
Note: Map files and auxiliary files are updated via the Storage API, which also avoids reloads when only file contents change.
Reload-Required Operations¶
The following changes require an HAProxy reload:
Server Operations¶
| Operation | Reason |
|---|---|
| Creating servers | New server requires configuration reload |
| Deleting servers | Removing server requires configuration reload |
| Modifying non-runtime fields | Fields like check, inter, rise, fall, ssl, verify, etc. are not supported by Runtime API |
Examples of server attributes that require reload when modified:
- Health check settings (
check,inter,rise,fall,fastinter,downinter) - SSL/TLS settings (
ssl,verify,ca-file,crt,sni) - Connection settings (
maxconn,maxqueue,minconn) - Advanced options (
send-proxy,send-proxy-v2,cookie,track)
Structural and Logic Changes¶
| Category | Components | Reason |
|---|---|---|
| Structural Changes | Frontends, Backends, Binds | Configuration structure changed |
| Routing Logic | ACLs, HTTP Rules, TCP Rules | Request processing logic changed |
| Advanced Features | Filters, Captures, Stick Rules | Feature configuration changed |
| Section Changes | All main sections | Section-level modifications |
| Health Checks | HTTP Checks, TCP Checks | Health check logic changed |
| Frontend Attributes | Most frontend settings except Maxconn | Not supported by Runtime API |
Optimization Strategy¶
The controller uses fine-grained comparison to detect changes at the attribute level:
- Server Weight/Address/Port Changes: Applied via Runtime API (no reload)
- Server Creation/Deletion: Triggers reload (required by HAProxy)
- Server Health Check Changes: Triggers reload (not supported by Runtime API)
- Other Changes: Evaluated individually; structural changes trigger reloads
Important: The Dataplane API automatically determines whether a change can use the Runtime API. If any modified field is not runtime-supported, a reload is triggered. The controller delegates this decision to the Dataplane API's changeThroughRuntimeAPI function.
Reference: See HAProxy Dataplane API runtime.go for the complete Runtime API field support logic.
Not Supported¶
Listen Sections¶
Listen sections are NOT supported because the HAProxy Dataplane API does not expose them as manageable resources.
Background: HAProxy's listen directive combines frontend and backend functionality into a single section. However, the Dataplane API enforces separation of concerns by requiring distinct frontend and backend sections.
Workaround: Any Listen section can be decomposed into:
- One Frontend section (handles client connections)
- One Backend section (handles server connections)
Since both Frontend and Backend are fully supported, this provides equivalent functionality.
HAProxy Enterprise Sections¶
The following sections are available only when connected to HAProxy Enterprise. The controller automatically detects the Enterprise edition and enables support for these features.
| Section | Description | API Version |
|---|---|---|
| WAF Profiles | Web Application Firewall profile definitions | Enterprise 3.0+ |
| WAF Body Rules | WAF request body inspection rules | Enterprise 3.0+ |
| WAF Rulesets | ModSecurity ruleset file references | Enterprise 3.0+ |
| WAF Global | Global WAF configuration settings | Enterprise 3.2+ |
| Bot Management Profiles | Bot detection and mitigation profiles | Enterprise 3.0+ |
| CAPTCHAs | CAPTCHA challenge configurations | Enterprise 3.0+ |
| UDP Load Balancers | UDP protocol load balancer sections | Enterprise 3.0+ |
| Keepalived VRRP | VRRP instances for high availability | Enterprise 3.0+ |
| Keepalived Sync Groups | VRRP synchronization groups | Enterprise 3.0+ |
| Dynamic Updates | Runtime configuration update rules | Enterprise 3.0+ |
| Advanced Logging | Extended log inputs and outputs | Enterprise 3.0+ |
| Git Integration | Configuration version control settings | Enterprise 3.0+ |
UDP Load Balancer Child Components¶
UDP Load Balancers support child components similar to TCP frontends/backends:
| Component | Description | API Version |
|---|---|---|
| Binds | UDP listen addresses and ports | Enterprise 3.0+ |
| Servers | Backend UDP server definitions | Enterprise 3.0+ |
| ACLs | Access control lists | Enterprise 3.2+ |
| Server Switching Rules | Dynamic server selection | Enterprise 3.2+ |
Keepalived Child Components¶
Keepalived sections support fine-grained management of VRRP configuration:
| Component | Description |
|---|---|
| Track Interfaces | Network interfaces to monitor |
| Track Scripts | Health check scripts for failover |
| Virtual IP Addresses | VIPs managed by VRRP instance |
Note
Enterprise features require HAProxy Enterprise license and the Enterprise Dataplane API. When connected to HAProxy Community, these sections are ignored without error.
Implementation Details¶
Comparison Strategies¶
The implementation uses two approaches for optimal performance:
- Fine-Grained Child Resource Management (frequently-changing resources)
- Frontends: 9 child resource types
- Backends: 14 child resource types
- Each child resource has individual Create/Update/Delete operations
- Changes to individual ACLs, rules, or servers are applied independently
-
Benefit: Minimizes API calls and reduces reload frequency
-
Whole-Section Replacement (infrequently-changing resources)
- Other sections (Resolvers, Mailers, Peers, etc.)
- Uses
.Equal()method to compare entire section including nested components - If any attribute changes, the entire section is replaced
- Benefit: Simpler code, fewer operations for resources that rarely change
Operation Ordering¶
Operations are automatically ordered by:
- Priority (lower numbers first)
- Type (Delete → Create → Update)
- Dependencies (parent sections before child components)
This ensures that, for example, a Backend is created before its Servers, and Servers are deleted before the Backend is removed.
Code References¶
All comparison logic is implemented in:
- Main Comparator:
pkg/dataplane/comparator/comparator.go - Operation Definitions:
pkg/dataplane/comparator/sections/*.go
The comparator uses the haproxytech/client-native models' built-in .Equal() methods for comprehensive attribute comparison, ensuring zero-maintenance compatibility with future HAProxy features.
Summary¶
HAPTIC provides complete HAProxy Dataplane API coverage:
- 15 main sections fully supported
- 23 child component types with fine-grained operations
- 12 Enterprise-only sections (WAF, bot management, UDP, Keepalived, etc.)
- Runtime API optimization for zero-reload server updates
- Dependency-aware operation ordering for safe deployments
- Future-proof comparison using HAProxy models'
.Equal()methods - Listen sections not supported (Dataplane API limitation)
For implementation details, see:
- Architecture:
docs/design.md - Parser:
pkg/dataplane/parser/ - Comparator:
pkg/dataplane/comparator/ - Operations:
pkg/dataplane/comparator/sections/