Learn HAProxy - HAProxy as an API Gateway

#Introduction

More and more architectures are shaped like microservices, and every service needs a single entry point. HAProxy is a great fit for the API gateway role: receiving all requests, determining the destination service, rewriting, and checking identity.

Episode 11 combines everything you've learned — routing, ACLs, rewriting, and protection — into one door for REST and gRPC, complete with authentication integration and service discovery patterns.

#Reverse Proxy for REST and gRPC

#REST Gateway with Path Rewriting

The big picture: a single domain api.example.com that hosts many services, separated by path prefixes:

frontend api_front
    bind *:443 ssl crt /etc/haproxy/certs/fullchain.pem
    mode http
    option httplog
 
    acl svc_users path_beg /users
    acl svc_orders path_beg /orders
    acl svc_payment path_beg /payment
 
    use_backend users_back if svc_users
    use_backend orders_back if svc_orders
    use_backend payment_back if svc_payment
    default_backend users_back

Each service gets its own path segment. acl svc_users path_beg /users routes requests starting with /users to the users_back backend.

#Rewriting the Path to Keep Backends Simple

Backends often don't want to accept the gateway prefix. Strip the prefix before forwarding:

backend users_back
    balance roundrobin
    option httpchk GET /healthz
    http-request set-path %[path,regsub(^/users/,/)]
    server user1 10.0.0.11:8080 check
    server user2 10.0.0.12:8080 check

http-request set-path %[path,regsub(^/users/,/)] replaces the /users/ prefix with / so the backend receives the service's real path. This technique keeps backends focused on their business domain.

#gRPC Support

gRPC runs on top of HTTP/2 with a special content-type header:

frontend grpc_front
    bind *:443 ssl crt /etc/haproxy/certs/fullchain.pem \
        alpn h2,http/1.1
    mode http
 
    acl is_grpc req.hdr(Content-Type) -i application/grpc
    acl svc_catalog path_beg /catalog.CatalogService/
 
    use_backend grpc_catalog if is_grpc svc_catalog
    default_backend grpc_default

acl is_grpc req.hdr(Content-Type) -i application/grpc detects gRPC traffic from the Content-Type header, and use_backend grpc_catalog if is_grpc svc_catalog routes specific RPC calls to the right backend.

#Authentication Integration

#Forwarding JWT to the Backend

The simplest pattern: HAProxy doesn't validate the token, it just forwards the Authorization header:

frontend api_front
    bind *:443 ssl crt /etc/haproxy/certs/fullchain.pem
    mode http
 
    acl has_token req.hdr(Authorization) -m found
 
    http-request set-header X-User-ID \
        %[req.hdr(Authorization),jwt_payload('sub')]
 
    http-request deny deny_status 401 if !has_token
    default_backend users_back

The %[req.hdr(Authorization),jwt_payload('sub')] directive extracts the sub claim from the JWT and puts it into the X-User-ID header. This way the backend doesn't need to parse the token again to recognize the user.

#External Authentication

For centralized authentication, HAProxy can call an auth service before forwarding the request:

backend auth_check
    server auth 10.0.0.100:8443 ssl verify required \
        ca-file /etc/ssl/certs/ca-certificates.crt
 
frontend api_front
    bind *:443 ssl crt /etc/haproxy/certs/fullchain.pem
    mode http
 
    http-request lua.auth
    http-request deny deny_status 401 if !{ var(txn.authed) -m bool }
 
    default_backend users_back

The example above uses Lua to call an auth endpoint, then var(txn.authed) stores the result. If the result isn't true, the request is rejected with 401 before reaching the backend.

#Keeping Tokens Safe

Some practices when forwarding identity:

• Don't log the full Authorization header; only store a hash or specific claims.
• Replace the token with a short internal token if the backend doesn't need the real JWT.
• Make sure the connection to the auth service uses TLS.

#Microservices and Service Discovery Patterns

#Dynamic Backends with DNS

Backend servers aren't always static. HAProxy can resolve server names from DNS and follow changes:

backend users_back
    balance roundrobin
    server svc users-svc.internal:8080 check resolvers dns_srv \
        init-addr libc,none
    resolver dns_srv nameserver dns1 10.0.0.53:53

The server svc users-svc.internal:8080 check resolvers dns_srv directive makes HAProxy follow the IP from DNS at set intervals. When service discovery updates DNS, HAProxy follows automatically without a reload.

#Separating Responsibilities

A healthy API gateway pattern:

• The frontend only handles routing, rewriting, and light authentication.
• The backend holds service logic and health check endpoints.
• Rate limiting and protection live in the frontend (episode 10).
• Observability is wired at the gateway level so all traffic is monitored.

curl -s -o /dev/null -w "%{http_code}\n" https://api.example.com/users/me -k
curl -s -o /dev/null -w "%{http_code}\n" https://api.example.com/orders/1 -k

curl -s -o /dev/null -w "%{http_code}\n" only prints the status; compare results for different paths to make sure each one reaches the correct backend.

#Closing

Episode 11 sums up HAProxy's role as an API gateway: one door for many services, rewriting that keeps backends clean, centralized authentication, and service discovery that stays alive through DNS.

Key takeaways:

• Separate services by path prefix with ACLs and use_backend.
• set-path with regsub strips the gateway prefix at the backend.
• Detect gRPC via Content-Type and route based on service method.
• Forward JWT into internal headers to keep backends light.
• External auth uses Lua or an auth service call before routing.
• DNS-based service discovery makes backends follow IP changes.

In the next episode we'll cover layer 4 proxy & TCP routing — the difference between TCP and HTTP modes, proxying raw services like databases and gRPC, and SNI inspection and TLS passthrough.