Модуль ngx_http_upstream_module позволяет описывать группы серверов, которые могут использоваться в директивах proxy_pass и fastcgi_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;
    }
}

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

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

Пример:

upstream backend {
    ip_hash;

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

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

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

Следует отметить, что директива 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 не определяют семантику постоянных соединений.

Задаёт имя и другие параметры сервера. В качестве имени можно использовать доменное имя, адрес, порт или путь UNIX-сокета. Если доменному имени соответствует несколько адресов, то все они используются.

weight=число

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

max_fails=число

задаёт число неудачных попыток работы с сервером в течение времени, заданного параметром fail_timeout, после которого он считается неработающим, также в течение времени заданного параметром fail_timeout. По умолчанию число попыток устанавливается равным 1. Нулевое значение запрещает учёт попыток. Что считается неудачной попыткой, задаётся директивами proxy_next_upstream и fastcgi_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;
}

Описывает группу серверов. Серверы могут слушать на разных портах. Кроме того, можно одновременно использовать серверы, слушающие на 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 и по одному запросу на второй и третий серверы. Если при попытке работы с сервером произошла ошибка, то запрос будет передан следующему серверу, и так до тех пор, пока не будут опробованы все работающие серверы. Если не удастся получить успешный ответ ни от одного из серверов, то клиенту будет возвращён результат работы с последним сервером.

Модуль 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_response_time

хранит времена ответов серверов в секундах с точностью до миллисекунд. Несколько ответов также разделяются запятыми и двоеточиями.

$upstream_status

хранит коды ответов серверов. Несколько ответов также разделяются запятыми и двоеточиями.

$upstream_http_...

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