Blocks · Web and proxies

net/haproxy

HAProxy load balancer. HAProxy balancing TCP and HTTP over health-checked servers, as stateless replicas behind a VIP.

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

haproxy.yaml
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.

KeyDefaultMeaning
frontendsrequired, or configListeners, each balancing over its own servers. The deploy form lists existing blocks' addresses for the servers.
frontends[].namerequiredName in stats and metrics (fe_<name>, be_<name>).
frontends[].portrequiredListen port, 1024 or above (HAProxy runs unprivileged).
frontends[].serversrequiredServers as host:port. Names resolve once, at start.
frontends[].modehttphttp adds X-Forwarded-For and checks with an HTTP GET; tcp forwards bytes.
frontends[].balanceroundrobinroundrobin, leastconn, source or first.
frontends[].checktrueCheck 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.
statsPortnoneServes the stats page at /stats and Prometheus metrics at /metrics.
maxconn4096Global connection limit.
confignoneA 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 config with bind ... ssl crt, or put web/caddy in 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

All block types · Fields every block shares