Skip to content

Support opt-in HAProxy backend address discovery - #208

Merged
pradeepkintali merged 2 commits into
masterfrom
pkintali/haproxy-server-address
Nov 19, 2026
Merged

pradeepkintali merged 2 commits into
masterfrom
pkintali/haproxy-server-address

Conversation

@pradeepkintali

Copy link
Copy Markdown
Contributor

Why

HAProxy's svname is a server label, which is not necessarily a resolvable
hostname. For example, a row can have svname=primary while its actual destination
is in addr=192.0.2.10:3307. Freno currently treats the label as the MySQL hostname
and uses the cluster's configured MySQL port.

Add a per-cluster HAProxySettings.UseServerAddress option to discover the
destination from addr instead. It defaults to false, preserving existing
hostname-based discovery.

Call flow

The two similarly named files have different responsibilities:

  • pkg/throttle/throttler.go coordinates discovery and creates MySQL probes.
  • pkg/haproxy/throttle.go selects which discovered servers should be probed.
pkg/throttle/throttler.go: refreshMySQLInventory()
    |
    | Read the configured HAProxy stats endpoint
    | Select the CSV parser using UseServerAddress
    v
pkg/haproxy/parser.go
    |
    | false / omitted: svname -> Hostname; Port remains 0
    | true: split and validate addr -> Hostname + Port
    |
    | Return BackendHost objects, including status and transition state
    v
pkg/haproxy/throttle.go: FilterThrottlerBackendHosts()
    |
    | Apply the existing server-status rules
    | Return eligible objects without discarding their ports
    v
pkg/throttle/throttler.go
    |
    | Collect objects in totalHosts ([]*haproxy.BackendHost)
    | Create mysql.InstanceKey:
    |   Hostname = discovered hostname / IP
    |   Port = discovered port, or configured cluster port when Port is 0
    | Create MySQL probes and send the cluster's probe list
    v
updateMySQLClusterProbes()
    |
    v
MySQL probe inventory used by metric collection

For the illustrative primary row above, enabling the option produces a probe
for 192.0.2.10:3307, rather than primary with the configured cluster port.
The address is split because the existing mysql.InstanceKey and connection
builder already represent hostname and port separately.

Previously, totalHosts contained only hostname strings. It now contains
backend objects so the address's port survives filtering and inventory creation.
The existing hostname-only FilterThrotllerHosts() function remains available
and reuses the same filtering implementation.

Configuration and compatibility

Set the option inside the selected cluster's existing HAProxySettings:

"HAProxySettings": {
  "Addresses": "http://haproxy.example.com/stats/",
  "PoolName": "example_rw",
  "UseServerAddress": true
}
  • With the option omitted or false, discovery still uses svname and the
    configured MySQL port. CSVs without an addr column remain supported.
  • When enabled, discovery retains the port from addr, including nondefault
    ports, and supports bracketed IPv6 addresses. IgnoreHosts and skipped-host
    checks apply to the discovered target rather than the HAProxy label.
  • Status filtering is unchanged: stable UP, DOWN, and no check servers
    remain eligible; transitioning UP, NOLB, and unrecognized statuses are
    excluded. Existing all-transitioning discovery safeguards remain in place.
  • The address parser rejects missing columns, incomplete rows, invalid ports,
    empty hosts, and unspecified IP addresses. Invalid selected-server addresses
    do not fall back to their labels or return a partially parsed roster.
  • This does not change throttling thresholds, recovery, or dependency decisions.
    An unsuccessful HAProxy refresh can still retain the previous inventory; this
    change does not add a new stale-discovery or fail-closed policy.

Deploy a binary supporting this option before enabling it in configuration.
No deployment or configuration rollout is included.

Validation

  • Confirmed the new inventory regression test fails against the old code.
  • Passed script/cibuild using the existing local Go 1.27.3 Docker image:
    formatting, binary build, and all package tests with race detection.
  • Added parser tests for IPv4, IPv6, hostnames, malformed addresses, missing
    fields, summary rows, and status/transition filtering.
  • Added inventory tests for unchanged hostname discovery and exclusions,
    identical aliases in different pools, nondefault ports, IPv6, address-based
    exclusions, and replacing the old probe target after a simulated address
    change.
  • Separately applied the patch to Add composite MySQL safety checks and stable recovery #196 at
    a98258889e1e4caa352c9604fb37d59ddb8c48ee without conflicts and passed the
    combined HAProxy, config, throttle, and HTTP race tests. This PR is independent
    of Add composite MySQL safety checks and stable recovery #196 and does not modify its branch.

These are local code and simulated-discovery checks, not production connectivity
or failover validation.

Preserve default hostname-based discovery while allowing selected pools to use validated backend host and port values from the HAProxy CSV addr field. Carry backend ports through status filtering and probe inventory creation, with regression tests and configuration documentation.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: fbc83df2-d1af-406f-b97b-51cf0aaa570d
Copilot AI adaptive review requested due to automatic review settings November 19, 2026 05:05

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

With UseServerAddress enabled, address validation of ineligible maintenance rows and incorrect parsing of quoted CSV fields can prevent otherwise valid servers from being discovered.

3 open issues
What changed in this PR

Adds opt-in HAProxy discovery from each server’s addr field, preserving the destination port while keeping hostname-based discovery as the default.

Changes:

  • Adds per-cluster configuration and address parsing for IPv4, IPv6, and hostname targets.
  • Preserves discovered ports through filtering and MySQL probe creation.
  • Documents the option and adds parser and inventory regression tests.
File Description
pkg/​throttle/​throttler.go Selects discovery mode and preserves target ports in probes.
pkg/​throttle/​haproxy_inventory_test.go Tests compatibility, exclusions, ports, and target changes.
pkg/​haproxy/​throttle.go Adds filtering that retains backend objects and ports.
pkg/​haproxy/​server_address_test.go Tests address parsing, validation, and status filtering.
pkg/​haproxy/​parser.go Adds opt-in parsing and validation of server addresses.
pkg/​haproxy/​host.go Adds the discovered port to backend hosts.
pkg/​config/​haproxy_config.go Adds the UseServerAddress setting.
doc/​mysql.md Documents configuration and discovery failure behavior.

Review effort: Max (adaptive)

Comment thread pkg/haproxy/parser.go Resolved
Comment thread pkg/haproxy/parser.go Resolved
Comment thread doc/mysql.md Resolved

@narlapuramsatya narlapuramsatya left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not familiar with where and how the HAProxy are used. Please get it reviewed someone with more familiar in this space.

Decode quoted CSV records correctly and validate backend addresses only for servers eligible for probing. Preserve transition safeguards, add parser and inventory regressions, and document the HTTP stats address prerequisite.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: fbc83df2-d1af-406f-b97b-51cf0aaa570d
@pradeepkintali
pradeepkintali merged commit 12b27f6 into master Nov 19, 2026
6 checks passed
@pradeepkintali
pradeepkintali deleted the pkintali/haproxy-server-address branch November 19, 2026 23:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants