Перейти к содержанию

stream-upsync: NGINX модуль для синхронизации потоковых бэкендов из Consul или Etcd

Установка на Debian/Ubuntu

Эти документы применимы к пакету APT nginx-module-stream-upsync, предоставляемому репозиторием GetPageSpeed Extras.

  1. Настройте репозиторий APT, как описано в настройке репозитория APT.
  2. Установите модуль:
sudo apt-get update
sudo apt-get install nginx-module-stream-upsync
Показать дистрибутивы и архитектуры 
| Дистрибутив | Версия             | Компонент   | Архитектуры   |
|-------------|--------------------|-------------|----------------|
| debian      | bookworm           | main        | amd64, arm64   |
| debian      | bookworm-mainline  | main        | amd64, arm64   |
| debian      | trixie             | main        | amd64, arm64   |
| debian      | trixie-mainline    | main        | amd64, arm64   |
| ubuntu      | focal              | main        | amd64, arm64   |
| ubuntu      | focal-mainline     | main        | amd64, arm64   |
| ubuntu      | jammy              | main        | amd64, arm64   |
| ubuntu      | jammy-mainline     | main        | amd64, arm64   |
| ubuntu      | noble              | main        | amd64, arm64   |
| ubuntu      | noble-mainline     | main        | amd64, arm64   |

nginx-stream-upsync-module - C модуль Nginx, синхронизирует upstream из consul или других, динамически изменяет атрибуты бэкенд-серверов (вес, max_fails,...), не требуя перезагрузки nginx.

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

Модуль может более плавно расширяться и сжиматься и не повлияет на производительность.

Другой модуль, nginx-upsync-module, поддерживает HTTP модуль nginx (протокол HTTP), обратите внимание.

Если вы хотите использовать как nginx-upsync-module, так и nginx-stream-upsync-module, пожалуйста, обратитесь к nginx-upsync.

Статус

Этот модуль все еще активно разрабатывается и считается готовым к производству.

Синопсис

nginx-consul: 

stream {
    upstream test {
        upsync 127.0.0.1:8500/v1/kv/upstreams/test/ upsync_timeout=6m upsync_interval=500ms upsync_type=consul strong_dependency=off;
        upsync_dump_path /usr/local/nginx/conf/servers/servers_test.conf;

        include /usr/local/nginx/conf/servers/servers_test.conf;
    }

    upstream bar {
        server 127.0.0.1:8090 weight=1 fail_timeout=10 max_fails=3;
    }

    server {
        listen 12345;

        proxy_connect_timeout 1s;
        proxy_timeout 3s;
        proxy_pass test;
    }

    server {
        listen 2345;

        upstream_show
    }

    server {
        listen 127.0.0.1:9091;

        proxy_responses 1;
        proxy_timeout 20s;
        proxy_pass bar;
    }
}
nginx-etcd: 
stream {
    upstream test {
        upsync 127.0.0.1:2379/v2/keys/upstreams/test upsync_timeout=6m upsync_interval=500ms upsync_type=etcd strong_dependency=off;
        upsync_dump_path /usr/local/nginx/conf/servers/servers_test.conf;

        include /usr/local/nginx/conf/servers/servers_test.conf;
    }

    upstream bar {
        server 127.0.0.1:8090 weight=1 fail_timeout=10 max_fails=3;
    }

    server {
        listen 12345;

        proxy_connect_timeout 1s;
        proxy_timeout 3s;
        proxy_pass test;
    }

    server {
        listen 2345;

        upstream_show
    }

    server {
        listen 127.0.0.1:9091;

        proxy_responses 1;
        proxy_timeout 20s;
        proxy_pass bar;
    }
}
upsync_lb: 
stream {
    upstream test {
        least_conn; //hash $uri consistent;

        upsync 127.0.0.1:8500/v1/kv/upstreams/test/ upsync_timeout=6m upsync_interval=500ms upsync_type=consul strong_dependency=off;
        upsync_dump_path /usr/local/nginx/conf/servers/servers_test.conf;
        upsync_lb least_conn; //hash_ketama;

        include /usr/local/nginx/conf/servers/servers_test.conf;
    }

    upstream bar {
        server 127.0.0.1:8090 weight=1 fail_timeout=10 max_fails=3;
    }

    server {
        listen 12345;

        proxy_connect_timeout 1s;
        proxy_timeout 3s;
        proxy_pass test;
    }

    server {
        listen 2345;

        upstream_show
    }

    server {
        listen 127.0.0.1:9091;

        proxy_responses 1;
        proxy_timeout 20s;
        proxy_pass bar;
    }
}

ПРИМЕЧАНИЕ: команда include для upstream обязательна, при первом создании файл дампа должен включать все серверы.

Описание

Этот модуль предоставляет метод для обнаружения бэкенд-серверов. Поддерживает динамическое добавление или удаление бэкенд-серверов через consul/etcd и динамическую регулировку веса бэкенд-серверов. Модуль будет своевременно подтягивать новый список бэкенд-серверов из consul/etcd для синхронизации с маршрутизатором IP NGINX. Nginx не требует перезагрузки. Имеет некоторые преимущества по сравнению с другими:

  • Своевременность

    Модуль отправляет ключ в consul/etcd с индексом, consul/etcd сравнивает его с собственным индексом. Если индекс не изменился, соединение будет висеть пять минут, в этот период любое действие над ключом-значением будет немедленно отражаться.

  • Производительность

    Запрос из consul/etcd равен запросу к nginx, обновление IP-маршрутизатора nginx не требует перезагрузки, поэтому влияние на производительность nginx минимально.

  • Стабильность

    Даже если одно извлечение не удалось, он попытка следующего через upsync_interval, гарантируя, что бэкенд-сервер стабильно предоставляет услуги. Также поддерживает дамп последней конфигурации в местоположение, так что даже если consul/etcd зависнет, nginx можно будет перезагрузить в любое время.

Директивы

upsync

syntax: upsync $consul/etcd.api.com:$port/v1/kv/upstreams/$upstream_name/ [upsync_type=consul/etcd] [upsync_interval=sec/min] [upsync_timeout=sec/min] [strong_dependency=off/on]
default: none, если параметры опущены, параметры по умолчанию: upsync_interval=5s upsync_timeout=6m strong_dependency=off

context: upstream

description: Запрос upstream серверов из consul/etcd... .

Значения параметров:

  • upsync_interval

    Интервал времени для получения серверов из consul/etcd.

  • upsync_timeout

    Тайм-аут запроса серверов из consul/etcd.

  • upsync_type

    Тип сервера, из которого получаем серверы.

  • strong_dependency

    Когда Nginx запускается, если strong_dependency включен, это означает, что серверы будут зависеть от consul/etcd и будут получать серверы из consul/etcd.

upsync_dump_path

syntax: upsync_dump_path $path

default: /tmp/servers_$host.conf

context: upstream

description: Дамп бэкенд-апстримов в $path.

upsync_lb

syntax: upsync_lb $load_balance

default: round_robin/ip_hash/hash modula

context: upstream

description: В основном для least_conn и hash consistent, при использовании одного из них обязательно укажите использование upsync_lb.

upsync_show

syntax: upsync_show

default: none

context: server

description: Показать все upstreams.

curl http://localhost:2345/upstream_show

показать все upstreams

Consul_interface

Данные могут быть получены из хранилища ключей/значений или каталога услуг. В первом случае параметр upsync_type директивы должен быть consul. Например

    upsync 127.0.0.1:8500/v1/kv/upstreams/test upsync_timeout=6m upsync_interval=500ms upsync_type=consul strong_dependency=off;

Во втором случае он должен быть consul_services.

    upsync 127.0.0.1:8500/v1/catalog/service/test upsync_timeout=6m upsync_interval=500ms upsync_type=consul_services strong_dependency=off;

Вы можете добавить или удалить бэкенд-сервер через consul_ui или http_interface. Ниже приведены примеры для хранилища ключей/значений.

Пример http_interface:

  • добавить 
        curl -X PUT http://$consul_ip:$port/v1/kv/upstreams/$upstream_name/$backend_ip:$backend_port
    по умолчанию: вес=1 max_fails=2 fail_timeout=10 down=0 backup=0;

    curl -X PUT -d "{\"weight\":1, \"max_fails\":2, \"fail_timeout\":10}" http://$consul_ip:$port/v1/kv/$dir1/$upstream_name/$backend_ip:$backend_port
или
    curl -X PUT -d '{"weight":1, "max_fails":2, "fail_timeout":10}' http://$consul_ip:$port/v1/kv/$dir1/$upstream_name/$backend_ip:$backend_port
значение поддерживает формат json.

  • удалить 

        curl -X DELETE http://$consul_ip:$port/v1/kv/upstreams/$upstream_name/$backend_ip:$backend_port

  • изменять вес 

        curl -X PUT -d "{\"weight\":2, \"max_fails\":2, \"fail_timeout\":10}" http://$consul_ip:$port/v1/kv/$dir1/$upstream_name/$backend_ip:$backend_port
или
    curl -X PUT -d '{"weight":2, "max_fails":2, "fail_timeout":10}' http://$consul_ip:$port/v1/kv/$dir1/$upstream_name/$backend_ip:$backend_port

  • пометить сервер как неработающий 

        curl -X PUT -d "{\"weight\":2, \"max_fails\":2, \"fail_timeout\":10, \"down\":1}" http://$consul_ip:$port/v1/kv/$dir1/$upstream_name/$backend_ip:$backend_port
или
    curl -X PUT -d '{"weight":2, "max_fails":2, "fail_timeout":10, "down":1}' http://$consul_ip:$port/v1/kv/$dir1/$upstream_name/$backend_ip:$backend_port

  • проверка 

        curl http://$consul_ip:$port/v1/kv/upstreams/$upstream_name?recurse

Etcd_interface

Вы можете добавить или удалить бэкенд-сервер через http_interface.

В основном как etcd, пример http_interface:

  • добавить 
        curl -X PUT http://$etcd_ip:$port/v2/keys/upstreams/$upstream_name/$backend_ip:$backend_port
    по умолчанию: вес=1 max_fails=2 fail_timeout=10 down=0 backup=0;

    curl -X PUT -d value="{\"weight\":1, \"max_fails\":2, \"fail_timeout\":10}" http://$etcd_ip:$port/v2/keys/$dir1/$upstream_name/$backend_ip:$backend_port
значение поддерживает формат json.

  • удалить 

        curl -X DELETE http://$etcd_ip:$port/v2/keys/upstreams/$upstream_name/$backend_ip:$backend_port

  • изменять вес 

        curl -X PUT -d "{\"weight\":2, \"max_fails\":2, \"fail_timeout\":10}" http://$etcd_ip:$port/v2/keys/$dir1/$upstream_name/$backend_ip:$backend_port

  • пометить сервер как неработающий 

        curl -X PUT -d value="{\"weight\":2, \"max_fails\":2, \"fail_timeout\":10, \"down\":1}" http://$etcd_ip:$port/v2/keys/$dir1/$upstream_name/$backend_ip:$backend_port

  • проверка 

        curl http://$etcd_ip:$port/v2/keys/upstreams/$upstream_name

Стиль кода

Стиль кода в основном основан на style

см. также

  • модуль проверки nginx_upstream_check: https://github.com/alibaba/tengine/blob/master/src/http/ngx_http_upstream_check_module.c
  • патч модуля проверки nginx_upstream_check: https://github.com/yaoweibin/nginx_upstream_check_module
  • или на основе https://github.com/xiaokai-wang/nginx_upstream_check_module

зависимости источников

  • Cjson: https://github.com/kbranigan/cJSON
  • http-parser: https://github.com/nodejs/http-parser