<?xml version="1.0" encoding="utf-8" standalone="yes"?><rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:media="http://search.yahoo.com/mrss/"><channel><title>Infrastructure | A DevOps Blog</title><link>https://blog.bsdserver.nl/tag/infrastructure/</link><description>Hands-on DevOps and homelab content: Kubernetes clusters, self-hosted services, CI/CD pipelines and infrastructure as code, by Patrick de Ruiter of We Build Your Cloud.</description><language>en</language><image><url>https://blog.bsdserver.nl/images/app-icon.svg</url><title>A DevOps Blog</title><link>https://blog.bsdserver.nl/</link></image><lastBuildDate>Wed, 18 Nov 2026 12:00:00 +0100</lastBuildDate><atom:link href="https://blog.bsdserver.nl/tag/infrastructure/rss/" rel="self" type="application/rss+xml"/><ttl>60</ttl><item><title>Why We Chose CFEngine Instead of Ansible for Configuration Management</title><link>https://blog.bsdserver.nl/why-we-chose-cfengine-instead-of-ansible-for-configuration-management/</link><guid isPermaLink="false">6a61dd6418bfa60001dd6cfd</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Fri, 24 Jul 2026 19:13:06 +0000</pubDate><description>Ask ten engineers which configuration management tool to use and nine will say Ansible. We went the other way.</description><category>Automation</category><category>Ansible</category><category>DevOps</category><category>Infrastructure</category><media:content url="https://blog.bsdserver.nl/content/images/2026/07/cfengine-vs-ansible.png" medium="image"/><content:encoded><![CDATA[<p>Ask ten engineers which configuration management tool to use and nine will say Ansible. We went the other way. Our fleet, both on-premise and cloud, for clients who expect things to just keep running, is managed by CFEngine. Here are the ten reasons why, and where Ansible still earns its place in our stack.</p>
<h2 id="1-continuous-convergence-not-point-in-time-runs">1. Continuous convergence, not point-in-time runs <a class="anchor" data-pagefind-ignore href="#1-continuous-convergence-not-point-in-time-runs" aria-label="Link to this section">#</a></h2>
<p>Ansible configures a host at the moment you run a playbook. Between runs, nothing watches the machine. CFEngine&rsquo;s agent runs every five minutes, every day, forever. Someone hand-edits a config, a package update overwrites a file, a service dies in the middle of the night, the agent quietly puts it back.</p>
<h2 id="2-self-healing-by-design">2. Self-healing by design <a class="anchor" data-pagefind-ignore href="#2-self-healing-by-design" aria-label="Link to this section">#</a></h2>
<p>Because the agent converges continuously, repair isn&rsquo;t a special event, it&rsquo;s the default behaviour. We don&rsquo;t get paged to re-run a playbook; drift is corrected before monitoring even fires. For a managed hosting company, that&rsquo;s not a nice-to-have.</p>
<h2 id="3-pull-beats-push-at-scale">3. Pull beats push at scale <a class="anchor" data-pagefind-ignore href="#3-pull-beats-push-at-scale" aria-label="Link to this section">#</a></h2>
<p>Ansible pushes over SSH from a control node: one machine fanning out to hundreds. Slow runs, timeouts, and a controller that becomes a bottleneck and a single point of failure. CFEngine hosts pull their policy from a hub and execute locally. A thousand hosts converging is no harder than ten, the work is distributed to the machines themselves.</p>
<h2 id="4-a-tiny-dependency-free-footprint">4. A tiny, dependency-free footprint <a class="anchor" data-pagefind-ignore href="#4-a-tiny-dependency-free-footprint" aria-label="Link to this section">#</a></h2>
<p>The CFEngine agent is written in C. It uses a few tens of megabytes of memory and needs no interpreter on the managed host. Ansible needs Python on every target, a real constraint on minimal installs, appliances, and BSD systems. We run infrastructure on machines where a Python runtime is either unwelcome or unavailable. The C agent runs everywhere, including the smallest VPS we manage.</p>
<h2 id="5-speed">5. Speed <a class="anchor" data-pagefind-ignore href="#5-speed" aria-label="Link to this section">#</a></h2>
<p>An agent run over our full policy set completes in seconds. Comparable Ansible playbooks take minutes per host, dominated by SSH round-trips and module transfer. Multiply that across a fleet and across every change, and the difference stops being academic.</p>
<h2 id="6-hosts-stay-autonomous">6. Hosts stay autonomous <a class="anchor" data-pagefind-ignore href="#6-hosts-stay-autonomous" aria-label="Link to this section">#</a></h2>
<p>Every CFEngine host caches its policy. If the policy server is unreachable, due to network partition, hub maintenance, or datacenter issue, hosts keep enforcing the last known-good policy on their own. An Ansible-managed fleet with an unreachable control node is simply unmanaged until it comes back.</p>
<h2 id="7-a-stronger-security-posture">7. A stronger security posture <a class="anchor" data-pagefind-ignore href="#7-a-stronger-security-posture" aria-label="Link to this section">#</a></h2>
<p>An Ansible control node holds SSH keys with root access to your entire estate, a high-value target. CFEngine inverts this: no inbound management connections needed, mutual authentication between agent and hub, and policy distributed over a trusted channel. Compromising the hub doesn&rsquo;t hand an attacker an interactive root shell on every host.</p>
<h2 id="8-promise-theory-makes-intent-explicit">8. Promise theory makes intent explicit <a class="anchor" data-pagefind-ignore href="#8-promise-theory-makes-intent-explicit" aria-label="Link to this section">#</a></h2>
<p>Ansible playbooks are ordered task lists, closer to structured scripting than desired state. CFEngine policies are promises: declarations of the state a host should converge to, with the agent deciding what needs doing. The learning curve is steeper, but once it clicks, policies are more predictable and genuinely idempotent, not idempotent-if-every-module-author-did-their-job.</p>
<h2 id="9-drift-detection-and-reporting-built-in">9. Drift detection and reporting built in <a class="anchor" data-pagefind-ignore href="#9-drift-detection-and-reporting-built-in" aria-label="Link to this section">#</a></h2>
<p>Because agents evaluate state constantly, CFEngine knows what changed, on which host, and when. Fleet-wide inventory and compliance reporting come with the model. With Ansible you only learn about drift when you happen to run a playbook in check mode. For compliance conversations with clients, &ldquo;here&rsquo;s a continuous report&rdquo; beats &ldquo;we ran a scan last Tuesday.&rdquo;</p>
<p>Homelabbers can have this too: CFEngine Enterprise is free for up to 25 hosts.</p>
<h2 id="10-boring-in-the-best-way">10. Boring in the best way <a class="anchor" data-pagefind-ignore href="#10-boring-in-the-best-way" aria-label="Link to this section">#</a></h2>
<p>CFEngine has been maintaining production systems since 1993. The language and the model are stable; policies we wrote years ago still run unmodified. That predictability matters when you&rsquo;re promising clients long-term managed infrastructure, not chasing this year&rsquo;s tooling refresh.</p>
<h2 id="where-ansible-still-fits">Where Ansible still fits <a class="anchor" data-pagefind-ignore href="#where-ansible-still-fits" aria-label="Link to this section">#</a></h2>
<p>This isn&rsquo;t a takedown. We use Ansible too, for orchestration, one-off rollouts, and provisioning steps where an ordered, imperative run is exactly what you want. The distinction we draw: <strong>Ansible deploys, CFEngine maintains.</strong> For the job of keeping hundreds of hosts continuously correct with minimal overhead, CFEngine was the right call, and years of quiet nights due to self-repairs have confirmed it.</p>
<hr>
<p><em>Questions about configuration management for your own infrastructure? That&rsquo;s what we do. We build it, we run it, we manage it.</em></p>
]]></content:encoded></item><item><title>HAProxy Data Plane API: Dynamic Configuration Management</title><link>https://blog.bsdserver.nl/haproxy-data-plane-api-dynamic-configuration-management/</link><guid isPermaLink="false">693b760079eb54000160a61d</guid><dc:creator>Patrick de Ruiter</dc:creator><pubDate>Fri, 12 Dec 2025 01:55:12 +0000</pubDate><description>Managing HAProxy configuration traditionally requires editing files and reloading the service.</description><category>HAProxy</category><category>API</category><category>Automation</category><category>DevOps</category><category>Infrastructure</category><media:content url="https://blog.bsdserver.nl/content/images/2026/01/haproxy-data-plane-api.png" medium="image"/><content:encoded><![CDATA[<p>Managing HAProxy configuration traditionally requires editing files and reloading the service. That works for a person at a terminal, but not for a deployment pipeline that needs to add a server.</p>
<p>The Data Plane API is HAProxy&rsquo;s REST API for its configuration. This post installs it behind a TLS frontend, then uses it to add and remove servers, switch blue-green environments, shift canary traffic, and drive it from Python and GitLab CI.</p>
<h2 id="why-data-plane-api">Why Data Plane API? <a class="anchor" data-pagefind-ignore href="#why-data-plane-api" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Configuration over HTTP</strong> - Backends and servers through REST calls instead of editing <code>haproxy.cfg</code></li>
<li><strong>Transactions</strong> - Group several changes, commit them as one, or throw them away</li>
<li><strong>Version check</strong> - Every change names the configuration version it builds on, so two clients cannot overwrite each other</li>
<li><strong>Runtime changes</strong> - Drain, maintenance and weights on the running process, without a reload</li>
<li><strong>Integration friendly</strong> - Anything that speaks HTTP: shell scripts, Python, CI pipelines</li>
</ul>
<h3 id="when-to-use-it">When to use it <a class="anchor" data-pagefind-ignore href="#when-to-use-it" aria-label="Link to this section">#</a></h3>
<ul>
<li><strong>Use it</strong> when tools change HAProxy: deployment pipelines, blue-green switches, service discovery.</li>
<li><strong>Skip it</strong> when the configuration changes rarely and Ansible or another tool already templates <code>haproxy.cfg</code>. That is simpler and easier to review.</li>
</ul>
<p>Pick one owner for <code>haproxy.cfg</code>. Once the API manages it, make changes through the API, not by hand.</p>
<h3 id="configuration-vs-runtime-changes">Configuration vs runtime changes <a class="anchor" data-pagefind-ignore href="#configuration-vs-runtime-changes" aria-label="Link to this section">#</a></h3>
<p>The API has two kinds of endpoints. Knowing which one you call explains most surprises.</p>
<table>
	<thead>
			<tr>
					<th>Endpoints</th>
					<th>Path</th>
					<th>What happens</th>
					<th>Survives a reload</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Configuration</td>
					<td><code>/services/haproxy/configuration/...</code></td>
					<td>Writes <code>haproxy.cfg</code>, then reloads HAProxy</td>
					<td>Yes</td>
			</tr>
			<tr>
					<td>Runtime</td>
					<td><code>/services/haproxy/runtime/...</code></td>
					<td>Changes the running process, no reload</td>
					<td>No</td>
			</tr>
	</tbody>
</table>
<h2 id="architecture-overview">Architecture Overview <a class="anchor" data-pagefind-ignore href="#architecture-overview" aria-label="Link to this section">#</a></h2>
<table>
	<thead>
			<tr>
					<th>Component</th>
					<th>Runs on</th>
					<th>Job</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>HAProxy</td>
					<td>Load balancer</td>
					<td>Serves the application (<code>http_front</code>) and a TLS frontend for the API on port 5556.</td>
			</tr>
			<tr>
					<td>Data Plane API</td>
					<td>Load balancer, port 5555</td>
					<td>Edits <code>haproxy.cfg</code>, reloads HAProxy, and makes runtime changes on the running process.</td>
			</tr>
			<tr>
					<td>Clients</td>
					<td>Admin machine, CI runner</td>
					<td>curl, the scripts below, Python, GitLab CI.</td>
			</tr>
	</tbody>
</table>
<p>The flow: client → HAProxy <code>:5556</code> (TLS, basic auth) → Data Plane API <code>:5555</code> → <code>haproxy.cfg</code> and a reload, or a runtime change.</p>
<h2 id="installing-the-data-plane-api">Installing the Data Plane API <a class="anchor" data-pagefind-ignore href="#installing-the-data-plane-api" aria-label="Link to this section">#</a></h2>
<h3 id="install-haproxy">Install HAProxy <a class="anchor" data-pagefind-ignore href="#install-haproxy" aria-label="Link to this section">#</a></h3>
<p>The Data Plane API 3.x needs a current HAProxy. Install it from the official HAProxy packages rather than the distribution&rsquo;s older <code>haproxy</code> package:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Official HAProxy packages for Ubuntu 24.04: one PPA per branch</span>
</span></span><span class="line"><span class="cl">sudo add-apt-repository -y ppa:vbernat/haproxy-3.3
</span></span><span class="line"><span class="cl">sudo apt update
</span></span><span class="line"><span class="cl">sudo apt install -y <span class="nv">haproxy</span><span class="o">=</span>3.3.<span class="se">\*</span>
</span></span><span class="line"><span class="cl">haproxy -v
</span></span></code></pre></div><p>3.3 is the newest branch the PPA builds for Ubuntu 24.04, but it is a short-lived stable branch, maintained until about Q1 2027. The newest LTS branch, 3.4, is built for Ubuntu 26.04 (<code>ppa:vbernat/haproxy-3.4</code>) and for Debian 13 on <a href="https://haproxy.debian.net/" rel="noopener">haproxy.debian.net</a>, which lists the repository lines per release and branch. For a long-lived Ubuntu 24.04 install, use the 3.2 LTS branch instead (<code>ppa:vbernat/haproxy-3.2</code>, maintained until 2030).</p>
<h3 id="download-and-install">Download and Install <a class="anchor" data-pagefind-ignore href="#download-and-install" aria-label="Link to this section">#</a></h3>
<p>The API is one static binary from the HAProxy Technologies GitHub releases.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Download the latest 3.x release (official HAProxy Technologies build)</span>
</span></span><span class="line"><span class="cl"><span class="nv">DATAPLANEAPI_VERSION</span><span class="o">=</span><span class="s2">&#34;3.4.7&#34;</span>
</span></span><span class="line"><span class="cl">wget https://github.com/haproxytech/dataplaneapi/releases/download/v<span class="si">${</span><span class="nv">DATAPLANEAPI_VERSION</span><span class="si">}</span>/dataplaneapi_<span class="si">${</span><span class="nv">DATAPLANEAPI_VERSION</span><span class="si">}</span>_linux_x86_64.tar.gz
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Extract and install</span>
</span></span><span class="line"><span class="cl">tar xzf dataplaneapi_<span class="si">${</span><span class="nv">DATAPLANEAPI_VERSION</span><span class="si">}</span>_linux_x86_64.tar.gz
</span></span><span class="line"><span class="cl">sudo mv dataplaneapi /usr/local/bin/
</span></span><span class="line"><span class="cl">sudo chmod +x /usr/local/bin/dataplaneapi
</span></span></code></pre></div><p>This post uses the Data Plane API 3.x paths: everything lives under <code>/v3</code>, and servers are addressed through their backend (<code>/services/haproxy/configuration/backends/web_servers/servers</code>). The 2.x style <code>/v2/.../servers?backend=web_servers</code> paths no longer exist.</p>
<h3 id="configuration-file">Configuration File <a class="anchor" data-pagefind-ignore href="#configuration-file" aria-label="Link to this section">#</a></h3>
<p>This file tells the API where to listen, who may log in, and how to reload HAProxy.</p>
<ul>
<li><code>host: 0.0.0.0</code>, <code>port: 5555</code>: the API itself, plain HTTP. Clients use the TLS frontend on 5556 (below).</li>
<li><code>user</code>: the API user. <code>insecure: false</code> means <code>password</code> is a hash, not plain text.</li>
<li><code>transaction_dir</code>: where open transactions wait until they are committed.</li>
<li><code>resources</code>: directories for map files, certificates and SPOE files that the API manages.</li>
<li><code>reload</code>: the commands the API runs. <code>reload_delay: 5</code> is the minimum time in seconds between two reloads.</li>
</ul>
<p>Create <code>/etc/haproxy/dataplaneapi.yaml</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nt">config_version</span><span class="p">:</span><span class="w"> </span><span class="m">2</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">haproxy_dataplane</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">dataplaneapi</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">host</span><span class="p">:</span><span class="w"> </span><span class="m">0.0.0.0</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">port</span><span class="p">:</span><span class="w"> </span><span class="m">5555</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">scheme</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="l">http</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">user</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">admin</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">password</span><span class="p">:</span><span class="w"> </span><span class="l">$6$rounds=500000$...$... </span><span class="w"> </span><span class="c"># Use mkpasswd to generate</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">insecure</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">transaction</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">transaction_dir</span><span class="p">:</span><span class="w"> </span><span class="l">/tmp/haproxy</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">resources</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">maps_dir</span><span class="p">:</span><span class="w"> </span><span class="l">/etc/haproxy/maps</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">ssl_certs_dir</span><span class="p">:</span><span class="w"> </span><span class="l">/etc/haproxy/certs</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">spoe_dir</span><span class="p">:</span><span class="w"> </span><span class="l">/etc/haproxy/spoe</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">spoe_transaction_dir</span><span class="p">:</span><span class="w"> </span><span class="l">/tmp/spoe-haproxy</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">haproxy</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">config_file</span><span class="p">:</span><span class="w"> </span><span class="l">/etc/haproxy/haproxy.cfg</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">haproxy_bin</span><span class="p">:</span><span class="w"> </span><span class="l">/usr/sbin/haproxy</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">reload</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">reload_delay</span><span class="p">:</span><span class="w"> </span><span class="m">5</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">reload_cmd</span><span class="p">:</span><span class="w"> </span><span class="l">systemctl reload haproxy</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">restart_cmd</span><span class="p">:</span><span class="w"> </span><span class="l">systemctl restart haproxy</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">status_cmd</span><span class="p">:</span><span class="w"> </span><span class="l">systemctl status haproxy</span><span class="w">
</span></span></span></code></pre></div><h3 id="generate-password-hash">Generate Password Hash <a class="anchor" data-pagefind-ignore href="#generate-password-hash" aria-label="Link to this section">#</a></h3>
<p>The SHA-512 hash goes into <code>dataplaneapi.yaml</code> and into the HAProxy <code>userlist</code> below.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Install mkpasswd if needed</span>
</span></span><span class="line"><span class="cl">sudo apt install whois
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Generate SHA-512 password hash</span>
</span></span><span class="line"><span class="cl">mkpasswd -m sha-512 <span class="s1">&#39;your-secure-password&#39;</span>
</span></span></code></pre></div><h2 id="haproxy-configuration-for-api">HAProxy Configuration for API <a class="anchor" data-pagefind-ignore href="#haproxy-configuration-for-api" aria-label="Link to this section">#</a></h2>
<p>HAProxy puts TLS and a second password check in front of the API, and serves the application the examples change.</p>
<ul>
<li><code>stats socket ... level admin</code>: the runtime socket. Runtime changes go through it.</li>
<li><code>frontend dataplane_api</code>: TLS on port 5556 with <code>api.pem</code>, basic auth against <code>api_users</code>, then on to the API on <code>127.0.0.1:5555</code>.</li>
<li><code>userlist api_users</code>: the same user and hash as in <code>dataplaneapi.yaml</code>. The <code>Authorization</code> header is passed on, so the API checks it again.</li>
<li><code>http_front</code> and <code>web_servers</code>: the application. <code>option httpchk GET /health</code> health-checks each server.</li>
</ul>
<p>Add to <code>/etc/haproxy/haproxy.cfg</code>:</p>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">global
    log /dev/log local0
    chroot /var/lib/haproxy
    stats socket /run/haproxy/admin.sock mode 660 level admin expose-fd listeners
    stats timeout 30s
    user haproxy
    group haproxy
    daemon
    
    # No &#34;master-worker&#34; here: it is deprecated since HAProxy 3.3. The packaged
    # systemd unit already starts HAProxy in master-worker mode (-Ws).

defaults
    log global
    mode http
    option httplog
    option dontlognull
    timeout connect 5000
    timeout client 50000
    timeout server 50000

# Data Plane API Frontend
frontend dataplane_api
    bind *:5556 ssl crt /etc/haproxy/certs/api.pem
    mode http
    http-request auth unless { http_auth(api_users) }
    default_backend dataplane_api_backend

backend dataplane_api_backend
    mode http
    server dataplane 127.0.0.1:5555

userlist api_users
    user admin password $6$rounds=500000$...$...

# Application frontends and backends
frontend http_front
    bind *:80
    bind *:443 ssl crt /etc/haproxy/certs/
    default_backend web_servers

backend web_servers
    balance roundrobin
    option httpchk GET /health
    server web1 192.168.1.10:8080 check
    server web2 192.168.1.11:8080 check
</code></pre><h2 id="starting-the-data-plane-api">Starting the Data Plane API <a class="anchor" data-pagefind-ignore href="#starting-the-data-plane-api" aria-label="Link to this section">#</a></h2>
<h3 id="systemd-service">Systemd Service <a class="anchor" data-pagefind-ignore href="#systemd-service" aria-label="Link to this section">#</a></h3>
<p>The unit starts the API after HAProxy and stops it when HAProxy stops (<code>Requires</code>). It runs as root; the comment in the unit explains why.</p>
<p>Create <code>/etc/systemd/system/dataplaneapi.service</code>:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-ini" data-lang="ini"><span class="line"><span class="cl"><span class="k">[Unit]</span>
</span></span><span class="line"><span class="cl"><span class="na">Description</span><span class="o">=</span><span class="s">HAProxy Data Plane API</span>
</span></span><span class="line"><span class="cl"><span class="na">After</span><span class="o">=</span><span class="s">network.target haproxy.service</span>
</span></span><span class="line"><span class="cl"><span class="na">Requires</span><span class="o">=</span><span class="s">haproxy.service</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">[Service]</span>
</span></span><span class="line"><span class="cl"><span class="na">Type</span><span class="o">=</span><span class="s">simple</span>
</span></span><span class="line"><span class="cl"><span class="na">ExecStart</span><span class="o">=</span><span class="s">/usr/local/bin/dataplaneapi -f /etc/haproxy/dataplaneapi.yaml</span>
</span></span><span class="line"><span class="cl"><span class="na">Restart</span><span class="o">=</span><span class="s">on-failure</span>
</span></span><span class="line"><span class="cl"><span class="na">RestartSec</span><span class="o">=</span><span class="s">5</span>
</span></span><span class="line"><span class="cl"><span class="c1"># Runs as root: it rewrites /etc/haproxy/haproxy.cfg and its own config file,</span>
</span></span><span class="line"><span class="cl"><span class="c1"># and calls systemctl to reload HAProxy. As User=haproxy it exits with</span>
</span></span><span class="line"><span class="cl"><span class="c1"># &#34;Error saving configuration: ... permission denied&#34;.</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">[Install]</span>
</span></span><span class="line"><span class="cl"><span class="na">WantedBy</span><span class="o">=</span><span class="s">multi-user.target</span>
</span></span></code></pre></div><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">sudo systemctl daemon-reload
</span></span><span class="line"><span class="cl">sudo systemctl <span class="nb">enable</span> dataplaneapi
</span></span><span class="line"><span class="cl">sudo systemctl start dataplaneapi
</span></span></code></pre></div><h2 id="api-operations">API Operations <a class="anchor" data-pagefind-ignore href="#api-operations" aria-label="Link to this section">#</a></h2>
<h3 id="authentication">Authentication <a class="anchor" data-pagefind-ignore href="#authentication" aria-label="Link to this section">#</a></h3>
<p>All examples use these two variables. <code>/info</code> is a quick test of the connection and the credentials.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Set credentials</span>
</span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">HAPROXY_API</span><span class="o">=</span><span class="s2">&#34;https://haproxy.example.com:5556/v3&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">AUTH</span><span class="o">=</span><span class="s2">&#34;admin:your-secure-password&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Test connection</span>
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> <span class="nv">$HAPROXY_API</span>/info <span class="p">|</span> jq .
</span></span></code></pre></div><h3 id="get-current-configuration">Get Current Configuration <a class="anchor" data-pagefind-ignore href="#get-current-configuration" aria-label="Link to this section">#</a></h3>
<p>Read before you write: the raw configuration, one backend, or its servers.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Get HAProxy configuration</span>
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> <span class="nv">$HAPROXY_API</span>/services/haproxy/configuration/raw
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Get specific backend</span>
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/configuration/backends/web_servers&#34;</span> <span class="p">|</span> jq .
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># List all servers in a backend</span>
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/configuration/backends/web_servers/servers&#34;</span> <span class="p">|</span> jq .
</span></span></code></pre></div><h3 id="working-with-transactions">Working with Transactions <a class="anchor" data-pagefind-ignore href="#working-with-transactions" aria-label="Link to this section">#</a></h3>
<p>Every configuration change follows the same pattern: version → transaction → changes → commit.</p>
<ul>
<li><strong>Version</strong>: the transaction is tied to the configuration version you read. If another client changed the configuration in between, the API rejects it; start again with a fresh version.</li>
<li><strong>Changes</strong>: calls with <code>?transaction_id=</code> are collected, not applied.</li>
<li><strong>Commit</strong> (<code>PUT</code>): writes all changes to <code>haproxy.cfg</code> at once and reloads HAProxy. <strong>Rollback</strong> (<code>DELETE</code>) throws them away.</li>
</ul>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Get current configuration version</span>
</span></span><span class="line"><span class="cl"><span class="nv">VERSION</span><span class="o">=</span><span class="k">$(</span>curl -s -u <span class="nv">$AUTH</span> <span class="nv">$HAPROXY_API</span>/services/haproxy/configuration/version<span class="k">)</span>
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">&#34;Current version: </span><span class="nv">$VERSION</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Start a transaction</span>
</span></span><span class="line"><span class="cl"><span class="nv">TRANSACTION</span><span class="o">=</span><span class="k">$(</span>curl -s -u <span class="nv">$AUTH</span> -X POST <span class="se">\
</span></span></span><span class="line"><span class="cl">  <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/transactions?version=</span><span class="nv">$VERSION</span><span class="s2">&#34;</span> <span class="p">|</span> jq -r <span class="s1">&#39;.id&#39;</span><span class="k">)</span>
</span></span><span class="line"><span class="cl"><span class="nb">echo</span> <span class="s2">&#34;Transaction ID: </span><span class="nv">$TRANSACTION</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Make changes within transaction (see examples below)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Commit transaction</span>
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> -X PUT <span class="se">\
</span></span></span><span class="line"><span class="cl">  <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/transactions/</span><span class="nv">$TRANSACTION</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Or rollback if needed</span>
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> -X DELETE <span class="se">\
</span></span></span><span class="line"><span class="cl">  <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/transactions/</span><span class="nv">$TRANSACTION</span><span class="s2">&#34;</span>
</span></span></code></pre></div><h3 id="adding-a-server">Adding a Server <a class="anchor" data-pagefind-ignore href="#adding-a-server" aria-label="Link to this section">#</a></h3>
<p><code>check: enabled</code> turns on health checks for the server. <code>weight</code> is its share of the traffic, relative to the other servers in the backend.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Get version and start transaction</span>
</span></span><span class="line"><span class="cl"><span class="nv">VERSION</span><span class="o">=</span><span class="k">$(</span>curl -s -u <span class="nv">$AUTH</span> <span class="nv">$HAPROXY_API</span>/services/haproxy/configuration/version<span class="k">)</span>
</span></span><span class="line"><span class="cl"><span class="nv">TRANSACTION</span><span class="o">=</span><span class="k">$(</span>curl -s -u <span class="nv">$AUTH</span> -X POST <span class="se">\
</span></span></span><span class="line"><span class="cl">  <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/transactions?version=</span><span class="nv">$VERSION</span><span class="s2">&#34;</span> <span class="p">|</span> jq -r <span class="s1">&#39;.id&#39;</span><span class="k">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Add new server</span>
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> -X POST <span class="se">\
</span></span></span><span class="line"><span class="cl">  <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/configuration/backends/web_servers/servers?transaction_id=</span><span class="nv">$TRANSACTION</span><span class="s2">&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -H <span class="s2">&#34;Content-Type: application/json&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -d <span class="s1">&#39;{
</span></span></span><span class="line"><span class="cl"><span class="s1">    &#34;name&#34;: &#34;web3&#34;,
</span></span></span><span class="line"><span class="cl"><span class="s1">    &#34;address&#34;: &#34;192.168.1.12&#34;,
</span></span></span><span class="line"><span class="cl"><span class="s1">    &#34;port&#34;: 8080,
</span></span></span><span class="line"><span class="cl"><span class="s1">    &#34;check&#34;: &#34;enabled&#34;,
</span></span></span><span class="line"><span class="cl"><span class="s1">    &#34;weight&#34;: 100
</span></span></span><span class="line"><span class="cl"><span class="s1">  }&#39;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Commit changes</span>
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> -X PUT <span class="se">\
</span></span></span><span class="line"><span class="cl">  <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/transactions/</span><span class="nv">$TRANSACTION</span><span class="s2">&#34;</span>
</span></span></code></pre></div><h3 id="removing-a-server">Removing a Server <a class="anchor" data-pagefind-ignore href="#removing-a-server" aria-label="Link to this section">#</a></h3>
<p>Delete the server by name. Drain it first (see Runtime API Operations) if it still has active connections.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="nv">VERSION</span><span class="o">=</span><span class="k">$(</span>curl -s -u <span class="nv">$AUTH</span> <span class="nv">$HAPROXY_API</span>/services/haproxy/configuration/version<span class="k">)</span>
</span></span><span class="line"><span class="cl"><span class="nv">TRANSACTION</span><span class="o">=</span><span class="k">$(</span>curl -s -u <span class="nv">$AUTH</span> -X POST <span class="se">\
</span></span></span><span class="line"><span class="cl">  <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/transactions?version=</span><span class="nv">$VERSION</span><span class="s2">&#34;</span> <span class="p">|</span> jq -r <span class="s1">&#39;.id&#39;</span><span class="k">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Remove server</span>
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> -X DELETE <span class="se">\
</span></span></span><span class="line"><span class="cl">  <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/configuration/backends/web_servers/servers/web3?transaction_id=</span><span class="nv">$TRANSACTION</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> -X PUT <span class="se">\
</span></span></span><span class="line"><span class="cl">  <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/transactions/</span><span class="nv">$TRANSACTION</span><span class="s2">&#34;</span>
</span></span></code></pre></div><h3 id="modifying-server-weight">Modifying Server Weight <a class="anchor" data-pagefind-ignore href="#modifying-server-weight" aria-label="Link to this section">#</a></h3>
<p>A <code>PUT</code> replaces the whole server object, so send every field, not just the weight. The new weight is written to <code>haproxy.cfg</code>; for a temporary change use the runtime weight below.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="nv">VERSION</span><span class="o">=</span><span class="k">$(</span>curl -s -u <span class="nv">$AUTH</span> <span class="nv">$HAPROXY_API</span>/services/haproxy/configuration/version<span class="k">)</span>
</span></span><span class="line"><span class="cl"><span class="nv">TRANSACTION</span><span class="o">=</span><span class="k">$(</span>curl -s -u <span class="nv">$AUTH</span> -X POST <span class="se">\
</span></span></span><span class="line"><span class="cl">  <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/transactions?version=</span><span class="nv">$VERSION</span><span class="s2">&#34;</span> <span class="p">|</span> jq -r <span class="s1">&#39;.id&#39;</span><span class="k">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Update server weight</span>
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> -X PUT <span class="se">\
</span></span></span><span class="line"><span class="cl">  <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/configuration/backends/web_servers/servers/web1?transaction_id=</span><span class="nv">$TRANSACTION</span><span class="s2">&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -H <span class="s2">&#34;Content-Type: application/json&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -d <span class="s1">&#39;{
</span></span></span><span class="line"><span class="cl"><span class="s1">    &#34;name&#34;: &#34;web1&#34;,
</span></span></span><span class="line"><span class="cl"><span class="s1">    &#34;address&#34;: &#34;192.168.1.10&#34;,
</span></span></span><span class="line"><span class="cl"><span class="s1">    &#34;port&#34;: 8080,
</span></span></span><span class="line"><span class="cl"><span class="s1">    &#34;check&#34;: &#34;enabled&#34;,
</span></span></span><span class="line"><span class="cl"><span class="s1">    &#34;weight&#34;: 50
</span></span></span><span class="line"><span class="cl"><span class="s1">  }&#39;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> -X PUT <span class="se">\
</span></span></span><span class="line"><span class="cl">  <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/transactions/</span><span class="nv">$TRANSACTION</span><span class="s2">&#34;</span>
</span></span></code></pre></div><h3 id="creating-a-new-backend">Creating a New Backend <a class="anchor" data-pagefind-ignore href="#creating-a-new-backend" aria-label="Link to this section">#</a></h3>
<p>The backend and its servers go into one transaction, so HAProxy never loads an empty <code>api_servers</code>.</p>
<ul>
<li><code>balance: leastconn</code>: each request goes to the server with the fewest active connections. Good for requests of uneven length.</li>
<li><code>adv_check: httpchk</code> with <code>httpchk_params</code>: health-check every server with <code>GET /health</code>.</li>
</ul>
<p>No frontend sends traffic to <code>api_servers</code> yet; add a <code>use_backend</code> rule for that.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="nv">VERSION</span><span class="o">=</span><span class="k">$(</span>curl -s -u <span class="nv">$AUTH</span> <span class="nv">$HAPROXY_API</span>/services/haproxy/configuration/version<span class="k">)</span>
</span></span><span class="line"><span class="cl"><span class="nv">TRANSACTION</span><span class="o">=</span><span class="k">$(</span>curl -s -u <span class="nv">$AUTH</span> -X POST <span class="se">\
</span></span></span><span class="line"><span class="cl">  <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/transactions?version=</span><span class="nv">$VERSION</span><span class="s2">&#34;</span> <span class="p">|</span> jq -r <span class="s1">&#39;.id&#39;</span><span class="k">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Create backend</span>
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> -X POST <span class="se">\
</span></span></span><span class="line"><span class="cl">  <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/configuration/backends?transaction_id=</span><span class="nv">$TRANSACTION</span><span class="s2">&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -H <span class="s2">&#34;Content-Type: application/json&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -d <span class="s1">&#39;{
</span></span></span><span class="line"><span class="cl"><span class="s1">    &#34;name&#34;: &#34;api_servers&#34;,
</span></span></span><span class="line"><span class="cl"><span class="s1">    &#34;mode&#34;: &#34;http&#34;,
</span></span></span><span class="line"><span class="cl"><span class="s1">    &#34;balance&#34;: {&#34;algorithm&#34;: &#34;leastconn&#34;},
</span></span></span><span class="line"><span class="cl"><span class="s1">    &#34;adv_check&#34;: &#34;httpchk&#34;,
</span></span></span><span class="line"><span class="cl"><span class="s1">    &#34;httpchk_params&#34;: {
</span></span></span><span class="line"><span class="cl"><span class="s1">      &#34;method&#34;: &#34;GET&#34;,
</span></span></span><span class="line"><span class="cl"><span class="s1">      &#34;uri&#34;: &#34;/health&#34;
</span></span></span><span class="line"><span class="cl"><span class="s1">    }
</span></span></span><span class="line"><span class="cl"><span class="s1">  }&#39;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Add servers to new backend</span>
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> -X POST <span class="se">\
</span></span></span><span class="line"><span class="cl">  <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/configuration/backends/api_servers/servers?transaction_id=</span><span class="nv">$TRANSACTION</span><span class="s2">&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -H <span class="s2">&#34;Content-Type: application/json&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -d <span class="s1">&#39;{&#34;name&#34;: &#34;api1&#34;, &#34;address&#34;: &#34;192.168.1.20&#34;, &#34;port&#34;: 3000, &#34;check&#34;: &#34;enabled&#34;}&#39;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> -X POST <span class="se">\
</span></span></span><span class="line"><span class="cl">  <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/configuration/backends/api_servers/servers?transaction_id=</span><span class="nv">$TRANSACTION</span><span class="s2">&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -H <span class="s2">&#34;Content-Type: application/json&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -d <span class="s1">&#39;{&#34;name&#34;: &#34;api2&#34;, &#34;address&#34;: &#34;192.168.1.21&#34;, &#34;port&#34;: 3000, &#34;check&#34;: &#34;enabled&#34;}&#39;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> -X PUT <span class="se">\
</span></span></span><span class="line"><span class="cl">  <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/transactions/</span><span class="nv">$TRANSACTION</span><span class="s2">&#34;</span>
</span></span></code></pre></div><h2 id="runtime-api-operations">Runtime API Operations <a class="anchor" data-pagefind-ignore href="#runtime-api-operations" aria-label="Link to this section">#</a></h2>
<p>Runtime calls change the running HAProxy directly: no transaction, no reload, nothing written to <code>haproxy.cfg</code>. Use them for short-lived changes like taking a server out during a deploy.</p>
<h3 id="server-state-management">Server State Management <a class="anchor" data-pagefind-ignore href="#server-state-management" aria-label="Link to this section">#</a></h3>
<table>
	<thead>
			<tr>
					<th><code>admin_state</code></th>
					<th>Effect</th>
					<th>Use it for</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>drain</code></td>
					<td>No new traffic; existing connections finish</td>
					<td>Before a deploy or a restart</td>
			</tr>
			<tr>
					<td><code>maint</code></td>
					<td>No traffic at all</td>
					<td>A server down for maintenance</td>
			</tr>
			<tr>
					<td><code>ready</code></td>
					<td>Normal operation</td>
					<td>Putting the server back</td>
			</tr>
	</tbody>
</table>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Get server runtime state</span>
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/runtime/backends/web_servers/servers&#34;</span> <span class="p">|</span> jq .
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Disable server (drain mode)</span>
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> -X PUT <span class="se">\
</span></span></span><span class="line"><span class="cl">  <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/runtime/backends/web_servers/servers/web1&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -H <span class="s2">&#34;Content-Type: application/json&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -d <span class="s1">&#39;{&#34;admin_state&#34;: &#34;drain&#34;}&#39;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Set server to maintenance</span>
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> -X PUT <span class="se">\
</span></span></span><span class="line"><span class="cl">  <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/runtime/backends/web_servers/servers/web1&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -H <span class="s2">&#34;Content-Type: application/json&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -d <span class="s1">&#39;{&#34;admin_state&#34;: &#34;maint&#34;}&#39;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Re-enable server</span>
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> -X PUT <span class="se">\
</span></span></span><span class="line"><span class="cl">  <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/runtime/backends/web_servers/servers/web1&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -H <span class="s2">&#34;Content-Type: application/json&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -d <span class="s1">&#39;{&#34;admin_state&#34;: &#34;ready&#34;}&#39;</span>
</span></span></code></pre></div><h3 id="runtime-weight-adjustment">Runtime Weight Adjustment <a class="anchor" data-pagefind-ignore href="#runtime-weight-adjustment" aria-label="Link to this section">#</a></h3>
<p>The runtime weight is not written to <code>haproxy.cfg</code>; it lasts until the next reload.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Adjust weight without reload</span>
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> -X PUT <span class="se">\
</span></span></span><span class="line"><span class="cl">  <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/runtime/backends/web_servers/servers/web1&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -H <span class="s2">&#34;Content-Type: application/json&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  -d <span class="s1">&#39;{&#34;operational_state&#34;: &#34;up&#34;, &#34;weight&#34;: 150}&#39;</span>
</span></span></code></pre></div><h2 id="automation-scripts">Automation Scripts <a class="anchor" data-pagefind-ignore href="#automation-scripts" aria-label="Link to this section">#</a></h2>
<h3 id="blue-green-deployment-script">Blue-Green Deployment Script <a class="anchor" data-pagefind-ignore href="#blue-green-deployment-script" aria-label="Link to this section">#</a></h3>
<p>Swaps a whole set of servers in one transaction: <code>green</code> adds the green servers and removes the blue ones, <code>blue</code> does the opposite. One commit, so both changes reach HAProxy in the same reload.</p>
<ul>
<li>Servers are listed as <code>name:address:port</code>.</li>
<li><code>--fail-with-body</code> with <code>set -e</code>: a rejected change stops the script before the commit.</li>
<li>Removing ignores errors (<code>|| true</code>), so it also works when the old servers are already gone.</li>
</ul>
<p>Run it as <code>./blue-green-deploy.sh green</code>.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="cp">#!/bin/bash
</span></span></span><span class="line"><span class="cl"><span class="c1"># blue-green-deploy.sh - Switch traffic between blue and green environments</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nb">set</span> -e
</span></span><span class="line"><span class="cl"><span class="c1"># --fail-with-body makes API errors (4xx/5xx) fail the script instead of</span>
</span></span><span class="line"><span class="cl"><span class="c1"># printing &#34;Deployment complete!&#34; after a rejected change</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nv">HAPROXY_API</span><span class="o">=</span><span class="s2">&#34;https://haproxy.example.com:5556/v3&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">AUTH</span><span class="o">=</span><span class="s2">&#34;admin:your-secure-password&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">BACKEND</span><span class="o">=</span><span class="s2">&#34;app_servers&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nv">BLUE_SERVERS</span><span class="o">=(</span><span class="s2">&#34;blue1:192.168.1.10:8080&#34;</span> <span class="s2">&#34;blue2:192.168.1.11:8080&#34;</span><span class="o">)</span>
</span></span><span class="line"><span class="cl"><span class="nv">GREEN_SERVERS</span><span class="o">=(</span><span class="s2">&#34;green1:192.168.1.20:8080&#34;</span> <span class="s2">&#34;green2:192.168.1.21:8080&#34;</span><span class="o">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">get_version<span class="o">()</span> <span class="o">{</span>
</span></span><span class="line"><span class="cl">  curl -s -u <span class="nv">$AUTH</span> <span class="nv">$HAPROXY_API</span>/services/haproxy/configuration/version
</span></span><span class="line"><span class="cl"><span class="o">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">start_transaction<span class="o">()</span> <span class="o">{</span>
</span></span><span class="line"><span class="cl">  curl -s -u <span class="nv">$AUTH</span> -X POST <span class="se">\
</span></span></span><span class="line"><span class="cl">    <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/transactions?version=</span><span class="nv">$1</span><span class="s2">&#34;</span> <span class="p">|</span> jq -r <span class="s1">&#39;.id&#39;</span>
</span></span><span class="line"><span class="cl"><span class="o">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">add_server<span class="o">()</span> <span class="o">{</span>
</span></span><span class="line"><span class="cl">  <span class="nb">local</span> <span class="nv">name</span><span class="o">=</span><span class="nv">$1</span>
</span></span><span class="line"><span class="cl">  <span class="nb">local</span> <span class="nv">addr</span><span class="o">=</span><span class="nv">$2</span>
</span></span><span class="line"><span class="cl">  <span class="nb">local</span> <span class="nv">port</span><span class="o">=</span><span class="nv">$3</span>
</span></span><span class="line"><span class="cl">  <span class="nb">local</span> <span class="nv">txn</span><span class="o">=</span><span class="nv">$4</span>
</span></span><span class="line"><span class="cl">  
</span></span><span class="line"><span class="cl">  curl -s --fail-with-body -u <span class="nv">$AUTH</span> -X POST <span class="se">\
</span></span></span><span class="line"><span class="cl">    <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/configuration/backends/</span><span class="nv">$BACKEND</span><span class="s2">/servers?transaction_id=</span><span class="nv">$txn</span><span class="s2">&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    -H <span class="s2">&#34;Content-Type: application/json&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    -d <span class="s2">&#34;{\&#34;name\&#34;: \&#34;</span><span class="nv">$name</span><span class="s2">\&#34;, \&#34;address\&#34;: \&#34;</span><span class="nv">$addr</span><span class="s2">\&#34;, \&#34;port\&#34;: </span><span class="nv">$port</span><span class="s2">, \&#34;check\&#34;: \&#34;enabled\&#34;}&#34;</span>
</span></span><span class="line"><span class="cl"><span class="o">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">remove_server<span class="o">()</span> <span class="o">{</span>
</span></span><span class="line"><span class="cl">  <span class="nb">local</span> <span class="nv">name</span><span class="o">=</span><span class="nv">$1</span>
</span></span><span class="line"><span class="cl">  <span class="nb">local</span> <span class="nv">txn</span><span class="o">=</span><span class="nv">$2</span>
</span></span><span class="line"><span class="cl">  
</span></span><span class="line"><span class="cl">  curl -s --fail-with-body -u <span class="nv">$AUTH</span> -X DELETE <span class="se">\
</span></span></span><span class="line"><span class="cl">    <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/configuration/backends/</span><span class="nv">$BACKEND</span><span class="s2">/servers/</span><span class="si">${</span><span class="nv">name</span><span class="si">}</span><span class="s2">?transaction_id=</span><span class="nv">$txn</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl"><span class="o">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">commit_transaction<span class="o">()</span> <span class="o">{</span>
</span></span><span class="line"><span class="cl">  curl -s --fail-with-body -u <span class="nv">$AUTH</span> -X PUT <span class="se">\
</span></span></span><span class="line"><span class="cl">    <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/transactions/</span><span class="nv">$1</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl"><span class="o">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">deploy_environment<span class="o">()</span> <span class="o">{</span>
</span></span><span class="line"><span class="cl">  <span class="nb">local</span> <span class="nv">target</span><span class="o">=</span><span class="nv">$1</span>
</span></span><span class="line"><span class="cl">  <span class="nb">local</span> servers_to_add
</span></span><span class="line"><span class="cl">  <span class="nb">local</span> servers_to_remove
</span></span><span class="line"><span class="cl">  
</span></span><span class="line"><span class="cl">  <span class="k">if</span> <span class="o">[</span> <span class="s2">&#34;</span><span class="nv">$target</span><span class="s2">&#34;</span> <span class="o">==</span> <span class="s2">&#34;green&#34;</span> <span class="o">]</span><span class="p">;</span> <span class="k">then</span>
</span></span><span class="line"><span class="cl">    <span class="nv">servers_to_add</span><span class="o">=(</span><span class="s2">&#34;</span><span class="si">${</span><span class="nv">GREEN_SERVERS</span><span class="p">[@]</span><span class="si">}</span><span class="s2">&#34;</span><span class="o">)</span>
</span></span><span class="line"><span class="cl">    <span class="nv">servers_to_remove</span><span class="o">=(</span><span class="s2">&#34;</span><span class="si">${</span><span class="nv">BLUE_SERVERS</span><span class="p">[@]</span><span class="si">}</span><span class="s2">&#34;</span><span class="o">)</span>
</span></span><span class="line"><span class="cl">  <span class="k">else</span>
</span></span><span class="line"><span class="cl">    <span class="nv">servers_to_add</span><span class="o">=(</span><span class="s2">&#34;</span><span class="si">${</span><span class="nv">BLUE_SERVERS</span><span class="p">[@]</span><span class="si">}</span><span class="s2">&#34;</span><span class="o">)</span>
</span></span><span class="line"><span class="cl">    <span class="nv">servers_to_remove</span><span class="o">=(</span><span class="s2">&#34;</span><span class="si">${</span><span class="nv">GREEN_SERVERS</span><span class="p">[@]</span><span class="si">}</span><span class="s2">&#34;</span><span class="o">)</span>
</span></span><span class="line"><span class="cl">  <span class="k">fi</span>
</span></span><span class="line"><span class="cl">  
</span></span><span class="line"><span class="cl">  <span class="nb">echo</span> <span class="s2">&#34;Switching to </span><span class="nv">$target</span><span class="s2"> environment...&#34;</span>
</span></span><span class="line"><span class="cl">  
</span></span><span class="line"><span class="cl">  <span class="nv">VERSION</span><span class="o">=</span><span class="k">$(</span>get_version<span class="k">)</span>
</span></span><span class="line"><span class="cl">  <span class="nv">TXN</span><span class="o">=</span><span class="k">$(</span>start_transaction <span class="nv">$VERSION</span><span class="k">)</span>
</span></span><span class="line"><span class="cl">  
</span></span><span class="line"><span class="cl">  <span class="c1"># Add new servers</span>
</span></span><span class="line"><span class="cl">  <span class="k">for</span> server in <span class="s2">&#34;</span><span class="si">${</span><span class="nv">servers_to_add</span><span class="p">[@]</span><span class="si">}</span><span class="s2">&#34;</span><span class="p">;</span> <span class="k">do</span>
</span></span><span class="line"><span class="cl">    <span class="nv">IFS</span><span class="o">=</span><span class="s1">&#39;:&#39;</span> <span class="nb">read</span> -r name addr port <span class="o">&lt;&lt;&lt;</span> <span class="s2">&#34;</span><span class="nv">$server</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="nb">echo</span> <span class="s2">&#34;Adding </span><span class="nv">$name</span><span class="s2"> (</span><span class="nv">$addr</span><span class="s2">:</span><span class="nv">$port</span><span class="s2">)&#34;</span>
</span></span><span class="line"><span class="cl">    add_server <span class="nv">$name</span> <span class="nv">$addr</span> <span class="nv">$port</span> <span class="nv">$TXN</span>
</span></span><span class="line"><span class="cl">  <span class="k">done</span>
</span></span><span class="line"><span class="cl">  
</span></span><span class="line"><span class="cl">  <span class="c1"># Remove old servers</span>
</span></span><span class="line"><span class="cl">  <span class="k">for</span> server in <span class="s2">&#34;</span><span class="si">${</span><span class="nv">servers_to_remove</span><span class="p">[@]</span><span class="si">}</span><span class="s2">&#34;</span><span class="p">;</span> <span class="k">do</span>
</span></span><span class="line"><span class="cl">    <span class="nv">IFS</span><span class="o">=</span><span class="s1">&#39;:&#39;</span> <span class="nb">read</span> -r name addr port <span class="o">&lt;&lt;&lt;</span> <span class="s2">&#34;</span><span class="nv">$server</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="nb">echo</span> <span class="s2">&#34;Removing </span><span class="nv">$name</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">    remove_server <span class="nv">$name</span> <span class="nv">$TXN</span> 2&gt;/dev/null <span class="o">||</span> <span class="nb">true</span>
</span></span><span class="line"><span class="cl">  <span class="k">done</span>
</span></span><span class="line"><span class="cl">  
</span></span><span class="line"><span class="cl">  commit_transaction <span class="nv">$TXN</span>
</span></span><span class="line"><span class="cl">  <span class="nb">echo</span> <span class="s2">&#34;Deployment complete!&#34;</span>
</span></span><span class="line"><span class="cl"><span class="o">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">case</span> <span class="s2">&#34;</span><span class="nv">$1</span><span class="s2">&#34;</span> in
</span></span><span class="line"><span class="cl">  blue<span class="o">)</span>  deploy_environment blue <span class="p">;;</span>
</span></span><span class="line"><span class="cl">  green<span class="o">)</span> deploy_environment green <span class="p">;;</span>
</span></span><span class="line"><span class="cl">  *<span class="o">)</span>     <span class="nb">echo</span> <span class="s2">&#34;Usage: </span><span class="nv">$0</span><span class="s2"> {blue|green}&#34;</span> <span class="p">;;</span>
</span></span><span class="line"><span class="cl"><span class="k">esac</span>
</span></span></code></pre></div><h3 id="canary-deployment-script">Canary Deployment Script <a class="anchor" data-pagefind-ignore href="#canary-deployment-script" aria-label="Link to this section">#</a></h3>
<p>Adds one canary server with weight 0, then raises its weight step by step.</p>
<table>
	<thead>
			<tr>
					<th>Command</th>
					<th>What it does</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>add</code></td>
					<td>Adds <code>web-canary</code> to the configuration with weight 0: it receives no traffic yet.</td>
			</tr>
			<tr>
					<td><code>shift &lt;n&gt;</code></td>
					<td>Sets the canary&rsquo;s runtime weight to <code>n</code>. No reload.</td>
			</tr>
			<tr>
					<td><code>remove</code></td>
					<td>Deletes the canary from the configuration.</td>
			</tr>
	</tbody>
</table>
<p>Two things to keep in mind:</p>
<ul>
<li>The weight is relative to the other servers in the backend, and the script does not change those. The printed percentage only matches when the production weights add up to <code>100 - n</code>.</li>
<li>Runtime weights last until the next reload. Any configuration change sets the canary back to weight 0.</li>
</ul>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="cp">#!/bin/bash
</span></span></span><span class="line"><span class="cl"><span class="c1"># canary-deploy.sh - Gradual traffic shifting to new version</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nb">set</span> -e
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nv">HAPROXY_API</span><span class="o">=</span><span class="s2">&#34;https://haproxy.example.com:5556/v3&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">AUTH</span><span class="o">=</span><span class="s2">&#34;admin:your-secure-password&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">BACKEND</span><span class="o">=</span><span class="s2">&#34;web_servers&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nv">CANARY_SERVER</span><span class="o">=</span><span class="s2">&#34;web-canary&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">CANARY_ADDRESS</span><span class="o">=</span><span class="s2">&#34;192.168.1.50&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">CANARY_PORT</span><span class="o">=</span><span class="s2">&#34;8080&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">shift_traffic<span class="o">()</span> <span class="o">{</span>
</span></span><span class="line"><span class="cl">  <span class="nb">local</span> <span class="nv">canary_weight</span><span class="o">=</span><span class="nv">$1</span>
</span></span><span class="line"><span class="cl">  <span class="nb">local</span> <span class="nv">production_weight</span><span class="o">=</span><span class="k">$((</span><span class="m">100</span> <span class="o">-</span> canary_weight<span class="k">))</span>
</span></span><span class="line"><span class="cl">  
</span></span><span class="line"><span class="cl">  <span class="nb">echo</span> <span class="s2">&#34;Shifting traffic: Canary=</span><span class="nv">$canary_weight</span><span class="s2">%, Production=</span><span class="nv">$production_weight</span><span class="s2">%&#34;</span>
</span></span><span class="line"><span class="cl">  
</span></span><span class="line"><span class="cl">  <span class="c1"># Use runtime API for immediate weight changes</span>
</span></span><span class="line"><span class="cl">  curl -s -u <span class="nv">$AUTH</span> -X PUT <span class="se">\
</span></span></span><span class="line"><span class="cl">    <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/runtime/backends/</span><span class="nv">$BACKEND</span><span class="s2">/servers/</span><span class="si">${</span><span class="nv">CANARY_SERVER</span><span class="si">}</span><span class="s2">&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    -H <span class="s2">&#34;Content-Type: application/json&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    -d <span class="s2">&#34;{\&#34;weight\&#34;: </span><span class="nv">$canary_weight</span><span class="s2">}&#34;</span>
</span></span><span class="line"><span class="cl"><span class="o">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">add_canary<span class="o">()</span> <span class="o">{</span>
</span></span><span class="line"><span class="cl">  <span class="nv">VERSION</span><span class="o">=</span><span class="k">$(</span>curl -s -u <span class="nv">$AUTH</span> <span class="nv">$HAPROXY_API</span>/services/haproxy/configuration/version<span class="k">)</span>
</span></span><span class="line"><span class="cl">  <span class="nv">TXN</span><span class="o">=</span><span class="k">$(</span>curl -s -u <span class="nv">$AUTH</span> -X POST <span class="se">\
</span></span></span><span class="line"><span class="cl">    <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/transactions?version=</span><span class="nv">$VERSION</span><span class="s2">&#34;</span> <span class="p">|</span> jq -r <span class="s1">&#39;.id&#39;</span><span class="k">)</span>
</span></span><span class="line"><span class="cl">  
</span></span><span class="line"><span class="cl">  curl -s -u <span class="nv">$AUTH</span> -X POST <span class="se">\
</span></span></span><span class="line"><span class="cl">    <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/configuration/backends/</span><span class="nv">$BACKEND</span><span class="s2">/servers?transaction_id=</span><span class="nv">$TXN</span><span class="s2">&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    -H <span class="s2">&#34;Content-Type: application/json&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">    -d <span class="s1">&#39;{
</span></span></span><span class="line"><span class="cl"><span class="s1">      &#34;name&#34;: &#34;&#39;</span><span class="nv">$CANARY_SERVER</span><span class="s1">&#39;&#34;,
</span></span></span><span class="line"><span class="cl"><span class="s1">      &#34;address&#34;: &#34;&#39;</span><span class="nv">$CANARY_ADDRESS</span><span class="s1">&#39;&#34;,
</span></span></span><span class="line"><span class="cl"><span class="s1">      &#34;port&#34;: &#39;</span><span class="nv">$CANARY_PORT</span><span class="s1">&#39;,
</span></span></span><span class="line"><span class="cl"><span class="s1">      &#34;check&#34;: &#34;enabled&#34;,
</span></span></span><span class="line"><span class="cl"><span class="s1">      &#34;weight&#34;: 0
</span></span></span><span class="line"><span class="cl"><span class="s1">    }&#39;</span>
</span></span><span class="line"><span class="cl">  
</span></span><span class="line"><span class="cl">  curl -s -u <span class="nv">$AUTH</span> -X PUT <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/transactions/</span><span class="nv">$TXN</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">  <span class="nb">echo</span> <span class="s2">&#34;Canary server added with 0% traffic&#34;</span>
</span></span><span class="line"><span class="cl"><span class="o">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">remove_canary<span class="o">()</span> <span class="o">{</span>
</span></span><span class="line"><span class="cl">  <span class="nv">VERSION</span><span class="o">=</span><span class="k">$(</span>curl -s -u <span class="nv">$AUTH</span> <span class="nv">$HAPROXY_API</span>/services/haproxy/configuration/version<span class="k">)</span>
</span></span><span class="line"><span class="cl">  <span class="nv">TXN</span><span class="o">=</span><span class="k">$(</span>curl -s -u <span class="nv">$AUTH</span> -X POST <span class="se">\
</span></span></span><span class="line"><span class="cl">    <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/transactions?version=</span><span class="nv">$VERSION</span><span class="s2">&#34;</span> <span class="p">|</span> jq -r <span class="s1">&#39;.id&#39;</span><span class="k">)</span>
</span></span><span class="line"><span class="cl">  
</span></span><span class="line"><span class="cl">  curl -s -u <span class="nv">$AUTH</span> -X DELETE <span class="se">\
</span></span></span><span class="line"><span class="cl">    <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/configuration/backends/</span><span class="nv">$BACKEND</span><span class="s2">/servers/</span><span class="si">${</span><span class="nv">CANARY_SERVER</span><span class="si">}</span><span class="s2">?transaction_id=</span><span class="nv">$TXN</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">  
</span></span><span class="line"><span class="cl">  curl -s -u <span class="nv">$AUTH</span> -X PUT <span class="s2">&#34;</span><span class="nv">$HAPROXY_API</span><span class="s2">/services/haproxy/transactions/</span><span class="nv">$TXN</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">  <span class="nb">echo</span> <span class="s2">&#34;Canary server removed&#34;</span>
</span></span><span class="line"><span class="cl"><span class="o">}</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">case</span> <span class="s2">&#34;</span><span class="nv">$1</span><span class="s2">&#34;</span> in
</span></span><span class="line"><span class="cl">  add<span class="o">)</span>    add_canary <span class="p">;;</span>
</span></span><span class="line"><span class="cl">  remove<span class="o">)</span> remove_canary <span class="p">;;</span>
</span></span><span class="line"><span class="cl">  <span class="nb">shift</span><span class="o">)</span>  shift_traffic <span class="nv">$2</span> <span class="p">;;</span>
</span></span><span class="line"><span class="cl">  *<span class="o">)</span>      <span class="nb">echo</span> <span class="s2">&#34;Usage: </span><span class="nv">$0</span><span class="s2"> {add|remove|shift &lt;percentage&gt;}&#34;</span> <span class="p">;;</span>
</span></span><span class="line"><span class="cl"><span class="k">esac</span>
</span></span></code></pre></div><h2 id="python-client-library">Python Client Library <a class="anchor" data-pagefind-ignore href="#python-client-library" aria-label="Link to this section">#</a></h2>
<p>The same calls wrapped in a small class, for tools written in Python.</p>
<ul>
<li><code>add_server</code> and <code>remove_server</code> each run their own transaction, and roll it back when the API rejects the change.</li>
<li><code>set_server_state</code> and <code>set_server_weight</code> are runtime calls: no transaction.</li>
<li><code>session.verify = True</code> checks the API&rsquo;s TLS certificate. Point it at your CA file rather than turning it off.</li>
<li>The <code>time.sleep(6)</code> in the example waits for the reload: a new server only exists in the running HAProxy after <code>reload_delay</code>.</li>
</ul>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="ch">#!/usr/bin/env python3</span>
</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">time</span>
</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">requests</span>
</span></span><span class="line"><span class="cl"><span class="kn">from</span> <span class="nn">requests.auth</span> <span class="kn">import</span> <span class="n">HTTPBasicAuth</span>
</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">json</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">class</span> <span class="nc">HAProxyAPI</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">base_url</span><span class="p">,</span> <span class="n">username</span><span class="p">,</span> <span class="n">password</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">        <span class="bp">self</span><span class="o">.</span><span class="n">base_url</span> <span class="o">=</span> <span class="n">base_url</span><span class="o">.</span><span class="n">rstrip</span><span class="p">(</span><span class="s1">&#39;/&#39;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">        <span class="bp">self</span><span class="o">.</span><span class="n">auth</span> <span class="o">=</span> <span class="n">HTTPBasicAuth</span><span class="p">(</span><span class="n">username</span><span class="p">,</span> <span class="n">password</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">        <span class="bp">self</span><span class="o">.</span><span class="n">session</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">Session</span><span class="p">()</span>
</span></span><span class="line"><span class="cl">        <span class="bp">self</span><span class="o">.</span><span class="n">session</span><span class="o">.</span><span class="n">auth</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">auth</span>
</span></span><span class="line"><span class="cl">        <span class="bp">self</span><span class="o">.</span><span class="n">session</span><span class="o">.</span><span class="n">verify</span> <span class="o">=</span> <span class="kc">True</span>  <span class="c1"># Set to False for self-signed certs</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="k">def</span> <span class="nf">get_version</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">        <span class="s2">&#34;&#34;&#34;Get current configuration version&#34;&#34;&#34;</span>
</span></span><span class="line"><span class="cl">        <span class="n">r</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">session</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="sa">f</span><span class="s2">&#34;</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">base_url</span><span class="si">}</span><span class="s2">/services/haproxy/configuration/version&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">        <span class="k">return</span> <span class="n">r</span><span class="o">.</span><span class="n">text</span><span class="o">.</span><span class="n">strip</span><span class="p">()</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="k">def</span> <span class="nf">start_transaction</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">version</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">        <span class="s2">&#34;&#34;&#34;Start a new transaction&#34;&#34;&#34;</span>
</span></span><span class="line"><span class="cl">        <span class="k">if</span> <span class="n">version</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">            <span class="n">version</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_version</span><span class="p">()</span>
</span></span><span class="line"><span class="cl">        <span class="n">r</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">session</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="sa">f</span><span class="s2">&#34;</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">base_url</span><span class="si">}</span><span class="s2">/services/haproxy/transactions?version=</span><span class="si">{</span><span class="n">version</span><span class="si">}</span><span class="s2">&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">        <span class="k">return</span> <span class="n">r</span><span class="o">.</span><span class="n">json</span><span class="p">()[</span><span class="s1">&#39;id&#39;</span><span class="p">]</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="k">def</span> <span class="nf">commit_transaction</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">txn_id</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">        <span class="s2">&#34;&#34;&#34;Commit a transaction&#34;&#34;&#34;</span>
</span></span><span class="line"><span class="cl">        <span class="n">r</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">session</span><span class="o">.</span><span class="n">put</span><span class="p">(</span><span class="sa">f</span><span class="s2">&#34;</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">base_url</span><span class="si">}</span><span class="s2">/services/haproxy/transactions/</span><span class="si">{</span><span class="n">txn_id</span><span class="si">}</span><span class="s2">&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">        <span class="k">return</span> <span class="n">r</span><span class="o">.</span><span class="n">status_code</span> <span class="o">==</span> <span class="mi">202</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="k">def</span> <span class="nf">rollback_transaction</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">txn_id</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">        <span class="s2">&#34;&#34;&#34;Rollback a transaction&#34;&#34;&#34;</span>
</span></span><span class="line"><span class="cl">        <span class="n">r</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">session</span><span class="o">.</span><span class="n">delete</span><span class="p">(</span><span class="sa">f</span><span class="s2">&#34;</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">base_url</span><span class="si">}</span><span class="s2">/services/haproxy/transactions/</span><span class="si">{</span><span class="n">txn_id</span><span class="si">}</span><span class="s2">&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">        <span class="k">return</span> <span class="n">r</span><span class="o">.</span><span class="n">status_code</span> <span class="o">==</span> <span class="mi">204</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="k">def</span> <span class="nf">get_backends</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">        <span class="s2">&#34;&#34;&#34;List all backends&#34;&#34;&#34;</span>
</span></span><span class="line"><span class="cl">        <span class="n">r</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">session</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="sa">f</span><span class="s2">&#34;</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">base_url</span><span class="si">}</span><span class="s2">/services/haproxy/configuration/backends&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">        <span class="k">return</span> <span class="n">r</span><span class="o">.</span><span class="n">json</span><span class="p">()</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="k">def</span> <span class="nf">get_servers</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">backend</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">        <span class="s2">&#34;&#34;&#34;List servers in a backend&#34;&#34;&#34;</span>
</span></span><span class="line"><span class="cl">        <span class="n">r</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">session</span><span class="o">.</span><span class="n">get</span><span class="p">(</span>
</span></span><span class="line"><span class="cl">            <span class="sa">f</span><span class="s2">&#34;</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">base_url</span><span class="si">}</span><span class="s2">/services/haproxy/configuration/backends/</span><span class="si">{</span><span class="n">backend</span><span class="si">}</span><span class="s2">/servers&#34;</span>
</span></span><span class="line"><span class="cl">        <span class="p">)</span>
</span></span><span class="line"><span class="cl">        <span class="k">return</span> <span class="n">r</span><span class="o">.</span><span class="n">json</span><span class="p">()</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="k">def</span> <span class="nf">add_server</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">backend</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">address</span><span class="p">,</span> <span class="n">port</span><span class="p">,</span> <span class="n">weight</span><span class="o">=</span><span class="mi">100</span><span class="p">,</span> <span class="n">check</span><span class="o">=</span><span class="kc">True</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">        <span class="s2">&#34;&#34;&#34;Add a server to a backend&#34;&#34;&#34;</span>
</span></span><span class="line"><span class="cl">        <span class="n">txn</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">start_transaction</span><span class="p">()</span>
</span></span><span class="line"><span class="cl">        
</span></span><span class="line"><span class="cl">        <span class="n">data</span> <span class="o">=</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">            <span class="s1">&#39;name&#39;</span><span class="p">:</span> <span class="n">name</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">            <span class="s1">&#39;address&#39;</span><span class="p">:</span> <span class="n">address</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">            <span class="s1">&#39;port&#39;</span><span class="p">:</span> <span class="n">port</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">            <span class="s1">&#39;weight&#39;</span><span class="p">:</span> <span class="n">weight</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">            <span class="s1">&#39;check&#39;</span><span class="p">:</span> <span class="s1">&#39;enabled&#39;</span> <span class="k">if</span> <span class="n">check</span> <span class="k">else</span> <span class="s1">&#39;disabled&#39;</span>
</span></span><span class="line"><span class="cl">        <span class="p">}</span>
</span></span><span class="line"><span class="cl">        
</span></span><span class="line"><span class="cl">        <span class="n">r</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">session</span><span class="o">.</span><span class="n">post</span><span class="p">(</span>
</span></span><span class="line"><span class="cl">            <span class="sa">f</span><span class="s2">&#34;</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">base_url</span><span class="si">}</span><span class="s2">/services/haproxy/configuration/backends/</span><span class="si">{</span><span class="n">backend</span><span class="si">}</span><span class="s2">/servers&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">            <span class="n">params</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;transaction_id&#39;</span><span class="p">:</span> <span class="n">txn</span><span class="p">},</span>
</span></span><span class="line"><span class="cl">            <span class="n">json</span><span class="o">=</span><span class="n">data</span>
</span></span><span class="line"><span class="cl">        <span class="p">)</span>
</span></span><span class="line"><span class="cl">        
</span></span><span class="line"><span class="cl">        <span class="k">if</span> <span class="n">r</span><span class="o">.</span><span class="n">status_code</span> <span class="ow">in</span> <span class="p">[</span><span class="mi">200</span><span class="p">,</span> <span class="mi">201</span><span class="p">,</span> <span class="mi">202</span><span class="p">]:</span>
</span></span><span class="line"><span class="cl">            <span class="bp">self</span><span class="o">.</span><span class="n">commit_transaction</span><span class="p">(</span><span class="n">txn</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">            <span class="k">return</span> <span class="kc">True</span>
</span></span><span class="line"><span class="cl">        <span class="k">else</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">            <span class="bp">self</span><span class="o">.</span><span class="n">rollback_transaction</span><span class="p">(</span><span class="n">txn</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">            <span class="k">return</span> <span class="kc">False</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="k">def</span> <span class="nf">remove_server</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">backend</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">        <span class="s2">&#34;&#34;&#34;Remove a server from a backend&#34;&#34;&#34;</span>
</span></span><span class="line"><span class="cl">        <span class="n">txn</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">start_transaction</span><span class="p">()</span>
</span></span><span class="line"><span class="cl">        
</span></span><span class="line"><span class="cl">        <span class="n">r</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">session</span><span class="o">.</span><span class="n">delete</span><span class="p">(</span>
</span></span><span class="line"><span class="cl">            <span class="sa">f</span><span class="s2">&#34;</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">base_url</span><span class="si">}</span><span class="s2">/services/haproxy/configuration/backends/</span><span class="si">{</span><span class="n">backend</span><span class="si">}</span><span class="s2">/servers/</span><span class="si">{</span><span class="n">name</span><span class="si">}</span><span class="s2">&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">            <span class="n">params</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;transaction_id&#39;</span><span class="p">:</span> <span class="n">txn</span><span class="p">}</span>
</span></span><span class="line"><span class="cl">        <span class="p">)</span>
</span></span><span class="line"><span class="cl">        
</span></span><span class="line"><span class="cl">        <span class="k">if</span> <span class="n">r</span><span class="o">.</span><span class="n">status_code</span> <span class="ow">in</span> <span class="p">[</span><span class="mi">200</span><span class="p">,</span> <span class="mi">202</span><span class="p">,</span> <span class="mi">204</span><span class="p">]:</span>
</span></span><span class="line"><span class="cl">            <span class="bp">self</span><span class="o">.</span><span class="n">commit_transaction</span><span class="p">(</span><span class="n">txn</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">            <span class="k">return</span> <span class="kc">True</span>
</span></span><span class="line"><span class="cl">        <span class="k">else</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">            <span class="bp">self</span><span class="o">.</span><span class="n">rollback_transaction</span><span class="p">(</span><span class="n">txn</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">            <span class="k">return</span> <span class="kc">False</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="k">def</span> <span class="nf">set_server_state</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">backend</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">state</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">        <span class="s2">&#34;&#34;&#34;Set server runtime state (ready/drain/maint)&#34;&#34;&#34;</span>
</span></span><span class="line"><span class="cl">        <span class="n">r</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">session</span><span class="o">.</span><span class="n">put</span><span class="p">(</span>
</span></span><span class="line"><span class="cl">            <span class="sa">f</span><span class="s2">&#34;</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">base_url</span><span class="si">}</span><span class="s2">/services/haproxy/runtime/backends/</span><span class="si">{</span><span class="n">backend</span><span class="si">}</span><span class="s2">/servers/</span><span class="si">{</span><span class="n">name</span><span class="si">}</span><span class="s2">&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">            <span class="n">json</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;admin_state&#39;</span><span class="p">:</span> <span class="n">state</span><span class="p">}</span>
</span></span><span class="line"><span class="cl">        <span class="p">)</span>
</span></span><span class="line"><span class="cl">        <span class="k">return</span> <span class="n">r</span><span class="o">.</span><span class="n">status_code</span> <span class="o">==</span> <span class="mi">200</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="k">def</span> <span class="nf">set_server_weight</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">backend</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">weight</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">        <span class="s2">&#34;&#34;&#34;Set server weight at runtime&#34;&#34;&#34;</span>
</span></span><span class="line"><span class="cl">        <span class="n">r</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">session</span><span class="o">.</span><span class="n">put</span><span class="p">(</span>
</span></span><span class="line"><span class="cl">            <span class="sa">f</span><span class="s2">&#34;</span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">base_url</span><span class="si">}</span><span class="s2">/services/haproxy/runtime/backends/</span><span class="si">{</span><span class="n">backend</span><span class="si">}</span><span class="s2">/servers/</span><span class="si">{</span><span class="n">name</span><span class="si">}</span><span class="s2">&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">            <span class="n">json</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;weight&#39;</span><span class="p">:</span> <span class="n">weight</span><span class="p">}</span>
</span></span><span class="line"><span class="cl">        <span class="p">)</span>
</span></span><span class="line"><span class="cl">        <span class="k">return</span> <span class="n">r</span><span class="o">.</span><span class="n">status_code</span> <span class="o">==</span> <span class="mi">200</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Usage example</span>
</span></span><span class="line"><span class="cl"><span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">&#39;__main__&#39;</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">    <span class="n">api</span> <span class="o">=</span> <span class="n">HAProxyAPI</span><span class="p">(</span>
</span></span><span class="line"><span class="cl">        <span class="s1">&#39;https://haproxy.example.com:5556/v3&#39;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">        <span class="s1">&#39;admin&#39;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">        <span class="s1">&#39;your-secure-password&#39;</span>
</span></span><span class="line"><span class="cl">    <span class="p">)</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="c1"># List backends</span>
</span></span><span class="line"><span class="cl">    <span class="nb">print</span><span class="p">(</span><span class="s2">&#34;Backends:&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="k">for</span> <span class="n">backend</span> <span class="ow">in</span> <span class="n">api</span><span class="o">.</span><span class="n">get_backends</span><span class="p">():</span>
</span></span><span class="line"><span class="cl">        <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">&#34;  - </span><span class="si">{</span><span class="n">backend</span><span class="p">[</span><span class="s1">&#39;name&#39;</span><span class="p">]</span><span class="si">}</span><span class="s2">&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="c1"># List servers</span>
</span></span><span class="line"><span class="cl">    <span class="nb">print</span><span class="p">(</span><span class="s2">&#34;</span><span class="se">\n</span><span class="s2">Servers in web_servers:&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="k">for</span> <span class="n">server</span> <span class="ow">in</span> <span class="n">api</span><span class="o">.</span><span class="n">get_servers</span><span class="p">(</span><span class="s1">&#39;web_servers&#39;</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">        <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">&#34;  - </span><span class="si">{</span><span class="n">server</span><span class="p">[</span><span class="s1">&#39;name&#39;</span><span class="p">]</span><span class="si">}</span><span class="s2">: </span><span class="si">{</span><span class="n">server</span><span class="p">[</span><span class="s1">&#39;address&#39;</span><span class="p">]</span><span class="si">}</span><span class="s2">:</span><span class="si">{</span><span class="n">server</span><span class="p">[</span><span class="s1">&#39;port&#39;</span><span class="p">]</span><span class="si">}</span><span class="s2">&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="c1"># Add a new server</span>
</span></span><span class="line"><span class="cl">    <span class="nb">print</span><span class="p">(</span><span class="s2">&#34;</span><span class="se">\n</span><span class="s2">Adding new server...&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="n">api</span><span class="o">.</span><span class="n">add_server</span><span class="p">(</span><span class="s1">&#39;web_servers&#39;</span><span class="p">,</span> <span class="s1">&#39;web4&#39;</span><span class="p">,</span> <span class="s1">&#39;192.168.1.14&#39;</span><span class="p">,</span> <span class="mi">8080</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="c1"># The new server exists in the running HAProxy only after the reload</span>
</span></span><span class="line"><span class="cl">    <span class="c1"># (reload_delay); before that the runtime call fails with &#34;not found&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">6</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    
</span></span><span class="line"><span class="cl">    <span class="c1"># Put server in maintenance</span>
</span></span><span class="line"><span class="cl">    <span class="nb">print</span><span class="p">(</span><span class="s2">&#34;Setting web4 to maintenance...&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="nb">print</span><span class="p">(</span><span class="n">api</span><span class="o">.</span><span class="n">set_server_state</span><span class="p">(</span><span class="s1">&#39;web_servers&#39;</span><span class="p">,</span> <span class="s1">&#39;web4&#39;</span><span class="p">,</span> <span class="s1">&#39;maint&#39;</span><span class="p">))</span>
</span></span></code></pre></div><h2 id="security-considerations">Security Considerations <a class="anchor" data-pagefind-ignore href="#security-considerations" aria-label="Link to this section">#</a></h2>
<p>The API can rewrite your whole load balancer. Protect it like root access.</p>
<ul>
<li><strong>Close port 5555.</strong> In the configuration above the API listens on <code>0.0.0.0:5555</code> without TLS. Firewall it, so clients can only use the frontend on 5556.</li>
<li><strong>Keep passwords out of scripts.</strong> The examples set <code>AUTH</code> inline for readability; use a masked CI variable like <code>HAPROXY_AUTH</code> instead.</li>
<li><strong>Restrict who can connect</strong>, and add TLS or mTLS on the API itself (below).</li>
</ul>
<h3 id="tls-configuration">TLS Configuration <a class="anchor" data-pagefind-ignore href="#tls-configuration" aria-label="Link to this section">#</a></h3>
<p>The API can terminate TLS itself. <code>tls_ca</code> makes it require client certificates signed by that CA (mTLS). Keep these files outside <code>/etc/haproxy/certs/</code>, as the comment explains.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="c"># dataplaneapi.yaml with TLS</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">dataplaneapi</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">host</span><span class="p">:</span><span class="w"> </span><span class="m">0.0.0.0</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">port</span><span class="p">:</span><span class="w"> </span><span class="m">5555</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">scheme</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="l">https</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">tls</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c"># Not in /etc/haproxy/certs/: HAProxy loads every file in that directory</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="c"># for &#34;bind *:443 ssl crt /etc/haproxy/certs/&#34; and fails on a bare key or CA</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">tls_certificate</span><span class="p">:</span><span class="w"> </span><span class="l">/etc/haproxy/api-tls/api.pem</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">tls_key</span><span class="p">:</span><span class="w"> </span><span class="l">/etc/haproxy/api-tls/api.key</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">tls_ca</span><span class="p">:</span><span class="w"> </span><span class="l">/etc/haproxy/api-tls/ca.pem </span><span class="w"> </span><span class="c"># For mTLS</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">tls_port</span><span class="p">:</span><span class="w"> </span><span class="m">5555</span><span class="w">
</span></span></span></code></pre></div><h3 id="network-restrictions">Network Restrictions <a class="anchor" data-pagefind-ignore href="#network-restrictions" aria-label="Link to this section">#</a></h3>
<p>Extra rules on the API frontend:</p>
<ul>
<li><code>acl allowed_networks</code> with <code>http-request deny</code>: only the management networks reach the API.</li>
<li><code>stick-table</code> and <code>track-sc0</code>: count requests per source IP over 10 seconds; above 100 the client gets a 429.</li>
<li>The rules run in order, so blocked clients are refused before the password check.</li>
</ul>
<pre tabindex="0"><code class="language-haproxy" data-lang="haproxy">frontend dataplane_api
    bind *:5556 ssl crt /etc/haproxy/certs/api.pem
    
    # Restrict to management network
    acl allowed_networks src 10.0.0.0/8 192.168.0.0/16
    http-request deny unless allowed_networks
    
    # Rate limiting
    stick-table type ip size 100k expire 30s store http_req_rate(10s)
    http-request track-sc0 src
    http-request deny deny_status 429 if { sc_http_req_rate(0) gt 100 }
    
    http-request auth unless { http_auth(api_users) }
    default_backend dataplane_api_backend
</code></pre><h2 id="integration-with-cicd">Integration with CI/CD <a class="anchor" data-pagefind-ignore href="#integration-with-cicd" aria-label="Link to this section">#</a></h2>
<h3 id="gitlab-ci-example">GitLab CI Example <a class="anchor" data-pagefind-ignore href="#gitlab-ci-example" aria-label="Link to this section">#</a></h3>
<p>The canary flow as a pipeline. <code>HAPROXY_AUTH</code> (<code>user:password</code>) and <code>CANARY_IP</code> come from CI/CD variables.</p>
<table>
	<thead>
			<tr>
					<th>Job</th>
					<th>Runs</th>
					<th>What it does</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><code>deploy-canary</code></td>
					<td>Automatically on <code>main</code></td>
					<td>Adds <code>canary</code> with weight 10, in a transaction</td>
			</tr>
			<tr>
					<td><code>shift-traffic-50</code></td>
					<td>Manual</td>
					<td>Runtime weight 50</td>
			</tr>
			<tr>
					<td><code>promote-canary</code></td>
					<td>Manual</td>
					<td>Runtime weight 100, drains <code>web1</code> to <code>web3</code></td>
			</tr>
	</tbody>
</table>
<p>The runtime weights go back to 10 at the next reload. Make the promotion permanent with a configuration change.</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="c"># .gitlab-ci.yml</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">stages</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- <span class="l">deploy</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- <span class="l">traffic</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">variables</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">HAPROXY_API</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;https://haproxy.example.com:5556/v3&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">deploy-canary</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">stage</span><span class="p">:</span><span class="w"> </span><span class="l">deploy</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">script</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="p">|</span><span class="sd">
</span></span></span><span class="line"><span class="cl"><span class="sd">      # Add canary server
</span></span></span><span class="line"><span class="cl"><span class="sd">      VERSION=$(curl -s -u $HAPROXY_AUTH $HAPROXY_API/services/haproxy/configuration/version)
</span></span></span><span class="line"><span class="cl"><span class="sd">      TXN=$(curl -s -u $HAPROXY_AUTH -X POST \
</span></span></span><span class="line"><span class="cl"><span class="sd">        &#34;$HAPROXY_API/services/haproxy/transactions?version=$VERSION&#34; | jq -r &#39;.id&#39;)
</span></span></span><span class="line"><span class="cl"><span class="sd">      
</span></span></span><span class="line"><span class="cl"><span class="sd">      curl -s -u $HAPROXY_AUTH -X POST \
</span></span></span><span class="line"><span class="cl"><span class="sd">        &#34;$HAPROXY_API/services/haproxy/configuration/backends/app_servers/servers?transaction_id=$TXN&#34; \
</span></span></span><span class="line"><span class="cl"><span class="sd">        -H &#34;Content-Type: application/json&#34; \
</span></span></span><span class="line"><span class="cl"><span class="sd">        -d &#39;{&#34;name&#34;: &#34;canary&#34;, &#34;address&#34;: &#34;&#39;$CANARY_IP&#39;&#34;, &#34;port&#34;: 8080, &#34;weight&#34;: 10, &#34;check&#34;: &#34;enabled&#34;}&#39;
</span></span></span><span class="line"><span class="cl"><span class="sd">      
</span></span></span><span class="line"><span class="cl"><span class="sd">      curl -s -u $HAPROXY_AUTH -X PUT &#34;$HAPROXY_API/services/haproxy/transactions/$TXN&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">only</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="l">main</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">shift-traffic-50</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">stage</span><span class="p">:</span><span class="w"> </span><span class="l">traffic</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">script</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="p">|</span><span class="sd">
</span></span></span><span class="line"><span class="cl"><span class="sd">      curl -s -u $HAPROXY_AUTH -X PUT \
</span></span></span><span class="line"><span class="cl"><span class="sd">        &#34;$HAPROXY_API/services/haproxy/runtime/backends/app_servers/servers/canary&#34; \
</span></span></span><span class="line"><span class="cl"><span class="sd">        -H &#34;Content-Type: application/json&#34; \
</span></span></span><span class="line"><span class="cl"><span class="sd">        -d &#39;{&#34;weight&#34;: 50}&#39;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">when</span><span class="p">:</span><span class="w"> </span><span class="l">manual</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">only</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="l">main</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">promote-canary</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">stage</span><span class="p">:</span><span class="w"> </span><span class="l">traffic</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">script</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="p">|</span><span class="sd">
</span></span></span><span class="line"><span class="cl"><span class="sd">      # Shift all traffic to canary
</span></span></span><span class="line"><span class="cl"><span class="sd">      curl -s -u $HAPROXY_AUTH -X PUT \
</span></span></span><span class="line"><span class="cl"><span class="sd">        &#34;$HAPROXY_API/services/haproxy/runtime/backends/app_servers/servers/canary&#34; \
</span></span></span><span class="line"><span class="cl"><span class="sd">        -H &#34;Content-Type: application/json&#34; \
</span></span></span><span class="line"><span class="cl"><span class="sd">        -d &#39;{&#34;weight&#34;: 100}&#39;
</span></span></span><span class="line"><span class="cl"><span class="sd">      
</span></span></span><span class="line"><span class="cl"><span class="sd">      # Set old servers to drain (without the JSON header the API answers 415)
</span></span></span><span class="line"><span class="cl"><span class="sd">      for server in web1 web2 web3; do
</span></span></span><span class="line"><span class="cl"><span class="sd">        curl -s -u $HAPROXY_AUTH -X PUT \
</span></span></span><span class="line"><span class="cl"><span class="sd">          &#34;$HAPROXY_API/services/haproxy/runtime/backends/app_servers/servers/${server}&#34; \
</span></span></span><span class="line"><span class="cl"><span class="sd">          -H &#34;Content-Type: application/json&#34; \
</span></span></span><span class="line"><span class="cl"><span class="sd">          -d &#39;{&#34;admin_state&#34;: &#34;drain&#34;}&#39;
</span></span></span><span class="line"><span class="cl"><span class="sd">      done</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">when</span><span class="p">:</span><span class="w"> </span><span class="l">manual</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">only</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span>- <span class="l">main</span><span class="w">
</span></span></span></code></pre></div><h2 id="troubleshooting">Troubleshooting <a class="anchor" data-pagefind-ignore href="#troubleshooting" aria-label="Link to this section">#</a></h2>
<h3 id="check-api-status">Check API Status <a class="anchor" data-pagefind-ignore href="#check-api-status" aria-label="Link to this section">#</a></h3>
<p>Is the API up, are transactions left open, and what does HAProxy report?</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Test API connectivity</span>
</span></span><span class="line"><span class="cl">curl -v -u <span class="nv">$AUTH</span> <span class="nv">$HAPROXY_API</span>/info
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Check pending transactions</span>
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> <span class="nv">$HAPROXY_API</span>/services/haproxy/transactions <span class="p">|</span> jq .
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># View HAProxy stats</span>
</span></span><span class="line"><span class="cl">curl -s -u <span class="nv">$AUTH</span> <span class="nv">$HAPROXY_API</span>/services/haproxy/stats/native <span class="p">|</span> jq .
</span></span></code></pre></div><h3 id="common-issues">Common Issues <a class="anchor" data-pagefind-ignore href="#common-issues" aria-label="Link to this section">#</a></h3>
<table>
	<thead>
			<tr>
					<th>Symptom</th>
					<th>Cause / fix</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>Transaction or commit rejected over the version</td>
					<td>Another change came first. Fetch a fresh version and start again.</td>
			</tr>
			<tr>
					<td><code>401</code></td>
					<td>Wrong user or password. Through port 5556, check both <code>dataplaneapi.yaml</code> and <code>userlist api_users</code>.</td>
			</tr>
			<tr>
					<td><code>415</code></td>
					<td>The request has no <code>Content-Type: application/json</code> header.</td>
			</tr>
			<tr>
					<td><code>Error saving configuration: ... permission denied</code></td>
					<td>The API does not run as root. See the systemd unit.</td>
			</tr>
			<tr>
					<td>Change rejected as invalid</td>
					<td>Check the current state with the GET endpoints first.</td>
			</tr>
			<tr>
					<td>Reload fails</td>
					<td>Check the syntax with <code>haproxy -c -f /etc/haproxy/haproxy.cfg</code>.</td>
			</tr>
			<tr>
					<td>Runtime call on a new server says &ldquo;not found&rdquo;</td>
					<td>The reload has not happened yet. Wait <code>reload_delay</code>.</td>
			</tr>
			<tr>
					<td>A runtime weight or state is back to its old value</td>
					<td>A reload happened. Runtime changes do not survive it.</td>
			</tr>
	</tbody>
</table>
<h2 id="automate-it">Automate it <a class="anchor" data-pagefind-ignore href="#automate-it" aria-label="Link to this section">#</a></h2>
<p>The Ansible roles and Terraform code that build this setup are on GitHub:
<a href="https://github.com/pderuiter/blog-haproxy-dataplane-api" rel="noopener">pderuiter/blog-haproxy-dataplane-api</a>. It creates an Ubuntu 24.04 VM, installs HAProxy from the official packages and the Data Plane API 3.x behind the TLS frontend from this post; put your <code>mkpasswd</code> hash in the vault and run <code>ansible-playbook site.yml</code>.</p>
<h2 id="next-steps">Next Steps <a class="anchor" data-pagefind-ignore href="#next-steps" aria-label="Link to this section">#</a></h2>
<ul>
<li><strong>Service Discovery Integration</strong> - Let the API build backends from Consul: see the <a href="https://blog.bsdserver.nl/haproxy-and-consul-dynamic-service-discovery-for-load-balancing/">Consul post</a></li>
<li><strong>Monitoring</strong> - Track configuration changes and performance metrics</li>
<li><strong>GitOps</strong> - Version control your HAProxy configuration changes</li>
</ul>
<p>With the Data Plane API, HAProxy changes become HTTP calls that scripts and pipelines can make safely.</p>
]]></content:encoded></item></channel></rss>