Announcing HAProxy Data Plane API 2.6

In HAProxy Data Plane API version 2.6, we continued the effort of expanding support for HAProxy configuration keywords, as this has been the priority with this release cycle, and it will be in the next one too to meet our goal of achieving complete feature parity with both the HAProxy configuration and Runtime API. This will enable you to use HAProxy Data Plane API for configuring HAProxy without any gaps in functionality.

With that in mind, we also implemented quality of life improvements, namely adding a health check endpoint that returns the status of the HAProxy process, and we upgraded to Go 1.18 and updated all dependencies that we are using so users can benefit from bug and security fixes.

Extended keyword support

We updated the HAProxy Data Plane API to cover more HAProxy configuration keywords, with the goal of making the API a full-fledged way to configure HAProxy. In this section, you’ll see everything we’ve added.

The ring section

Since HAProxy 2.2, you’ve had the ability to define a section called ring which creates a FIFO buffer in memory where you can store HAProxy’s logs temporarily before forwarded them to a remote syslog server. The benefit of using a ring buffer is that it allows you to forward log messages to a remote syslog server using TCP. A traditional log line in an HAProxy configuration forwards logs using the UDP protocol. Relaying logs using UDP avoids any slowdowns, since UDP is a connectionless protocol, but the downside is that there is no guarantee that every log message will arrive at the destination. UDP is fire and forget.

However, by defining a ring section you can buffer log messages and then communicate with a syslog server over a TCP port without slowing down HAProxy since the log forwarding happens in the background. The TCP protocol is a connected protocol and guarantees delivery of all messages. In the snippet below, we define a ring section for buffering HAProxy logs.

Then in the global section of your configuration, your log line would specify the ring buffer instead of an IP address and port:

You can now create a ring section through the API by using the /services/haproxy/configuration/rings endpoint, as shown below.

Then add a server to it by using the /services/haproxy/configuration/servers endpoint, setting the URL parameter parent_type to ring and parent_name to the name of the ring section.

Add the required log line to your global section by invoking the /services/haproxy/configuration/log_targets endpoint.

The log-forward section

While the ring section pertains to forwarding HAProxy’s own logs, another section named log-forward pertains to forwarding log messages for other applications to a list of syslog servers. This gets its own section in order to support relaying syslog messages over UDP, while in general HAProxy is a TCP-based proxy. The log-forward section was introduced in HAProxy 2.3 and looks like this:

You can create a log-forward section through the API by using the new /services/haproxy/configuration/log_forwards endpoint.

Then add a bind line for receiving syslog traffic over TCP and a dgram_bind line for receiving it over UDP by calling the /services/haproxy/configuration/binds and /services/haproxy/configuration/dgram_binds endpoints:

Finally, add the log servers to which you will forward traffic by invoking the /services/haproxy/configuration/log_targets endpoint.

Global section keywords

With version 2.6, we’re happy to announce that the /services/haproxy/configuration/global endpoint supports all options for the HAProxy global section.

Process management and security:

• default-path
• description
• expose-experimental-directives
• gid
• grace
• insecure-fork-wanted
• insecure-setuid-wanted
• issuers-chain-path
• h2-workaround-bogus-websocket-clients
• log-tag
• lua-load-per-thread
• mworker-max-reloads
• node
• numa-cpu-mapping
• pp2-never-send-local
• presetenv
• resetenv
• uid
• ulimit-n
• set-dumpable
• set-var
• setenv
• unix-bind
• unsetenv
• strict-limits

SSL tuning options:

• ssl-default-bind-ciphers
• ssl-default-bind-ciphersuites
• ssl-default-bind-curves
• ssl-default-bind-options
• ssl-default-server-ciphers
• ssl-default-server-ciphersuites
• ssl-default-server-options
• ssl-dh-param-file
• ssl-server-verify
• ssl-skip-self-issued-ca

Performance tuning:

• busy-polling
• max-spread-checks
• maxconnrate
• maxcomprate
• maxcompcpuusage
• maxpipes
• maxsessrate
• maxsslconn
• maxsslrate
• maxzlibmem
• noepoll
• nokqueue
• noevports
• nopoll
• nosplice
• nogetaddrinfo
• noreuseport
• profiling.tasks
• spread-checks
• ssl-engine

Defaults, frontend and backend keywords

Version 2.6 of the HAProxy Data Plane API also brings support or all option keywords that can be configured in defaults, backend, and frontend sections via the /services/haproxy/configuration/defaults, /services/haproxy/configuration/frontends, and /services/haproxy/configuration/backends API endpoints:

• option abortonclose
• option checkcache
• option http-ignore-probes
• option http-no-delay
• option http-use-proxy-header
• option httpslog
• option independent-streams
• option nolinger
• option originalto
• option persist
• option prefer-last-server
• option socket-stats
• option splice-auto
• option splice-request
• option splice-response
• option spop-check
• option srvtcpka
• option tcp-smart-accept
• option tcp-smart-connect
• option tcpka
• option transparent

In addition, we’ve extended the stats object that you can configure in a frontend or backend section to include the following options:

• stats auth
• stats http-request
• stats realm

For the backend and the defaults sections we added support for the server TCP keep-alive options:

• srvtcpka-cnt
• srvtcpka-idle
• Srvtcpka-intvl

For the frontend and the defaults sections we added support for the client TCP keep-alive options:

• clitcpka-cnt
• clitcpka-idle
• clitcpka-intvl

The http-after-response directive

HAProxy 2.6 introduced the http-after-response directive, which applies an action to all responses, even those generated by HAProxy and returned without involving a backend server. People use it to attach HTTP headers to a response when HAProxy returns a redirect, for example. The older http-response directive applies only when the backend server sends the response.

With HAProxy Data Plane API 2.6, you can configure http-after-response directives similarly to how you would configure http-response directives, only using the /services/haproxy/configuration/http_after_response_rules endpoint.

This will create the following line in your frontend section in the HAProxy configuration file:

Health endpoint

A new endpoint, /health, returns a value indicating whether HAProxy is up and running.

To enable this feature, you must configure the status_cmd field in the HAProxy Data Plane API configuration file (e.g. /etc/haproxy/dataplaneapi.hcl), as shown below.

HCL

YAML

Library updates and bug fixes

In addition to the already mentioned features implemented in HAProxy Data Plane API, the 2.6 version brings some stability and quality of life improvements, along with bug fixes.

One of the bigger updates is that the HAProxy Data Plane API project has been migrated to Go 1.18 along with the underlying libraries config-parser and client-native. This allows us to get all the new features of the Go language to improve our codebase, along with some optimizations and, of course, security fixes.

We’ve also updated the go-swagger library we use for code generation to the latest version, which received many bug fixes but introduced some breaking changes for our models package in the client-native project. So, the client-native package has been upgraded to v4. This is important news for all of our contributors, since they will need to update their dev environments for both Go 1.18 and go-swagger 0.29.0.

In addition to that, we did a thorough pass of all the external dependencies used by the HAProxy Data Plane API project and updated those dependencies where needed to benefit from all the bug and security fixes.

Contributors

We’d like to thank the code contributors who helped make this version possible!