HAProxy

​

Overview

• Run it directly to get a managed HAProxy load balancer with sensible defaults
• Inherit it in your own runnable to seamlessly add load balancing and high availability to your services

​

What this template manages

• HAProxy container (haproxy image, configurable tag)
• Network service on port 8080 (configurable)
• Custom HAProxy configuration file
• Backend server routing and health checking
• Connection timeouts and load balancing algorithms

​

Quick start (run directly)

1. Load templates

monk load MANIFEST

2. Run HAProxy with defaults

monk run haproxy/haproxy

3. Customize backend servers (recommended via inheritance)

• Preferred: inherit and override variables with your backend configuration as shown below.
• Alternative: fork/clone and edit the variables in haproxy.yml, then monk load MANIFEST and run.

​

Configuration

variables:
  haproxy-image: "2.7.1"          # container image tag
  haproxy-port-number: 8080       # internal service port
  host-port-number: 8080          # host-exposed port
  backend-hostname: "1.1.1.1"     # backend server address
  backend-port: "443"             # backend server port

​

Use by inheritance (recommended for apps)

namespace: myapp
loadbalancer:
  defines: runnable
  inherits: haproxy/haproxy
  variables:
    backend-hostname: <- connection-hostname("backend")
    backend-port: "8080"
backend:
  defines: runnable
  containers:
    app:
      image: myorg/app
  services:
    api:
      container: app
      port: 8080
      protocol: tcp
  connections:
    proxy:
      runnable: loadbalancer
      service: haproxy

monk run myapp/backend

​

Ports and connectivity

• Service: haproxy on TCP port 8080 (configurable via haproxy-port-number)
• Host exposure: Port 8080 (configurable via host-port-number)
• From other runnables in the same process group, use connection-hostname("\<connection-name>") to resolve the load balancer.

​

Persistence and configuration

• Configuration file: files/haproxy.cfg - mounted to /usr/local/etc/haproxy/haproxy.cfg in the container
• The configuration supports Monk variable interpolation for dynamic backend configuration
• No persistent data storage required (HAProxy is stateless)

​

Features

• Layer 4 (TCP) and Layer 7 (HTTP) load balancing
• SSL/TLS termination
• Health checking with automatic failover
• Sticky sessions (session affinity)
• Advanced routing and URL rewriting
• ACL-based traffic rules
• High performance (100K+ concurrent connections)
• Built-in DNS resolution for dynamic backends

​

Related templates

• See other templates in this repository for complementary services
• Combine with monitoring tools (prometheus-grafana/) for observability
• Use with application servers (nginx/, apache/) for complete web stack
• Integrate with your application stack as needed

​

Troubleshooting

• Check logs:

monk logs -l 500 -f haproxy/haproxy

• If backend servers are not responding, verify the backend-hostname and backend-port values match your backend configuration.
• Ensure backend servers are reachable from the HAProxy container’s network.
• For custom configurations, validate your haproxy.cfg syntax before running.