jdomain
The 'jdomain' directive enables asynchronous domain name resolution for upstream server configurations in NGINX.
Description
The 'jdomain' directive allows NGINX to use a domain name for upstream server definitions, enabling dynamic resolution of domain names. This capability makes the upstream configurations resilient to DNS updates, ensuring that incoming requests can be routed to the correct backend server based on the latest DNS resolution. When a request targets a jdomain upstream, it checks whether the specified interval has passed since the last DNS resolution; if it has, a new DNS lookup is performed. This avoids the need for periodic DNS checks and instead triggers resolution based on demand.
A unique feature of the jdomain directive is its flexibility in handling multiple upstreams and mixing other upstream directives. Users can define multiple 'jdomain' directives, 'server' directives, and load balancing rules within the same upstream block. However, caution is necessary when specifying load balancing algorithms, as any custom algorithms must precede the jdomain directive in the upstream block to prevent runtime crashes. Additionally, since the DNS resolution happens asynchronously, requests directed to a jdomain upstream may experience one-time failures if the upstream configuration changes unexpectedly during DNS lookups, highlighting the importance of managing upstream states carefully.
Config Example
resolver 8.8.8.8;
upstream backend {
jdomain example.com;
jdomain anotherdomain.com port=8080;
}Load balancing algorithms must be specified before the jdomain directive to avoid runtime crashes.
Asynchronous DNS resolution can result in one-off failures if upstream states change while a request is being processed.
Ensure the resolver is defined in the HTTP context before using jdomain.