Overview
Runs HAProxy as a TCP and HTTP load balancer. HAProxy keeps no state, so the block runs several replicas on different nodes behind one VIP and needs no volume. Each replica health-checks every server itself and stops sending to one that fails. The block writes haproxy.cfg from frontends on every start; a whole config can be given instead.
Expanse's own VIP load balancer already spreads traffic over a block's replicas. Use HAProxy when you need what it adds: servers that are not blocks, active health checks, balancing algorithms, and HAProxy's stats and metrics.
- Shape
- Stateless replicas
- Reached at
- VIP
- Node package
pkgs.haproxy
Fetched on demand: the first time a block of this type is placed on a node, its agent fetches pkgs.haproxy, built from the node's own nixpkgs so the NixOS binary cache serves it. That first placement needs network access (or a binary cache on the LAN) and waits for the download; later placements on that node start at once.
Example
apiVersion: expanse.io/v1 kind: Block metadata: name: lb namespace: default spec: type: net/haproxy replicas: 2 placement: antiAffinity: ANTI_AFFINITY_NODE resources: requests: cpu: 100m memory: 64Mi config: statsPort: 18404 frontends: - name: web port: 18080 servers: ["app1.lan:8080", "app2.lan:8080"] checkPath: /healthz - name: db port: 15432 mode: tcp balance: leastconn servers: ["10.0.0.31:5432", "10.0.0.32:5432"] network: ports: - name: http port: 80 target_port: 18080 protocol: tcp expose: EXPOSE_VIP - name: db port: 5432 target_port: 15432 protocol: tcp expose: EXPOSE_VIP health_check: readiness: type: PROBE_TCP port: 18080 period_seconds: 2
$ expanse ctl block apply -f haproxy.yaml --dry-run # validate only $ expanse ctl block apply -f haproxy.yaml
Configuration
Give either frontends or config.
Keys go under spec.config and are checked against the type's JSON Schema when the block is applied. A default is what the block uses when the key is unset.
| Key | Default | Meaning |
|---|---|---|
frontends | required, or config | Listeners, each balancing over its own servers. The deploy form lists existing blocks' addresses for the servers. |
frontends[].name | required | Name in stats and metrics (fe_<name>, be_<name>). |
frontends[].port | required | Listen port, 1024 or above (HAProxy runs unprivileged). |
frontends[].servers | required | Servers as host:port. Names resolve once, at start. |
frontends[].mode | http | http adds X-Forwarded-For and checks with an HTTP GET; tcp forwards bytes. |
frontends[].balance | roundrobin | roundrobin, leastconn, source or first. |
frontends[].check | true | Check servers every 2 s; two failures take one out, two passes bring it back. |
frontends[].checkPath | / | HTTP mode: the path checked; any 2xx or 3xx passes. |
statsPort | none | Serves the stats page at /stats and Prometheus metrics at /metrics. |
maxconn | 4096 | Global connection limit. |
config | none | A whole haproxy.cfg, used instead of everything above. |
Using it
Each frontend listens on its own port on every replica's node. Expose it on the VIP with a network.ports entry whose target_port is that port; the exposed port must differ from it. The VIP spreads connections over the replicas on every node, so a node firewall must let the other nodes reach each frontend port.
A server name that does not resolve at start leaves that server down rather than stopping HAProxy. A name takes the first address the node's resolver returns, which is IPv6 when the name has one; give an IPv4 address if the server listens on IPv4 only. The stats port is not on the VIP: read each replica at its node's address.
When a node fails
A server fails: each replica takes it out of rotation after two failed checks, 2 to 4 s later. When it passes two checks it gets traffic again.
A replica's node fails: if it held the VIP, the VIP moves to a node running the other replica and connections through it are lost; clients reconnect to the same address. The controller then places a new replica on a spare node, if there is one. In Expanse's VM test, requests through the VIP succeeded again 6 to 15 s after the VIP holder was killed.
Limits
- No TLS termination in the generated config; use
configwithbind ... ssl crt, or putweb/caddyin front. - Server names are not resolved again while running, and there is no DNS service discovery.
- Sticky sessions only through
balance: source. - UDP: VIPs forward TCP only.
Source
- docs/HAPROXY.md: the Expanse guide this page follows.
- nix/blocks/net/haproxy: the type's identity and JSON Schema.