5.3. Server IP address resolution using DNS

  1. HAProxy allows using a host name on the server line to retrieve its IP address
  2. using name servers. By default, HAProxy resolves the name when parsing the
  3. configuration file, at startup and cache the result for the process' life.
  4. This is not sufficient in some cases, such as in Amazon where a server's IP
  5. can change after a reboot or an ELB Virtual IP can change based on current
  6. workload.
  7. This chapter describes how HAProxy can be configured to process server's name
  8. resolution at run time.
  9. Whether run time server name resolution has been enable or not, HAProxy will
  10. carry on doing the first resolution when parsing the configuration.

5.3.1. Global overview

  1. As we've seen in introduction, name resolution in HAProxy occurs at two
  2. different steps of the process life:
  3.  
  4.   1. when starting up, HAProxy parses the server line definition and matches a
  5.      host name. It uses libc functions to get the host name resolved. This
  6.      resolution relies on /etc/resolv.conf file.
  7.  
  8.   2. at run time, HAProxy performs periodically name resolutions for servers
  9.      requiring DNS resolutions.
  10.  
  11. A few other events can trigger a name resolution at run time:
  12.   - when a server's health check ends up in a connection timeout: this may be
  13.     because the server has a new IP address. So we need to trigger a name
  14.     resolution to know this new IP.
  15.  
  16. When using resolvers, the server name can either be a hostname, or a SRV label.
  17. HAProxy considers anything that starts with an underscore as a SRV label. If a
  18. SRV label is specified, then the corresponding SRV records will be retrieved
  19. from the DNS server, and the provided hostnames will be used. The SRV label
  20. will be checked periodically, and if any server are added or removed, haproxy
  21. will automatically do the same.
  22.  
  23. A few things important to notice:
  24.   - all the name servers are queried in the meantime. HAProxy will process the
  25.     first valid response.
  26.  
  27.   - a resolution is considered as invalid (NX, timeout, refused), when all the
  28.     servers return an error.

5.3.2. The resolvers section

  1. This section is dedicated to host information related to name resolution in
  2. HAProxy. There can be as many as resolvers section as needed. Each section can
  3. contain many name servers.
  4.  
  5. When multiple name servers are configured in a resolvers section, then HAProxy
  6. uses the first valid response. In case of invalid responses, only the last one
  7. is treated. Purpose is to give the chance to a slow server to deliver a valid
  8. answer after a fast faulty or outdated server.
  9.  
  10. When each server returns a different error type, then only the last error is
  11. used by HAProxy. The following processing is applied on this error:
  12.  
  13.   1. HAProxy retries the same DNS query with a new query type. The A queries are
  14.      switch to AAAA or the opposite. SRV queries are not concerned here. Timeout
  15.      errors are also excluded.
  16.  
  17.   2. When the fallback on the query type was done (or not applicable), HAProxy
  18.      retries the original DNS query, with the preferred query type.
  19.  
  20.   3. HAProxy retries previous steps <resolve_retires> times. If no valid
  21.      response is received after that, it stops the DNS resolution and reports
  22.      the error.
  23.  
  24. For example, with 2 name servers configured in a resolvers section, the
  25. following scenarios are possible:
  26.  
  27.   - First response is valid and is applied directly, second response is
  28.     ignored
  29.  
  30.   - First response is invalid and second one is valid, then second response is
  31.     applied
  32.  
  33.   - First response is a NX domain and second one a truncated response, then
  34.     HAProxy retries the query with a new type
  35.  
  36.   - First response is a NX domain and second one is a timeout, then HAProxy
  37.     retries the query with a new type
  38.  
  39.   - Query timed out for both name servers, then HAProxy retries it with the
  40.     same query type
  41.  
  42. As a DNS server may not answer all the IPs in one DNS request, haproxy keeps
  43. a cache of previous answers, an answer will be considered obsolete after
  44. <hold obsolete> seconds without the IP returned.

resolvers 

  1.   Creates a new name server list labeled <resolvers id>
  2.  
  3. A resolvers section accept the following parameters:

accepted_payload_size 

  1. Defines the maximum payload size accepted by HAProxy and announced to all the
  2. name servers configured in this resolvers section.
  3. <nb> is in bytes. If not set, HAProxy announces 512. (minimal value defined
  4.      by RFC 6891)
  5.  
  6. Note: the maximum allowed value is 8192.

nameserver :

  1. DNS server description:
  2.   <id>   : label of the server, should be unique
  3.   <ip>   : IP address of the server
  4.   <port> : port where the DNS service actually runs

parse-resolv-conf

  1. Adds all nameservers found in /etc/resolv.conf to this resolvers nameservers
  2. list. Ordered as if each nameserver in /etc/resolv.conf was individually
  3. placed in the resolvers section in place of this directive.

hold 

  1. Defines <period> during which the last name resolution should be kept based
  2. on last resolution <status>
  3.   <status> : last name resolution status. Acceptable values are "nx",
  4.              "other", "refused", "timeout", "valid", "obsolete".
  5.   <period> : interval between two successive name resolution when the last
  6.              answer was in <status>. It follows the HAProxy time format.
  7.              <period> is in milliseconds by default.
  8.  
  9. Default value is 10s for "valid", 0s for "obsolete" and 30s for others.

resolve_retries 

  1. Defines the number <nb> of queries to send to resolve a server name before
  2. giving up.
  3. Default value: 3
  4.  
  5. A retry occurs on name server timeout or when the full sequence of DNS query
  6. type failover is over and we need to start up from the default ANY query
  7. type.

timeout 

  1. Defines timeouts related to name resolution
  2.    <event> : the event on which the <time> timeout period applies to.
  3.              events available are:
  4.              - resolve : default time to trigger name resolutions when no
  5.                          other time applied.
  6.                          Default value: 1s
  7.              - retry   : time between two DNS queries, when no valid response
  8.                          have been received.
  9.                          Default value: 1s
  10.    <time>  : time related to the event. It follows the HAProxy time format.
  11.              <time> is expressed in milliseconds.

Example:

  1. resolvers mydns
  2.   nameserver dns1 10.0.0.1:53
  3.   nameserver dns2 10.0.0.2:53
  4.   parse-resolv-conf
  5.   resolve_retries       3
  6.   timeout resolve       1s
  7.   timeout retry         1s
  8.   hold other           30s
  9.   hold refused         30s
  10.   hold nx              30s
  11.   hold timeout         30s
  12.   hold valid           10s
  13.   hold obsolete        30s