Learn HAProxy - HTTP Routing, Headers & Rewrite

#Introduction

In episode 4 you already saw ACLs and use_backend. Episode 6 takes HTTP handling to the next level: smarter routing based on path, host, and headers, header manipulation in both directions, redirects, and cookie-based session affinity.

These are the capabilities that make HAProxy worthy of being called an API gateway and application delivery controller, not just a packet forwarder. The configuration in this episode will be your main asset for episodes 11 and 16.

#Path-Based and Host-Based Routing

#Path-Based Routing

Path-based routing separates traffic based on parts of the URL:

frontend web_front
    bind *:80
    mode http
 
    acl is_api    path_beg /api
    acl is_admin  path_beg /admin
    acl is_static path_end .png .jpg .css .js
 
    use_backend api_back     if is_api
    use_backend admin_back   if is_admin
    use_backend static_back  if is_static
    default_backend web_back

The line acl is_api path_beg /api creates a condition that is true when the path starts with /api. The patterns used: path_beg for prefixes, path_end for suffixes, and path_reg for regexes.

#Host-Based Routing

Host-based routing separates traffic based on the domain name, the basic virtual hosting pattern:

frontend web_front
    bind *:80
    mode http
 
    acl host_app1 hdr(host) -i app1.example.com
    acl host_app2 hdr(host) -i app2.example.com
 
    use_backend app1_back if host_app1
    use_backend app2_back if host_app2
    default_backend web_back

The acl host_app1 hdr(host) -i app1.example.com directive matches the Host header case-insensitively thanks to the -i option.

#Matching Based on Headers

#Header ACLs for Routing Decisions

Besides Host, other headers can be used as a basis for decisions:

frontend web_front
    bind *:80
    mode http
 
    acl is_mobile hdr(user-agent) -i android iphone
    acl is_internal hdr(x-internal) -m str yes
 
    use_backend mobile_back if is_mobile
    use_backend internal_back if is_internal
    default_backend web_back

acl is_mobile hdr(user-agent) -i android iphone is true when the User-Agent contains the word android or iphone. Custom headers like X-Internal can be used for internal service-to-service traffic.

#Header Manipulation and Redirects

#Request Headers

Backends often need information about the client that only HAProxy knows. Headers are modified with http-request set-header:

frontend web_front
    bind *:80
    mode http
 
    http-request set-header X-Real-IP %[src]
    http-request set-header X-Forwarded-Proto http
    http-request del-header X-Internal

The line http-request set-header X-Real-IP %[src] fills a header with the client IP, and http-request del-header X-Internal removes a header that must not reach the backend.

#Response Headers and Redirects

For responses, http-response set-header is used; to move users, http-request redirect:

frontend web_front
    bind *:80
    mode http
 
    acl is_logged hdr(cookie) -m sub session_id
 
    http-response set-header X-Powered-By none
    http-request redirect location /login if !is_logged
 
    default_backend web_back

http-request redirect location /login if !is_logged sends users who aren't logged in to the login page. Redirects are also commonly used to force HTTPS, as in the example in episode 4.

#Cookie-Based Persistence

#Maintaining Session Affinity

Some applications store state in server memory. So sessions aren't lost, HAProxy can insert a cookie that locks a user to one server:

backend web_back
    balance roundrobin
    cookie SERVERID insert indirect nocache
    server web1 10.0.0.11:80 check cookie web1
    server web2 10.0.0.12:80 check cookie web2

The cookie SERVERID insert indirect nocache directive tells HAProxy to insert a cookie named SERVERID, and server web1 10.0.0.11:80 check cookie web1 marks the cookie value for that server.

#How It Works and Considerations

When a client arrives for the first time, HAProxy chooses a server and inserts the cookie. On subsequent requests, the cookie is read and the request is always routed to the same server. Note:

• Persistence is good for sessions, but can pile up load if distribution is unbalanced.
• Use option httpchk so a dead server doesn't receive requests labeled with its cookie.
• Consider leastconn when sessions are long-lived.

curl -s -i http://localhost/ | grep -i set-cookie

curl -s -i http://localhost/ | grep -i set-cookie shows the Set-Cookie header inserted by HAProxy.

#Closing

Episode 6 rounds out your HTTP toolkit: precise routing, two-way header manipulation, redirects, and session affinity. With these capabilities, HAProxy can already act as the traffic-routing brain in front of microservices.

Key takeaways:

• path_beg, path_end, and path_reg for URL-based routing.
• hdr(host) and hdr(user-agent) for header-based routing.
• http-request set-header and http-response set-header for header modification.
• http-request redirect to move clients.
• cookie SERVERID insert maintains cookie-based session affinity.
• Always validate the configuration before reloading.

In the next episode we'll cover logging & basic monitoring — syslog-based logging configuration and log formats, the stats socket and statistics page, and the basics of reading metrics like request rate, response time, and server health status.