HAProxy Enterprise Documentation 1.6r1


A resolvers section lists DNS nameservers that HAProxy Enterprise will query when it needs to resolve a hostname to an IP address. Each resolvers keyword is followed by a label, such as mynameservers, to differentiate it from others.

resolvers mynameservers
   nameserver ns1
   nameserver ns2

Each nameserver line indicates the IP address and port of a DNS nameserver. HAProxy Enterprise sends a query to all of the nameservers and uses the first, valid response that it receives.

Resolvers configuration examples

The most common way to use this feature is to configure backend server hostnames instead of IP addresses. When defining a list of servers in a backend or listen section, you can use DNS names.

In the following configuration sample, the servers defined in backend webservers are using the resolvers field on each server line to reference the resolvers section that will be used to resolve the server's name.

resolvers mynameservers
   nameserver ns1
   nameserver ns2

backend webservers
   server s1 hostname1.example.com:80 check resolvers mynameservers
   server s2 hostname2.example.com:8080 check resolvers mynameservers
   server s3 hostname3.example.com:8080 check resolvers mynameservers

Configuring DNS resolution

Resolution happens when the load balancer starts or reloads. However, in some cases, the DNS records may not be available yet, such as in dynamic environments that leverage DNS-based service discovery for populating DNS records. This would result in HAProxy Enterprise failing to start since failure to resolve an address is fatal.

To control this behavior we have added the init-addr field on the server line followed by comma-separated resolution methods.

backend webservers
   server s1 hostname1.example.com:80 check resolvers mynameservers init-addr last,libc,none
  • By setting the first method to last, HAProxy Enterprise first tries to get the IP address from a state file (i.e. server-state-file).

  • Next, it tries to resolve the DNS name by using its internal "libc" resolver.

  • If that fails, it moves on to the none method, which indicates that the load balancer can start without resolving the name with the expectation that the name will be resolved later at runtime.

A hardcoded IP address can also be specified as a fallback.

backend webservers
   server s1 hostname1.example.com:80 check resolvers mynameservers init-addr last,libc,

Adjusting DNS settings

You can adjust how HAProxy Enterprise queries nameservers and caches the responses. The following sample configuration contains a resolvers section with all available options configured.

resolvers mynameservers
   nameserver ns1
   nameserver ns2

   # Maximum size of a DNS answer allowed, in bytes
   accepted_payload_size 512

   # Whether to add nameservers found in /etc/resolv.conf

   # How long to "hold" a backend server's up/down status depending on the name resolution status.
   # For example, if an NXDOMAIN response is returned, keep the backend server in its current state (up) for
   # at least another 30 seconds before marking it as down due to DNS not having a record for it.
   hold valid    10s
   hold other    30s
   hold refused  30s
   hold nx       30s
   hold timeout  30s
   hold obsolete 30s

   # How many times to retry a query
   resolve_retries 3

   # How long to wait between retries when no valid response has been received
   timeout retry 1s

   # How long to wait for a successful resolution
   timeout resolve 1s

See also

DNS Service Discovery

Next up