HAProxy Enterprise Documentation 2.0r1

Frontend

When HAProxy Enterprise is used as a reverse proxy in front of your backend servers, a frontend section defines the IP addresses and ports that clients can connect to.

You may add as many frontend sections as needed to expose various websites or applications to the Internet. Each frontend keyword is followed by a label, such as www.example.com, to differentiate it from others.

frontend www.example.com
   # Your configuration directives

The label is mostly for readability, but it does come into play when referencing stick tables and categorizing traffic metrics. It should consist of only upper or lowercase letters, digits, dashes, underscores, dots, and colons.

Frontend configuration examples

The following configuration sample defines a frontend with the label myfrontend and uses the mode, bind, and default_backend directives to set the proxy mode, define IP addresses and ports that client can connect to, and send that traffic to a specific backend.

frontend myfrontend

   # Set the proxy mode to http (layer 7) or tcp (layer 4)
   mode http

   # Receive HTTP traffic on all IP addresses assigned to the server at port 80
   bind *:80

   # Choose the default pool of backend servers
   default_backend web_servers

backend web_servers
   mode http
   server s1 192.168.1.25:80
   server s2 192.168.1.26:80
   server s3 192.168.1.27:80

Listening on multiple IP addresses and ports

A frontend may listen on multiple addresses and/or ports. In the following configuration sample, myfrontend listens on both ports 80 and 443 and the http-request redirect directive redirects all clients from HTTP to HTTPS.

frontend myfrontend
   mode http
   bind *:80
   bind *:443 ssl crt /etc/hapee-2.0/certs/ssl.pem

   # Redirect HTTP to HTTPS
   http-request redirect scheme https unless { ssl_fc }

   default_backend web_servers

The http-request redirect directive will only redirect if the request is not HTTPS. To check for that it uses a conditional unless statement that checks the value or the ssl_fc boolean fetch.

Fetches can extract data from traffic streams, client or server information, tables, environmental information, etc. A more detailed look into available HAProxy Enterprise fetches is available at a later topic.

Using multiple frontends for different traffic types

In the next configuration sample, frontend foo.com is configured to receive HTTP traffic. It specifies a mode of http in order to enable Layer 7 processing of HTTP messages.

Frontend db.foo.com is configured to receive non-HTTP traffic, in this case MySQL traffic at port 3306, and cannot make use of Layer 7 inspection and routing. Therefore, mode is set to tcp, which enables a simpler Layer 4 proxying.

frontend foo.com
   mode http
   bind 192.168.1.5:80
   default_backend foo_servers

frontend db.foo.com
   mode tcp
   bind 192.168.1.15:3306
   default_backend db_servers

It is important to remember that a frontend section's mode should match the mode of the backend section it sends traffic to. A mismatch will cause the configuration to not work.

Using conditionals to forward traffic to different backends

A frontend section can be setup to send traffic to other backends with the use_backend directive. The syntax is use_backend followed by a backend label and an if or unless statement.

frontend example.com
  use_backend <backend> [{if | unless} <condition>]

In the next configuration sample, frontent foo_and_bar listens for HTTP traffic on two IP addresses and uses use_backend to send traffic to backend foo_servers.

frontend foo_and_bar
   mode http
   bind 192.168.1.5:80
   bind 192.168.1.6:80
   use_backend foo_servers if { req.hdr(host) -i foo.com }
   default_backend bar_servers

The if statement checks if the string returned by the req.hdr(host) fetch matches the string foo.com. The -i flag used ignores case during string matching.

All other traffic is configured by the default_backend directive to go to backend bar_servers.

Data Plane API

Install the Data Plane API.

You can manage frontends remotely by calling the Data Plane API endpoint /services/haproxy/configuration/frontends.

Get a list of frontends with the GET method:

$ curl -X GET \
    --user admin:adminpwd \
    "http://127.0.0.1:5555/v2/services/haproxy/configuration/frontends"

# output
{
   "_version":1,
   "data":[{
      "default_backend":"webservers",
      "name":"fe_main"
   }]
}

Add a frontend by using the POST method (note that bind lines are added separately using the /services/haproxy/configuration/binds endpoint):

$ curl -X POST
    --user admin:adminpwd \
    -H "Content-Type: application/json" \
    -d '{
          "name": "myfrontend",
          "mode": "http",
          "default_backend": "webservers",
          "maxconn": 2000
        }' \
    "http://127.0.0.1:5555/v2/services/haproxy/configuration/frontends?version=1"

Get information about a specific frontend by adding its name to the GET call:

$ curl -X GET \
    --user admin:adminpwd \
    "http://127.0.0.1:5555/v2/services/haproxy/configuration/frontends/myfrontend"

# output
{
   "_version":2,
   "data":{
      "default_backend":"webservers",
      "maxconn":2000,
      "mode":"http",
      "name":"myfrontend"
   }
}

Replace an existing frontend by calling PUT:

$ curl -X PUT
    --user admin:adminpwd \
    -H "Content-Type: application/json" \
    -d '{
          "name": "myfrontend",
          "mode": "tcp",
          "default_backend":
          "webservers",
          "maxconn": 1000
        }' \
    "http://127.0.0.1:5555/v2/services/haproxy/configuration/frontends/myfrontend?version=2"

Delete a frontend with the DELETE method:

$ curl -X DELETE \
    --user admin:adminpwd \
    "http://127.0.0.1:5555/v2/services/haproxy/configuration/frontends/myfrontend?version=3"

Next up

Backend