Модуль ngx_http_upstream_module

Разделы

Пример конфигурации
Директивы
     upstream
     server
     zone
     ip_hash
     keepalive
     least_conn
     queue
Встроенные переменные

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

Директивы

синтаксис: upstream название { ... }
умолчание:
контекст: http

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

    server backup1.example.com  backup;
}

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

синтаксис: server адрес [параметры];
умолчание:
контекст: upstream

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

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

weight=число
задаёт вес сервера, по умолчанию 1.
max_fails=число
задаёт число неудачных попыток работы с сервером, которые должны произойти в промежуток времени, заданный параметром fail_timeout, чтобы сервер считался неработающим на период времени, также заданный параметром fail_timeout. По умолчанию число попыток устанавливается равным 1. Нулевое значение отключает учёт попыток. Что считается неудачной попыткой, определяется директивами proxy_next_upstream, fastcgi_next_upstream, uwsgi_next_upstream, scgi_next_upstream и memcached_next_upstream.
fail_timeout=время
задаёт
  • время, в течение которого должно произойти заданное число неудачных попыток работы с сервером для того, чтобы сервер считался неработающим;
  • и время, в течение которого сервер будет считаться неработающим.
По умолчанию параметр равен 10 секундам.
backup
помечает сервер как запасной сервер. На него будут передаваться запросы в случае, если не работают основные серверы.
down
помечает сервер как постоянно неработающий; используется совместно с директивой ip_hash.

Кроме того, следующие параметры доступны как часть коммерческой подписки:

max_conns=число
ограничивает максимальное число одновременных соединений к проксируемому серверу (1.5.9). Значение по умолчанию равно 0 и означает, что ограничения нет.
resolve
отслеживает изменения IP-адресов, соответствующих доменному имени сервера, и автоматически изменяет конфигурацию группы без необходимости перезапуска nginx (1.5.12).

Для работы этого параметра директива resolver должна быть задана в блоке http. Пример:

http {
    resolver 10.0.0.1;

    upstream u {
        zone ...;
        ...
        server example.com resolve;
    }
}

синтаксис: zone имя размер;
умолчание:
контекст: upstream

Задаёт имя и размер зоны разделяемой памяти, в которой хранятся конфигурация группы и рабочее состояние, разделяемые между рабочими процессами. В таких группах возможно изменение состава группы или настроек отдельных серверов без необходимости перезапуска nginx. Конфигурация доступна через специальный location, для которого указана директива upstream_conf.

синтаксис: ip_hash;
умолчание:
контекст: upstream

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

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

Пример:

upstream backend {
    ip_hash;

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

синтаксис: keepalive соединения;
умолчание:
контекст: upstream

Эта директива появилась в версии 1.1.4.

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

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

Пример конфигурации группы серверов 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 "";
        ...
    }
}

Для работы постоянных соединений с 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;
        ...
    }
}

синтаксис: least_conn;
умолчание:
контекст: upstream

Эта директива появилась в версиях 1.3.1 и 1.2.2.

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

синтаксис: queue число [timeout=время];
умолчание:
контекст: upstream

Эта директива появилась в версии 1.5.12.

Если при обработке запроса невозможно сразу выбрать сервер группы и в группе есть серверы, у которых число соединений достигло ограничения max_conns, запрос будет помещён в очередь. Директива задаёт максимальное число запросов, которые могут одновременно находиться в очереди. Если очередь переполнена или за время, задаваемое параметром timeout, так и не удастся выбрать сервер для передачи ему запроса, клиенту будет возвращена ошибка.

По умолчанию параметр timeout равен 60 секундам.

Встроенные переменные

Модуль 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”, “REVALIDATED” или “HIT”.
кука с указанным именем, переданная сервером группы в поле “Set-Cookie” заголовка ответа (1.7.1). Необходимо иметь в виду, что запоминаются поля заголовка только из ответа последнего сервера.
$upstream_response_length
хранит длины ответов, полученных от серверов группы (0.7.27); длины хранятся в байтах. Длины нескольких ответов разделяются запятыми и двоеточиями подобно адресам в переменной $upstream_addr.
$upstream_response_time
хранит времена ответов, полученных от серверов группы; времена хранятся в секундах с точностью до миллисекунд. Времена нескольких ответов разделяются запятыми и двоеточиями подобно адресам в переменной $upstream_addr.
$upstream_status
хранит коды ответов, полученных от серверов группы. Коды нескольких ответов разделяются запятыми и двоеточиями подобно адресам в переменной $upstream_addr.
$upstream_http_имя
хранят поля заголовка ответа сервера. Например, поле заголовка ответа “Server” доступно в переменной $upstream_http_server. Правила преобразования имён полей заголовка ответа в имена переменных такие же, как для переменных с префиксом “$http_”. Необходимо иметь в виду, что запоминаются поля заголовка только из ответа последнего сервера.

    Поддержать сайт на родительском проекте КГБ