haproxyconf-2022/README.en.md

haproxyconf-2022

The purpose of this presentation is to show how we can use HAProxy and Varnish together to make web-sites and web-apps more performant and reliable.

We will start with the general ideas then go deeper to the details.

Why HAProxy and Varnish ?

They are both open-source, mature and performance-oriented. They are not alon inb their categories, but they are the ones we know and love the most. They are eaisly available on many platforms. They have great documentation and vast/vibrant communities. They both are supported by companies that offer professional support and services, while keeping the core open-source and free for everybody.

HAProxy

HAProxy will be the first web-server for the HTTP client. It will be the TLS/SSL termination. It will decide if the request is accepted or rejected,and finaly will pass the request to the upstream server or servers. It is acting as a proxy, with load-balancing and fault-tolerance capabilities.

To summarize briefly the basic principles of HAProxy, let's mention the frontend, the backend and the intermediate processing.

A frontend is an entry point. HAProxy is listening on the TCP or HTTP layer, on one or more IP:PORT pairs, with options regarding logs, timeouts, supported, protocols and much more. Many frontend can coexist in an HAProxy instance,to accomodate different use cases. For example : a traditionnal web-site in one, and an API for third-parties in another one, each with their settings and configuration.

HAProxy is able to parse and process the full TCP or HTTP request. It exposes an internal API to change the request or the response, decide how to deliver them upstream or not… in a very optimized and reliable manner.

A backend is an exit point. There must be one for each group of final webservers. If there is only one server in a backend, it will deal with every request, but if there are more than one, HAProxy will balance the requests, according to an algorithm. That's where we begin to mention load-balancing. And when we introduce som logic to deal with misbeahaving or missing servers, it becomes fault-tolerant.

Varnish

Varnish is going to store in cache the result of some requests. Later on, a client who makes the same request might get a result from the cache if it is preset andfresh enough.

With its default configuration, Varnish has a lot of good practice already in place and jst a few adjustments might be necessary to work with most of the situations. Every step of the request/response processing is done by functions that can be customized by something that looks a bit like inheritance in programming. At startup, everything is validated and compiled into optimized code.

Like HAProxy, Varnish parses the whole request/response inside the functions, so we can decide if the request/response needs to be modified (like adding or removeing headers), if a response can be served from the cache, if it need to talk to the final server, and if the responsae can be stored in cache for future use.

Varnish stores the content, its objects, into memory to be really fast. if you have a lot of trafic, give it enough RAM to keep a lot of content available.

Comment combiner HAProxy et Varnish

So we have decided to have them work together, in a coordinated way, for an efficient and feature-rich setup.

Has we've seen earlier, HAProxy uses frontends as entry-points and backend asexit-points.

In our case, after accepting the request from the HTTP client, HAProxy will pass it to Varnish, via a dedicated backend. We have chosen to place HAProxy and Varnish on the server server, and connect them with unix sockets, but it's an implementation detail andwe could have placed them on separate servers, communicating through regular TCP sockets.

Once the request is passed to Varnish, it will parse it too and decide if it is able to serve a resposne from the cache or pass it to the final server.

In the most common case with Varnish, the request to the final server and passed directly. It is evencapable of some rather basic load-balancing. But since we have HAProxy at hands and it is more capable in this area, we have decided to pass the request back to HAProxy.

To prevent loops, and to bypass the processing that has already been done, the request will reenter HAProxy throughanother frontend. This one is much simpler and its responsibility is basically to choose which backend to use for each request. If we manage sites and apps on more than one set of servers, we have to create as much backends as we have sets of servers.

In the end, the request is passed to a server in a backend, be it a static web site, a dynamic application programmed with a framework, or the ingress of a big Kubernetes cluster.

La réponse fera ensuite le chemin inverse, en revenant à HAProxy, puis Varnish (qui décidera s'il met la réponse en cache), puis HAProxy puis le client HTTP qui a fait initialement la requête.

The response will eventually travl the same way backwards, through HAProxy, Varnish (which will decide to store it in the cache or not) and HAProxy again to the original HTTP client.

Chain :

1. HAProxy frontend « external » (general)
2. HAProxy backend « varnish »
3. Varnish
4. HAProxy frontend « internal » (general)
5. HAProxy backend « site X » (per site)
6. Web-server

Multi-sites

Even if we have only one frontend to manage all the requests with the same settings, we can have many groups of web-servers,for differents web-apps of web-sites. In our case, we have many clients on one HAProxy, with one frontend, but many backends, one for each client and their own servers.

HAProxy does not have a concept of VirtualHost as Apache or Nginx do, but we can use some lower-levels conditionals to have a similar result. We can write (at least) an ACL t detect if the Host header is for a web site or another and then use this ACL to trigger some processing adnd chose the backend to use.

An ACL is like a boolean variable.

frontend external
    acl example_com_domains hdr(host) -i example.com
    acl foo_bar_domains     hdr(host) -i foo-bar.com foo-bar.org
    […]
    use_backend example_com if example_com_domains
    use_backend foo_bar     if foo_bar_domains

Pass the request to Varnish

In the HAProxy configurtion, we've put a "varnish" backend, with only one server.

backend varnish
    option httpchk HEAD /varnishcheck
    server varnish_sock /run/varnish.sock check observe layer7 maxconn 3000 inter 1s send-proxy-v2

The httpchk option tells HAProxy to use the "layer 7" to check for Varnish health, by regularly checking on a special URL.

In the Varnish configuration we have a behaviour for this URL:

sub vcl_recv {
    # HAProxy check
    if (req.url == "/varnishcheck") {
        return(synth(200, "Hi HAProxy, I'm fine!"));
    }
    […]
}

The response is extremely fast, which allow for frequent checks by HAProxy.

In the frontend section of HAProxy, there is an ACL that tells if Varnish is knownto be available. It is then possible to decide if we can pass the requets to VArnish or bypass it:

frontend external
    # Is the request routable to Varnish ?
    acl varnish_available   nbsrv(varnish) gt 0

    # Use Varnish if available
    use_backend varnish if varnish_available

    # … or use normal backend
    use_backend default_backend

backend varnish
    option httpchk HEAD /varnishcheck
    server varnish_sock /run/varnish.sock check observe layer7 maxconn 3000 inter 1s send-proxy-v2

backend default_backend
    server example-hostname 1.2.3.4:443 check observe layer4 ssl

Nothing forces us to use VArnish for every request and all web-sites of apps.

We ca either use an ACL :

frontend external
    acl example_com_domains hdr(host) -i example.com
    […]
    use_backend varnish if example_com_domains

We can use a more dynamic condition, with a file containing all the domains whose trafic should go through Varnish:

frontend external
    acl use_cache if hdr(host) -f /etc/haproxy/cached_domains
    […]
    use_backend varnish if use_cache

In some cases, we could decide to bypass Varnish when caching makes no sense. For example, if the HTTP method is neither GET, HEAD or PURGE:

frontend external
    acl varnish_http_verb method GET HEAD PURGE
    […]
    use_backend varnish if varnish_http_verb

And we can combine several of these conditions together:

• should the domaine be cached?
• is the request eligible for cache?
• is Varnish available?

PROXY protocol

What for?

Using the PROXY Protocol is not a necessity at all, but it adds a certain amount of comfort when we have proxies involved, like HAProxy and Varnish.

At the TCP level, when HAProxy talks to Varnish, then Varnish to HAproxy and finally HAroxy to the final web server, they are all seen as regular HTTP clients. Without any modification, each element reports the IP of the previous elements as the client IP, and the final server thinks that HAProxy is the only client accessing it. It's bad for IP based filtering, logging…

At the HTTP level, we've had the X-Forwarded-For header for a long time. I you look at its presence and you know how to parse it, you can use the ocrrect value in your web-server of application. It's cumbersome, and error-prone, and at the TCP level, this is invisible.

The PROXY protocol is simple extension of the TCP protocol. It add the same kinf of header, but at the TCP level. The downside is that both parties must support the PROXY protocol andbe configured to use it. The upside is that its completely transparent after that. There is nothing to do at the application level.

The PROXY protol has been designed by Willy Tarreau, creator of HAProxy, in 2010. It has sincebeen adopted by many products like Varnish, Apache, Nginx, Postfix, Docecot…

Comment?

In HAProxy we find in the backend to Varnish, in the frontend used by Varnish to pass the request to HAProxy, and possibly ibn the backend to the final web-servers.

backend varnish
    server varnish_sock /run/varnish.sock check observe layer7 maxconn 3000 inter 1s send-proxy-v2

frontend internal
    bind /run/haproxy-frontend-default.sock user root mode 666 accept-proxy

backend example_com
    server example-hostname 1.2.3.4:443 check observe layer4 ssl verify none send-proxy-v2

With HAProxy, for the listening side we use the accept-proxy option in the frontend section and for the emitting side we use the send-proxy-v2 option in the backendsection.

With Varnish, for the listening side we use the PROXY option in the startp command line :

/usr/sbin/varnishd […] -a /run/varnish.sock,PROXY […]

And for the emitting side, we use the proxy_header = 1 setting in the backend section. :

backend default {
    .path = "/run/haproxy-frontend-default.sock";
    .proxy_header = 1;
    […]
}

How to debug with PROXY protocol

Even though it's a valuable optimization, the PROXY protocol is not supported by many tools, especially some very low level ones, like a forged HTTP request on a telnet connection.

This is especially if you want to bypass HAProxy and debug at the varnish level directly.

The startup command accepts many listening addresses, each one with its options. We can add one restricted on localhost and a custom firewalled port, and have a debug back-door :

/usr/sbin/varnishd […] -a 127.0.0.1:82 […]

It become really easy to make a direct request:

curl --verbose \
     --resolve www.example.com:82:127.0.0.1 \
     --header "X-Forwarded-Proto: https" \
     http://www.example.com:82/foo/bar

And yes, curl supports the PROXY protocol since version 7.37.0 and with the --proxy-header. But it's an example and it's good to know that you can do that manually if you want or need.

What about the final servers?

Si on contrôle les serveurs web finaux et qu'il ssont compatibles, on peut aussi faire la liaison finale avec le PROXY protocol. On sera alors aussi tenté d'ajouter au serveur web un port d'écoute sans PROXY protocol, et bien protégé.

Note: si vous utilisez Apache, je vous recommande d'étudier le module "ForensicLog" qui permet facilement un debug détaillé de tous les en-têtes échangés. C'est très pratique pour débug des chaînes de proxy et voir si tout arrive bien au serveur web final. Je ne sais pas s'il existe quelque chose de similaire pour Nginx.

HTTP tagging

Toujours dans une optique de traçabilité et de facilité de debug, nous nous servons de HAProxy et Varnish pour ajouter dans les en-têtes HTTP des informations sur leur fonctionnement.

Rappelons que la norme HTTP définit des en-têtes normalisés, dont la syntaxe et l'utilisation sont bien codifiés : Host, Set-Cookie, Cache-Control… Mais nous pouvons ajouter n'importe quel en-tête no standard avec un prefix X-. Certains sont quasi standards, d'autres sont totalement personnalisés.

X-Forwarded-*

Bien que nous utilisions le PROXY protocol en interne (et éventuellement vers certains serveurs finaux), nous conservons généralement l'en-tête HTTP X-Forwarded-For.

Nous ajoutons aussi X-Forwarded-Port pour indiquer à quel port de HAProxy le client s'est adressé. Et enfin nous ajoutons X-Forwarded-Proto pour indiquer si la connexion initiale était chiffrée ou pas.

frontend external
    bind 0.0.0.0:80,:::80
    bind 0.0.0.0:443,:::443 ssl […]

    option forwardfor

    http-request set-header X-Forwarded-Port  %[dst_port]

    http-request set-header X-Forwarded-Proto http  if !{ ssl_fc }
    http-request set-header X-Forwarded-Proto https if  { ssl_fc }

Ce dernier en-tête est souvent imortant lorsque la requête finale est utilisée par des framework qui impose un accès en https te ne peuvent pas s'appuyer sur le fait que la requête leur arrive au final en https.

X-Unique-ID

Il est très utile de marquer une requête entrante d'un identifiant unique qui pourra être transmis d'étape en étape jusqu'au serveur final (et pourquoi pas au retour aussi).

frontend external
    […]
    http-request set-header X-Unique-ID %[uuid()] unless { hdr(X-Unique-ID) -m found }

Il n'y a pas de réel consensus sur le nommage de l'en-tête. On trouve souvent X-Unique-ID ou X-Request-ID.

X-Boost-*

Boost est le nom que nous avons donné à notre système basé sur HAProxy et Varnish. Nous ajoutons donc plusieurs en-têtes X-Boost-* pour ajouter des informations utiles.

Sur le frontend « external » nous marquons la requête comme étant passée en étape 1 par « haproxy-external ». Les autres étapes de la requête sauront alors que la requête est entrée par là.

Lorsque réponse resortira de ce backend pour aller au client, on la marque aussi pour indiquer que l'étape 1 était « haproxy-external » en précisant si la connexion était en http ou https. On indique aussi le nom du serveur Boost qui a traité la requête.

frontend external
    […]
    http-request add-header X-Boost-Step1 haproxy-external

    http-response add-header X-Boost-Step1 "haproxy-external; client-https" if  { ssl_fc }
    http-response add-header X-Boost-Step1 "haproxy-external; client-http"  if !{ ssl_fc }
    http-response set-header X-Boost-Server my-hostname

Au niveau du frontend « internal » on applique le même principe, mais en indiquant que c'est pour l'étape 3.

frontend internal
    […]
    http-request add-header X-Boost-Step3 haproxy-internal

    http-response add-header X-Boost-Step3 "haproxy-internal; SSL to backend" if  { ssl_bc }
    http-response add-header X-Boost-Step3 "haproxy-internal; no SSL to backend" if !{ ssl_bc }

Dans le backend final du site, on marque la réponse pour indiquer si la connexion avec le serveur final s'est faite en http ou https.

backend example_com
    […]
    http-response set-header X-Boost-Proto https if  { ssl_bc }
    http-response set-header X-Boost-Proto http  if !{ ssl_bc }
    server example-hostname 1.2.3.4:443 check observe layer4 ssl verify none

Au niveau de Varnish, nous marquons la requête transmise pour indiquer qu'elle est passée par Varnish :

sub vcl_recv {
    […]
    set req.http.X-Boost-Layer = "varnish";
}

Lorsque la réponse est renvoyée, elle est marquée sur l'étape 2 de détails à propos des modalités de cache

sub vcl_deliver {
    […]
    if (resp.http.Set-Cookie && resp.http.Cache-Control) {
      set resp.http.X-Boost-Step2 = "varnish WITH set-cookie AND cache-control on backend server";
    } elseif (resp.http.Set-Cookie) {
      set resp.http.X-Boost-Step2 = "varnish WITH set-cookie and NO cache-control on backend server";
    } elseif (resp.http.Cache-Control) {
      set resp.http.X-Boost-Step2 = "varnish with NO set-cookie and WITH cache-control on backend server";
    } else {
      set resp.http.X-Boost-Step2 = "varnish with NO set-cookie and NO cache-control on backend server";
    }

Par ailleurs, Varnish ajoute par défaut de nombreux en-têtes sur l'utilisation ou non du cache, l'âge de la ressource…

Note: La syntaxe de ces en-têtes X-Boost-* est encore expérimentale. Nous prévoyons de les rendre plus compacts et faciles à traiter automatiquement.

Log HAProxy complet

Dans des situations avancées de debug, nous pouvons aussi activer l'ajout dans un en-tête HTTP de la totalité de la ligne de log :

frontend external
    http-response add-header X-Haproxy-Log-external "%ci:%cp [%tr] %ft %b/%s %TR/%Tw/%Tc/%Tr/%Ta %ST %B %CC %CS %tsc %ac/%fc/%bc/%sc/%rc %sq/%bq %hr %hs %{+Q}r"

frontend internal
    http-response add-header X-Haproxy-Log-Internal "%ci:%cp [%tr] %ft %b/%s %TR/%Tw/%Tc/%Tr/%Ta %ST %B %CC %CS %tsc %ac/%fc/%bc/%sc/%rc %sq/%bq %hr %hs %{+Q}r"

⚠️ Il vaut mieux ne pas activer cela en production, mais ça peut être très utile pour permettre à un client en mode test/préprod de vérifier comment se comporte le proxy.

Haute disponibilité

Côté applicatif

Lorsque le site ou l'application web finale dispose de plusieurs serveurs pour gérer les requêtes, on peut prendre en charge directement dans HAProxy la répartition de charge. Lorsque c'est possible, on fait de préférence un round-robin sur les serveurs web. Lorsque l'application gère mal les sessions ou des aspects bloquants, on met un serveur en actif et les autres en backup, pour basculer sur un secours si le primaire n'est plus disponible.

Côté HAProxy

Pour éviter que HAProxy + Varnish ne soient un « Single Point Of Failure », nous avons mis en place 2 serveurs différents dans 2 réseaux différents et nous faisons un round-robin DNS en amont. Cette approche n'est pas la plus avancée, car en cas de panne d'un serveur il faut intervenir au niveau DNS. Cependant elle a le mérite de la simplicité et les pannes complète de machines virtuelles tournant sur de la virtualisation redondante sont heureusement très rares. En revanche, ce système nous permet pas mal de souplesse.

Il serait aussi possible de faire du « actif-passif » en mettant une IP flottante (keepalived/vrrp) en amont de deux serveurs, pour avoir une bascule automatique sur le secondaire en cas de panne du primaire. On aller encor eplus loin et faire du « actif-actif » avec 2 HAProxy en « layer 4 » qui renvoient ensuite sur 2 HAproxy en « layer 7 » Ces approches permettent une reprise d'activité quasi immédiate en cas de panne, mais elles impliquent plus de ressources et une topologie réseau particulière.

Fonctionnalités complémentaires

Filtrage TCP

Dans le frontend « external » qui gère le trafic entrant, nous pouvons vérifier si le client doit être immédiatement rejeté, par exemple selon son adresse IP :

frontend external
    […]
    # Reject the request at the TCP level if source is in the denylist
    tcp-request connection reject if { src -f /etc/haproxy/deny_ips }

Cela ne remplace pas un vrai firewall, mais ça permet de facilement exclure des client au niveau TCP (couche 4).

Filtrage HTTP

En analysant la requête au niveau HTTP (couche 7), on peut filtrer de manière beaucoup plus fine.

Par exemple, si un site est passé en mode maintenance (détaillé plus loin), on peut contourner ce mode maintenance pour une liste d'IP particulière qui pourra tout de même consulter le site et vérifier par exemple l'état des opérationsde maintenance.

frontend external
    […]
    # List of IP that will not go the maintenance backend
    acl maintenance_ips src -f /etc/haproxy/maintenance_ips
    # Go to maintenance backend, unless your IP is whitelisted
    use_backend maintenance if !maintenance_ips

backend maintenance
    http-request set-log-level silent
    # Custom 503 error page
    errorfile 503 /etc/haproxy/errors/maintenance.http
    # With no server defined, a 503 is returned for every request

Pour les outils locaux de monitoring (exemple: Munin) ou pour les challenges ACME, il peut être utile de renvoyer sur un serveur web local (exemple: Apache ou Nginx), au lieu de renvoyer sur Varnish ou les serveurs web appliatifs.

frontend external
    […]
    # Is the request coming for the server itself (stats…)
    acl server_hostname hdr(host) -i my-hostname
    acl munin           hdr(host) -i munin

    # Detect Let's Encrypt challenge requests
    acl letsencrypt path_dir -i /.well-known/acme-challenge

    use_backend local       if server_hostname
    use_backend local       if munin

    use_backend letsencrypt if letsencrypt

backend letsencrypt
    # Use this if the challenge is managed locally
    server localhost 127.0.0.1:81 send-proxy-v2 maxconn 10
    # Use this if the challenge is managed remotely
    ### server my-certbot-challenge-manager 192.168.2.1:80 maxconn 10

backend local
    option httpchk HEAD /haproxy-check
    server localhost 127.0.0.1:81 send-proxy-v2 maxconn 10

Mode maintenance

Le mode maintenance est une sorte de coupe-circuit qui permet de basculer toute l'installation, ou juste un site web en mode maintenance.

Pour la coupure globale, on utilise un backend spécial qui ne définit pas de serveur web final et provoquera toujours une erreur 503. On peut aussi définir une page d'erreur particulière pour cette situation. Nous avons fait le choix de ne pas logguer les requêtes lorsque ce mode et activé.

frontend external
    […]
    # List of IP that will not go the maintenance backend
    acl maintenance_ips src -f /etc/haproxy/maintenance_ips
    # Go to maintenance backend, unless your IP is whitelisted
    use_backend maintenance if !maintenance_ips

backend maintenance
    http-request set-log-level silent
    # Custom 503 error page
    errorfile 503 /etc/haproxy/errors/maintenance.http
    # With no server defined, a 503 is returned for every request

Pour une coupure par site, il faut définir un backend spécial pour ce site et activer l'utilisation de ce backend pour les requêtes. On retrouve notre ACL par domaine.

frontend external
    […]
    acl example_com_domains hdr(host) -i example.com

    acl maintenance_ips src -f /etc/haproxy/maintenance_ips
    acl example_com_maintenance_ips src -f /etc/haproxy/example_com/maintenance_ips

    use_backend example_com_maintenance if example_com_domains !example_com_maintenance_ips !maintenance_ips

Personnalisation par site

On peut définir des ACL pour chaque site et ainsi provoquer des comportements lorsqu'une requête est destinée à ce site.

Par exemple, les redirections http vers https, ou pour des sous-domaines, les en-têtes HSTS

Configuration complète

Parcourons la configuration complète de HAProxy puis Varnish, pour commenter petit à petit tout ce qu'on a vu jusque là.