Модуль ngx_http_upstream_module позволяет описывать группы серверов, которые могут использоваться в директивах proxy_pass, fastcgi_pass и memcached_pass.

upstream backend {
    server backend1.example.com       weight=5;
    server backend2.example.com:8080;
    server unix:/tmp/backend3;

    server backup1.example.com:8080   backup;
    server backup2.example.com:8080   backup;
}

server {
    location / {
        proxy_pass http://backend;
    }
}

Описывает группу серверов. Серверы могут слушать на разных портах. Кроме того, можно одновременно использовать серверы, слушающие на TCP- и UNIX-сокетах.

Пример:

upstream backend {
    server backend1.example.com weight=5;
    server 127.0.0.1:8080       max_fails=3 fail_timeout=30s;
    server unix:/tmp/backend3;
}

По умолчанию запросы распределяются по серверам циклически (в режиме round-robin) с учётом весов серверов. В вышеприведённом примере каждые 7 запросов будут распределены так: 5 запросов на backend1.example.com и по одному запросу на второй и третий серверы. Если при попытке работы с сервером произошла ошибка, то запрос будет передан следующему серверу, и так до тех пор, пока не будут опробованы все работающие серверы. Если не удастся получить успешный ответ ни от одного из серверов, то клиенту будет возвращён результат работы с последним сервером.

Задаёт адрес и другие параметры сервера. Адрес может быть указан в виде доменного имени или IP-адреса, и необязательного порта, или в виде пути UNIX-сокета, который указывается после префикса “unix:”. Если порт не указан, используется порт 80. Доменное имя, которому соответствует несколько IP-адресов, задаёт сразу несколько серверов.

Могут быть заданы следующие параметры:

weight=число

задаёт вес сервера, по умолчанию 1.

max_fails=число

задаёт число неудачных попыток работы с сервером в течение времени, заданного параметром fail_timeout, после которого он считается неработающим, также в течение времени заданного параметром fail_timeout. По умолчанию число попыток устанавливается равным 1. Нулевое значение запрещает учёт попыток. Что считается неудачной попыткой, задаётся директивами proxy_next_upstream, fastcgi_next_upstream и memcached_next_upstream. Состояние http_404 не считается неудачной попыткой.

fail_timeout=время

задаёт

• время, в течение которого должно произойти заданное число неудачных попыток работы с сервером для того, чтобы сервер считался неработающим;
• и время, в течение которого сервер будет считаться неработающим.

По умолчанию таймаут равен 10 секундам.

backup

помечает сервер как запасной сервер. На него будут передаваться запросы в случае, если не работают основные серверы.

down

помечает сервер как постоянно неработающий; используется совместно с директивой ip_hash.

Пример:

upstream backend {
    server backend1.example.com     weight=5;
    server 127.0.0.1:8080           max_fails=3 fail_timeout=30s;
    server unix:/tmp/backend3;

    server backup1.example.com:8080 backup;
}

Задаёт для группы метод балансировки нагрузки, при котором запросы распределяются по серверам на основе IP-адресов клиентов. В качестве ключа для хэширования используются первые три октета IPv4-адреса клиента или IPv6-адрес клиента целиком. Метод гарантирует, что запросы одного и того же клиента будут всегда передаваться на один и тот же сервер. Если же этот сервер будет считаться неработающим, то запросы этого клиента будут передаваться на другой сервер. С большой долей вероятности это также будет один и тот же сервер.

IPv6-адреса поддерживаются начиная с версий 1.3.2 и 1.2.2.

Если один из серверов нужно убрать на некоторое время, то для сохранения текущего хэширования IP-адресов клиентов этот сервер нужно пометить параметром down.

Пример:

upstream backend {
    ip_hash;

    server backend1.example.com;
    server backend2.example.com;
    server backend3.example.com down;
    server backend4.example.com;
}

До версий 1.3.1 и 1.2.2 для серверов, использующих метод балансировки нагрузки ip_hash, нельзя было задать вес.

Задействует кэш соединений для группы серверов.

Параметр соединения устанавливает максимальное число неактивных постоянных соединений с серверами группы, которые будут сохраняться в кэше каждого рабочего процесса. При превышении этого числа наиболее давно не используемые соединения закрываются.

Следует особо отметить, что директива keepalive не ограничивает общее число соединений с серверами группы, которые рабочие процессы nginx могут открыть. Параметр соединения следует устанавливать достаточно консервативно для обеспечения возможности обработки серверами группы новых входящих соединений.

Пример конфигурации группы серверов memcached с постоянными соединениями:

upstream memcached_backend {
    server 127.0.0.1:11211;
    server 10.0.0.2:11211;

    keepalive 32;
}

server {
    ...

    location /memcached/ {
        set $memcached_key $uri;
        memcached_pass memcached_backend;
    }

}

Для HTTP директиву proxy_http_version следует установить в “1.1”, а поле заголовка “Connection” — очистить:

upstream http_backend {
    server 127.0.0.1:8080;

    keepalive 16;
}

server {
    ...

    location /http/ {
        proxy_pass http://http_backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        ...
    }
}

Хоть это и не рекомендуется, но также возможно использование постоянных соединений в HTTP/1.0, путём передачи поля заголовка “Connection: Keep-Alive” серверу группы.

Для работы постоянных соединений с FastCGI-серверами потребуется включить директиву fastcgi_keep_conn:

upstream fastcgi_backend {
    server 127.0.0.1:9000;

    keepalive 8;
}

server {
    ...

    location /fastcgi/ {
        fastcgi_pass fastcgi_backend;
        fastcgi_keep_conn on;
        ...
    }
}

При использовании методов балансировки нагрузки, отличных от стандартного round-robin, следует активировать их до директивы keepalive.

Протоколы SCGI и uwsgi не определяют семантику постоянных соединений.

Задаёт для группы метод балансировки нагрузки, при котором запрос передаётся серверу с наименьшим числом активных соединений, с учётом весов серверов. Если подходит сразу несколько серверов, они выбираются циклически (в режиме round-robin) с учётом их весов.

Модуль ngx_http_upstream_module поддерживает следующие встроенные переменные:

$upstream_addr

хранит IP-адрес и порт сервера или путь к UNIX-сокету. Если при обработке запроса были сделаны обращения к нескольким серверам, то их адреса разделяются запятой, например, “192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock”. Если произошло внутреннее перенаправление от одной группы серверов на другую с помощью “X-Accel-Redirect” или error_page, то эти группы серверов разделяются двоеточием, например, “192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock : 192.168.10.1:80, 192.168.10.2:80”.

$upstream_cache_status

хранит статус доступа к кэшу ответов (0.8.3). Статус может быть одним из “MISS”,  “BYPASS”, “EXPIRED”, “STALE”, “UPDATING” или “HIT”.

$upstream_response_length

хранит длины ответов, полученных от серверов группы (0.7.27); длины хранятся в байтах. Несколько ответов разделяются запятыми и двоеточиями, подобно переменной $upstream_addr.

$upstream_response_time

хранит времена ответов, полученных от серверов группы; времена хранятся в секундах с точностью до миллисекунд. Несколько ответов разделяются запятыми и двоеточиями, подобно переменной $upstream_addr.

$upstream_status

хранит коды ответов, полученных от серверов группы. Несколько ответов разделяются запятыми и двоеточиями, подобно переменной $upstream_addr.

$upstream_http_...

хранят поля заголовка ответа сервера. Например, поле заголовка ответа “Server” доступно в переменной $upstream_http_server. Правила преобразования имён полей заголовка ответа в имена переменных такие же, как для переменных с префиксом “$http_”. Необходимо иметь в виду, что запоминаются только поля заголовка ответа последнего сервера.