Release Notes

HAProxy Data Plane API v3.0.0 1491b08

Build from: git@github.com:haproxytech/dataplaneapi.git
Build date: 2024-09-10T15:39:08Z

Key changes in the HAProxy Data Plane API 3.0 release include the following. For more information checkout our blog post announcement and release notes with all the examples.

Breaking changes

Data Plane API moves to v3, and our API resources now start with /v3 instead of /v2. In v3 of the API we introduce a number of breaking changes to improve API usability and readability. These are all based on feedback in the last four years since the release of v2.0.0. Working on that feedback we changed things around and organized it better to make the API more usable for everyone.

Removed _version and data wrapper fields in responses

Data Plane API uses versions for optimistic locking of the configuration, and in the initial design we returned data on each configuration endpoint with _version and data fields as top keys in the response object. Sometime later we also included the Configuration-Version header. In v3 we are getting rid of the redundant configuration version in the response, making the response more straightforward.

Rename of the defaults resource

In the beginning of the Data Plane API we wanted to have only one defaults section, and that resided in the /v2/services/haproxy/configuration/defaults resource. That was due to the fact that the name had no meaning in the functionality of the HAProxy instance. With HAproxy 2.4, from keywords were introduced to frontend and backend sections, and that gave more sense to the functionality of having multiple named defaults. Since the defaults resource was returning an object and not a list, to keep backward compatibility we implemented another resource called named_defaults that returned a list of defaults resources that had a name and could be referenced in backend and frontend sections. The defaults resource was kept for backward compatibility as an object. With v3 of the API, we are migrating named_defaults to simply defaults, while breaking the old defaults behavior. Now the defaults resource returns a list instead of an object.

Moving child resources as nested resources

In the v2 API we have some resources that represent lines inside a section of HAProxy configuration, making them effectively child resources of the parent section resource. One example is the acl resource that could be a child of a frontend, backend or server resource. In v2 two you could access these resources on the API by identifying them with their index (such as for acl) or name (such as for servers) and specifying their parents by using parent_type and parent_name query-string parameters.

Over the years, users found this confusing so now we are redesigning this into having nested resources in the URL. One child resource cannot simultaneously exist in multiple parent resources so it makes more sense to have this as part of the URL of the resource and also helps with many external tools for the future.

Example:

v2/services/haproxy/configuration/acls?parent_type=backend&parent_name=my_bck is now at v3/services/haproxy/configuration/backends/my_bck/acls

Removing explicit index field on index based child resources

In v2 of the API all index-based resources, which represent lines in a configuration that can be repeated inside a section and are distinguished by the order in which they appear in the section, had an index field that told us the position where this specific resource appeared. For example, the acls resource. For v3 we are removing that field as we find it redundant and it is complicated to maintain when positions change. You can infer the index from the actual position in the list returned, and access it at this position.

Remove support for HAProxy in multi-process mode

HAProxy had a feature that allowed it to run in multi-process mode. When HAProxy 2.0 introducing multi-thread mode, this was discouraged. It was deprecated in 2.3 and in 2.5 it was completely removed. In v2 of the API we supported all the keywords related to multi-process mode, and also supported multiple runtime APIs, one for each process mode, so all /runtime resources worked with multiple process support. In v3 of the API we are removing this support altogether. We removed the following fields from the the respective sections:

bind_process from the backend resource
process from the bind resource
bind_process from the defaults resource
bind_process from the frontend resource
nbproc from the global resource

In addition to removing these fields, /runtime endpoints received changes.

Stats endpoint change

The statistics resource at /v2/services/haproxy/stats/native used to return two layers of arrays, the top layer is stats per process, where then each item contains an array of stats lines per object: server, backend, and frontend. Now, as we don't support multi-process mode, /v3/services/haproxy/stats/native returns an object with only one level of stats arrays per object.

Process Info endpoint change

This change is similar to stats info change where we are not supporting multiple processes anymore. In v3 we removed one layer of arrays, which returned process infos per process.

Runtime Stick Table change

This change affected /v2/services/haproxy/runtime/stick_table in a way that the process field is removed from the responses, which used to return data from the process from which we were fetching the stick table information. In addition to this, the query-string parameter process was removed for both the /v2/services/haproxy/runtime/stick_tables and /v2/services/haproxy/runtime/stick_table_entries resources.

Reorganize Global resource fields

We found a need to logically reorganize the global fields. Global is our biggest resource if you measure it by number of fields, and it was mostly flat structured. To improve readability of this resource on the API, we decided to reorganize the fields into logical nested objects.

The API adheres to the field naming in HAProxy and some documentation hints in the HAProxy documentation, while trying to keep only one level of nested objects so as not to unnecessarily make the object more complex. There are still some fields left in the root level of the object, and some options are split into debug_options and performance_options. Also, we've added an ssl_options nested object to cover all SSL options, in addition to adding the tune_options to cover all tune.* options. There are additional nested objects like tune_ssl_options, tune_vars_options, tune_zlib_options, etc. which are all derived from tune.*.* options. Also following the dot notation in the configuration, options now exist under http_client_options, fifty_one_degrees_options, etc. For a full, detailed specification that describes the fields please see the global model specification defined in the Swagger definition.

Removal of deprecated fields and resources

During the development of Data Plane API, we deprecated some fields and resources in order to change or improve the behavior and support configuration keywords. Now we are removing those deprecated keywords. Here is an extensive list of removed deprecations in v3:

Global section: Removed deprecated tune_ssl_default_dh_param that can now be found in tune_ssl_options as default_dh_param.
Backend section: Removed deprecated http-check. You can now specify multiple http_check resources on /v3/services/haproxy/configuration/backends/{parent_name}/http_checks. Removed http-keep-alive, http-server-close, and httpclose fields as they are mutually exclusive and can be set using http_connection_mode field.
HTTP Request/Response Rules and TCP Request Rule resource: Removed deprecated track_sc<stick_counter> fields. In v2 we supported only 0, 1 and 2 stick counter indexes by having those hard-coded in the field names. Now with this change we added the track_sc_stick_counter field, which specifies the stick counter index and can be more than 2 if configured using the tune.stick_counters keyword in global (it defaults to 3), which was introduced in HAProxy 2.8.
Service Discovery resources: Removed the deprecated service-whitelist and service-blacklist, which were replaced by service_allowlist and service_denylist respectively.

Further API Improvements

This section describes other API improvements.

Fetching a parent resource with all children embedded

We've found that our granular approach to creating resources on the API can be helpful, but also in some cases complex. In v3 we've added an extra query-string parameter full_section on all the section resources (such as frontend and backend resources) which allows you to fetch, create, or replace a complete section with all of its child resources.

This query-string parameter works on both PUT and POST endpoints, meaning that you can now edit or create the whole parent section in just one API call. An important thing to note here is that we have two different types of child resources. One is the named child resource (in this example the bind resource). These are all the resources that can be uniquely identified by their name inside a parent section, and then that name is used as a key and those resources are represented as a map. The other child resource type is index-based as its unique identifier is the position in the configuration where the directive appears. It is represented as an inde...

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Release Notes

Changelog

Release Notes

Changelog

Release Notes

Changelog

Release Notes

Changelog

Release Notes

Changelog

Release Notes

Changelog

Release Notes

Changelog

Release Notes

Breaking changes

Removed _version and data wrapper fields in responses

Rename of the defaults resource

Moving child resources as nested resources

Removing explicit index field on index based child resources

Remove support for HAProxy in multi-process mode

Stats endpoint change

Process Info endpoint change

Runtime Stick Table change

Reorganize Global resource fields

Removal of deprecated fields and resources

Further API Improvements

Fetching a parent resource with all children embedded

Release Notes

Changelog

Release Notes

Changelog

Releases: haproxytech/dataplaneapi

HAProxy Data Plane API v2.8.12

Release Notes

Changelog

HAProxy Data Plane API v3.0.3

Release Notes

Changelog

HAProxy Data Plane API v2.9.8

Release Notes

Changelog

HAProxy Data Plane API v3.0.2

Release Notes

Changelog

HAProxy Data Plane API v2.9.7

Release Notes

Changelog

HAProxy Data Plane API v2.8.11

Release Notes

Changelog

HAProxy Data Plane API v3.0.1

Release Notes

Changelog

HAProxy Data Plane API v3.0.0

Release Notes

Breaking changes

Removed _version and data wrapper fields in responses

Rename of the defaults resource

Moving child resources as nested resources

Removing explicit index field on index based child resources

Remove support for HAProxy in multi-process mode

Stats endpoint change

Process Info endpoint change

Runtime Stick Table change

Reorganize Global resource fields

Removal of deprecated fields and resources

Further API Improvements

Fetching a parent resource with all children embedded

HAProxy Data Plane API v2.9.6

Release Notes

Changelog

HAProxy Data Plane API v2.8.10

Release Notes

Changelog