From fda991001bd8796243f1a8e46628d6e8b1ee43fe Mon Sep 17 00:00:00 2001 From: OpenCode Date: Fri, 5 Jun 2026 09:41:37 +0200 Subject: [PATCH] Add article for hypernode-haproxyctl --- docs/hypernode-platform/cluster.md | 2 + .../how-to-use-hypernode-haproxyctl-tool.md | 51 +++++++++++++++++++ 2 files changed, 53 insertions(+) create mode 100644 docs/hypernode-platform/tools/how-to-use-hypernode-haproxyctl-tool.md diff --git a/docs/hypernode-platform/cluster.md b/docs/hypernode-platform/cluster.md index 698d95de..f609a018 100644 --- a/docs/hypernode-platform/cluster.md +++ b/docs/hypernode-platform/cluster.md @@ -85,6 +85,8 @@ least connections. Web traffic is terminated by NGINX, which (optionally) forwards the request to varnish, which can return a cached page or send the request to [HAProxy](https://www.haproxy.org/), which sends the request to the application servers. +To manage the HAProxy service, you can use our utility command `hypernode-haproxyctl`. Learn more about this command in our [hypernode-haproxyctl documentation](tools/how-to-use-hypernode-haproxyctl-tool.md). + ### Managing NGINX To add custom NGINX rules for handling specific things on the loadbalancer (like serving assets), the `loadbalancer.` prefix can be diff --git a/docs/hypernode-platform/tools/how-to-use-hypernode-haproxyctl-tool.md b/docs/hypernode-platform/tools/how-to-use-hypernode-haproxyctl-tool.md new file mode 100644 index 00000000..45818306 --- /dev/null +++ b/docs/hypernode-platform/tools/how-to-use-hypernode-haproxyctl-tool.md @@ -0,0 +1,51 @@ +--- +myst: + html_meta: + description: 'With the hypernode-haproxyctl tool you can inspect and manage the + HAProxy service. Learn how to use the hypernode-haproxy CLI Tool. ' + title: How to use the hypernode-haproxyctl CLI Tool? +--- + +# How to Use the hypernode-haproxyctl CLI Tool + +Hypernode clusters use [HAProxy](https://www.haproxy.org/) to distribute HTTP requests from the loadbalancer to the application servers. With the `hypernode-haproxyctl` CLI tool you can inspect and manage the HAProxy service. + +## Viewing the current status + +With the `status` subcommand, you can see the current status of HAProxy and its backends. + +```console +app@abcdef-examplelb-magweb-tbbm ~ $ hypernode-haproxyctl status +HAProxy v2.6.12-1+deb12u3 (released: 2025/10/03, uptime: 98d 22h33m56s) +FRONTEND (OPEN): request rate(160), session rate(7), conn rate(7) +exampleapp1 (UP): request rate(0), session rate(25), conn rate(0) +exampleapp2 (UP): request rate(0), session rate(32), conn rate(0) +exampleapp3 (UP): request rate(0), session rate(28), conn rate(0) +exampleapp4 (UP): request rate(0), session rate(38), conn rate(0) +exampleapp5 (UP): request rate(0), session rate(35), conn rate(0) +BACKEND (UP): request rate(0), session rate(160), conn rate(0) +``` + +The output has three sections: + +- **FRONTEND**: The internet-facing entry point. Shows how many requests and connections are coming in per second. +- **exampleapp1-N**: Your individual app servers. Common states are `UP`, `DOWN` and `DRAIN`. +- **BACKEND**: The combined pool of all app servers. `UP` means at least one server is healthy. + +If a server shows `DOWN` unexpectedly, it likely needs attention. `DRAIN` and `MAINTENANCE` are usually intentional states used during maintenance. + +## Managing backends + +When troubleshooting or performing maintenance on an app server, you can use the `drain` subcommand to gracefully remove it from rotation: + +```console +app@abcdef-examplelb-magweb-tbbm ~ $ hypernode-haproxyctl drain exampleapp1 +``` + +The `drain` command allows existing connections to finish while preventing new traffic from being sent to the server. This is ideal for performing maintenance without disrupting active users. + +Once maintenance is complete, you can use the `enable` subcommand to bring the server back into rotation: + +```console +app@abcdef-examplelb-magweb-tbbm ~ $ hypernode-haproxyctl enable exampleapp1 +```