# Overview & concepts

### What is an HAProxy pool?

An <span class="font-semibold" data-streamdown="strong">HAProxy pool</span> is a ServerCTL deployment preset for the <span class="font-semibold" data-streamdown="strong">edge tier</span>: public DNS, one or more enrolled Linux VMs running HAProxy, and optional automatic promotion when the active host fails.

ServerCTL is the <span class="font-semibold" data-streamdown="strong">control plane</span>. It does not terminate customer traffic itself. It:

- Enrols VMs via the <span class="font-semibold" data-streamdown="strong">ServersCTL agent</span>
- Publishes a managed <span class="font-semibold" data-streamdown="strong">A record</span> through Cloudflare or cPanel/WHM
- Tracks <span class="font-semibold" data-streamdown="strong">heartbeats</span> (~1s check-ins) and <span class="font-semibold" data-streamdown="strong">systemd HAProxy</span> health
- Queues <span class="font-semibold" data-streamdown="strong">remote jobs</span> (install, reload, backup, drain) that run on the next heartbeat

<span class="font-semibold" data-streamdown="strong">Status:</span> HAProxy pools are well tested and in public beta.

### Core terminology

<div class="ui-scroll-area" data-direction="horizontal" data-scroll-padding="4" data-visibility="hover" id="bkmrk-term-meaning-pool-on"><div class="ui-scroll-area__viewport"><div class="ui-scroll-area__content"><table><thead class="bg-muted/80" data-streamdown="table-header"><tr class="border-border border-b" data-streamdown="table-row"><th class="whitespace-nowrap px-4 py-2 text-left font-semibold text-sm" data-streamdown="table-header-cell">Term</th><th class="whitespace-nowrap px-4 py-2 text-left font-semibold text-sm" data-streamdown="table-header-cell">Meaning</th></tr></thead><tbody class="divide-y divide-border bg-muted/40" data-streamdown="table-body"><tr class="border-border border-b" data-streamdown="table-row"><td><div class="md-table-cell-content"><span class="font-semibold" data-streamdown="strong">Pool</span></div></td><td><div class="md-table-cell-content">One site/deployment in the dashboard</div></td></tr><tr class="border-border border-b" data-streamdown="table-row"><td><div class="md-table-cell-content"><span class="font-semibold" data-streamdown="strong">Member</span></div></td><td><div class="md-table-cell-content">One enrolled VM (node) with hostname, allowed egress IP, and enrollment secret</div></td></tr><tr class="border-border border-b" data-streamdown="table-row"><td><div class="md-table-cell-content"><span class="font-semibold" data-streamdown="strong">Active member</span></div></td><td><div class="md-table-cell-content">The host whose IPv4 the managed DNS A record points at</div></td></tr><tr class="border-border border-b" data-streamdown="table-row"><td><div class="md-table-cell-content"><span class="font-semibold" data-streamdown="strong">Standby</span></div></td><td><div class="md-table-cell-content">Enrolled member not currently receiving DNS traffic</div></td></tr><tr class="border-border border-b" data-streamdown="table-row"><td><div class="md-table-cell-content"><span class="font-semibold" data-streamdown="strong">Failover hostname</span></div></td><td><div class="md-table-cell-content">Public FQDN clients use (e.g. `<span class="md-inline-path-filename">lb.example.com</span>`)</div></td></tr><tr class="border-border border-b" data-streamdown="table-row"><td><div class="md-table-cell-content"><span class="font-semibold" data-streamdown="strong">Member template</span></div></td><td><div class="md-table-cell-content">Role at enroll time — for HAProxy pools use <span class="font-semibold" data-streamdown="strong">HAProxy balancer</span></div></td></tr></tbody></table>

</div></div></div>### Architecture (high level)

<div class="composer-message-codeblock" id="bkmrk-clients-%E2%86%92-dns-%28cloud"><div class="ui-code-block"><div class="ui-code-block-content"><div class="ui-scroll-area" data-direction="horizontal" data-scroll-padding="4" data-visibility="hover"><div class="ui-scroll-area__viewport"><div class="ui-scroll-area__content"><div class="ui-default-code ui-code-block-default-code"><div class="ui-default-code__content"><div class="ui-default-code__line"><div class="ui-default-code__line-content">Clients → DNS (Cloudflare / cPanel) → A record → Active HAProxy VM</div></div><div class="ui-default-code__line"><div class="ui-default-code__line-content">↑</div></div><div class="ui-default-code__line"><div class="ui-default-code__line-content">ServerCTL Worker updates DNS</div></div><div class="ui-default-code__line"><div class="ui-default-code__line-content">↑</div></div><div class="ui-default-code__line"><div class="ui-default-code__line-content">Standby HAProxy VMs ← agent heartbeats + jobs</div></div></div></div></div></div></div></div></div></div><span class="font-semibold" data-streamdown="strong">Health for failover:</span> A member is unhealthy when:

1. No heartbeat within the <span class="font-semibold" data-streamdown="strong">failover delay</span> window (10–120 seconds), or
2. HAProxy is monitored, and <span class="font-semibold" data-streamdown="strong">systemd reports HAProxy inactive</span>

<p class="callout warning"><span class="font-semibold" data-streamdown="strong">Important:</span> Clients must use the <span class="font-semibold" data-streamdown="strong">failover hostname</span>, not a member’s raw IP. ServerCTL moves the A record; your apps keep the same DNS name.</p>

### What HAProxy pools include vs other presets

HAProxy pools uniquely enable:

- Remote HAProxy jobs (install, reload, backup)
- HAProxy systemd probe on member cards
- <span class="font-semibold" data-streamdown="strong">Disaster Recovery</span> tab (cross-member restore, 2+ members)
- Traffic-flow diagram on Overview
- HAProxy <span class="font-semibold" data-streamdown="strong">Status</span> tab

Generic Linux pools hide HAProxy-specific jobs unless the agent detects HAProxy on the host.