Breaking changes in products that follow protocol evolutions are something unavoidable, even though we're particularly proud to support very old configurations. Thus we try hard not to drop features until there's really no valid justification for keeping them anymore, and they're causing difficulties, either for the users (e.g. confusing setup), or they're not reliable, or they're hindering architectural improvements that are necessary to support new protocols or features. We strive to proceed in a progressive way.

First, we always make sure that a working and supported setup in a non-LTS branch will always work in the next LTS branch. This is in order to guarantee that users of non-LTS can eventually upgrade when the next LTS is available. This means we don't remove features between a non-LTS and the next LTS branch.

Second, we know that many users run with the "zero-warning" setting, which consists in refusing to load a configuration producing warnings. As such, we make sure not to add warnings in LTS versions for supported configurations that would not emit them in the previous non-LTS.

Third, we want to explain how to change the config before breaking. This means that we'll generally proceed in two steps:

• first, introduction of a deprecation warning in a non-LTS branch, which as much as possible will explain what to do
• second, removal of the deprecated feature in the next non-LTS branch (i.e. at least 1 year later). The warning becomes an error, which as much as possible will make a special case of the removed feature to try to guide users through the replacement.

Whenever possible, deprecation happens long after the replacement feature has been available. This means that it should be safe to use the alternate approach even with older versions. This is something important for a number of users, who may switch between one LTS and the next one depending on desired features, performance or any regressions that might be observed. In such a case, a no-warning configuration that matches two LTS versions is desired and is generally guaranteed by the process above.

Examples:

• grace keyword: marked as deprecated in 2.3-dev6 (ab0a5192a), removed in 2.5-dev1 (eb77824)
• option http-tunnel: marked as deprecated in 2.1-dev2 (73e8ede), removed in 2.5-dev1 (d2f2537d1b)
• reqdel, reqrep etc: longer and more complicated:
  • http-request del-header rules were added in 1.5-dev23 (2014)
  • older reqdel/reqrep etc rules were deprecated in 2.0-dev4 (2019, by then there was no zero-warning option so we could deprecate on LTS, and these keywords had almost disappeared anyway)
  • they were finally removed in 2.1-dev2 with a message explaining what keyword to search for each existing keyword.

For these reasons, it is very important that the deprecation date is not missed, otherwise it can postpone the removal by one extra year. Often, features deprecation are discussed on the mailing list (also to seek alternatives), and once decided, it may happen that they're forgotten. If you happen to notice such a situation, please report it to the person(s) proposing this before the current version's release.

Some of the past and planned deprecations / removals are listed below. This list should be kept up to date.

Below we'll classify changes as "Planned" for those not yet marked deprecated in any version, "Pending" for those marked deprecated in at least one version but not yet removed in any version, and "Completed" for those removed in at least one version. Versions might not necessarily match reality if a change was postponed.

• support for the OpenTracing filter
  • summary: as reported in this issue the OpenTracing code is no longer supported and it is becoming increasingly difficult for end users to build the filter relying on it. The current filter's maintainer mentioned here that work has already started on a replacement filter based on OpenTelemetry which is apparently perceived as the natural replacement solution, with a probable inclusion in HAProxy 3.2. As such the plan is to deprecate the current OT filter in 3.3 (where it will only emit a warning), and remove it in 3.5. This should offer enough time to complete the current work, covering for the risk of a bit of time shift, while still offering a warning-less config till 2030 (3.2 EOL) and an effective end of life in 2031 (3.4 EOL).
  • planned deprecation: 3.3
  • planned removal: 3.5
  • status: Planned

• dispatch directive

  • summary: as discussed here, the dispatch directive has lived too long and is still hindering some architectural evolutions. It's super limited (no idle conns, no SSL, no checks, no possibility to update it on the fly, no queuing, no dynamic name resolution, no stats) and can simply be replaced with a server. A good hint is to place server before the directive, resulting in a server called "dispatch" with the same address. When other servers are already present (e.g. for haproxy-1.0 style cookie persistence), then these servers must have their weight set to zero. Let's deprecate it in 3.3 and remove it in 3.5, offering support till 2031 (3.4 EOL). As of now it will emit a warning unless expose-deprecated-directives is set in the global section.
  • planned deprecation: 3.3
  • planned removal: 3.5
  • status: Pending

• transparent and option transparent directives

  • summary: as discussed here, the option transparent directive has lived too long and is still hindering some architectural evolutions. It's super limited (no idle conns, no SSL, no checks, no possibility to update it on the fly, no queuing, no dynamic name resolution, no stats) and can simply be replaced with a server with address 0.0.0.0, which will route the request to the original tproxy address. Let's deprecate it in 3.3 and remove it in 3.5, offering support till 2031 (3.4 EOL). As of now it will emit a warning unless expose-deprecated-directives is set in the global section.
  • planned deprecation: 3.3
  • planned removal: 3.5
  • status: Pending

• general QUIC configuration reorganization

  • summary: QUIC was first introduced in haproxy 2.5. Since then, it has evolved quite rapidly with new features and performance improvement on each new release. In 3.3, QUIC backend support will be introduced. This was considered an ideal opportunity to review the QUIC tuning global configuration. Keywords are renamed with shorter names. to better reflect their purpose and hide unnecessary technical details. This uses a consistent naming with namespace to regroup similar keywords together. Finally, most option are splitted to have individual frontend and backend tuning configuration. Older keywords are marked as deprecated in 3.3 : a warning will be displayed if used on startup with an indication to replace them with the corresponding newer name. Deprecated keywords will be removed on 3.5.
  • planned deprecation: 3.3
  • planned removal: 3.5
  • status: Pending

• master-worker directive

  • summary: The master-worker directive is often wrongly used in the configuration while the -W or -Ws was already set on the startup line. This deprecates the directive 'master-worker' alone without 'no-exit-on-failure'.
  • planned deprecation: 3.3
  • planned removal: 3.5
  • status: Pending

• support for program section

  • summary: the program section is a way to start external programs at the same time as HAProxy. It was designed to be able to start the dataplane API from the master process. However it has a lot of limitations and could never replace a real process manager. With the rework of the master-worker mode in 3.1 it's even less relevant to keep this section. People using the dataplane API migrated to real process managers that are more reliable, and can start the dataplane API before HAProxy. Deprecation of the program section was announced in 3.1-dev12
  • planned deprecation: 3.1
  • planned removal: 3.3
  • status: Completed

• support for same instance names in frontends and backends

  • summary: since the introduction of frontends and backends in HAProxy 1.2, as a convenience to encourage users to split listen instances in two parts, it has been supported to have the same name for a frontend and a backend. Nowadays this is becoming a real problem. Tools consuming statistics cannot reliably use the proxy name for example. Logs are unclear regarding the backend name (is it the frontend before the switch or the backend after?). Also, stick-tables can be declared in both, increasing the confusion and corner cases. Configuration validation is not easy.
  • discussion: https://www.mail-archive.com/[email protected]/msg45185.html
  • planned deprecation: 3.1
  • planned removal: 3.3
  • optional: if possible, detect this condition in 3.0 and report it as a diag warning to limit such new setups.
  • status: Completed

• support for duplicate server names

  • summary: since the beginning, the server names were just informative. We began to enforce their uniqueness for stats only in 1.3 or so, and by then it was decided that we would tolerate duplicate names if numeric IDs would differ. It's about time to get rid of this, it significantly complicates dynamic servers processing and even the boot-time sanity checks. Some config management tools might not understand that, just like stats consumers.
  • discussion: https://www.mail-archive.com/[email protected]/msg45185.html
  • planned deprecation: 3.1
  • planned removal: 3.3
  • optional: if possible, detect this condition in 3.0 and report it as a diag warning to limit such new setups.
  • status: Completed

• support for native mailers

  • summary: the mailers subsystem is convenient to send alerts about servers going down. However, over time it has become clear that there's a desire for quite a bit of customization from users (which is understandable), and the current approach (which is a hack on top of TCP checks) doesn't permit this. A new, 100% compatible and extensible implementation written in Lua (examples/lua/mailers.lua) was merged into 2.8 and can easily be copied, modified, adapted to include more information (e.g. server states, counters, date/time, whatever) or to support multiple addresses, and it still parses the mailers section correctly. It should be the preferred usage for the long term. The legacy mailers feature was announced in 2.8.0 for deprecation in 2.9 and removal in 3.1 thought that deadline was missed, but it must be deprecated in 3.1.
  • planned deprecation: 3.1
  • planned removal: 3.3
  • status: Completed