Skip to content

upstream-dynamic: Dynamic DNS resolution for NGINX upstreams

Installation

You can install this module in any RHEL-based distribution, including, but not limited to:

  • RedHat Enterprise Linux 7, 8, 9 and 10
  • CentOS 7, 8, 9
  • AlmaLinux 8, 9
  • Rocky Linux 8, 9
  • Amazon Linux 2 and Amazon Linux 2023
dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-upstream-dynamic

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-upstream-dynamic

Enable the module by adding the following at the top of /etc/nginx/nginx.conf:

load_module modules/ngx_http_upstream_dynamic_servers_module.so;

This document describes nginx-module-upstream-dynamic v0.4.0 released on Mar 15 2016.

An nginx module to resolve domain names inside upstreams and keep them up to date.

By default, servers defined in nginx upstreams are only resolved when nginx starts. This module provides an additional resolve parameter for server definitions that can be used to asynchronously resolve upstream domain names. This keeps the upstream definition up to date according to the DNS TTL of each domain names. This can be useful if you want to use upstreams for dynamic types of domain names that may frequently change IP addresses.

This module also allows nginx to start if an upstream contains a defunct domain name that no longer resolves. By default, nginx will fail to start if an upstream server contains an unresolvable domain name. With this module, nginx is still allowed to start with invalid domain names, but an error will be logged and the unresolvable domain names will be marked as down.

Usage

Use the server definition inside your upstreams and specify the resolve parameter.

Note: A resolver must be defined at the http level of nginx's config for resolve to work.

http {
  resolver 8.8.8.8;

  upstream example {
    server example.com resolve;
  }
}

Directives

server

Syntax: server address [parameters]; Context upstream

Defines a server for an upstream. The module adds the ability to specify a resolve parameter. When specified:

  • Domain names will be resolved on an ongoing basis and kept up to date according to the TTL of each domain name.
  • Unresolvable domain names are considered non-fatal errors (but logged). nginx is allowed to startup if a domain name can't be resolved, but the server is marked as down.

The following parameters can be used (see nginx's server documentation for details):

weight=number max_fails=number fail_timeout=time backup down resolve

GitHub

You may find additional configuration tips and documentation for this module in the GitHub repository for nginx-module-upstream-dynamic.