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

upsync: Модуль NGINX для синхронизации upstream'ов из консул или etcd

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

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

  1. Настройте APT репозиторий, как описано в настройке APT репозитория.
  2. Установите модуль:
sudo apt-get update
sudo apt-get install nginx-module-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 C, который может синхронизировать upstream'ы из Consul или других источников. Он динамически изменяет характеристики бэкенд-серверов (вес, max_fails и т. д.), без необходимости перезагрузки NGINX.

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

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

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

Статус

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

Основные сведения

nginx-consul: 

http {
    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 8080;

        location = /proxy_test {
            proxy_pass http://test;
        }

        location = /bar {
            proxy_pass http://bar;
        }

        location = /upstream_show {
            upstream_show;
        }

    }
}
nginx-etcd: 
http {
    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 8080;

        location = /proxy_test {
            proxy_pass http://test;
        }

        location = /bar {
            proxy_pass http://bar;
        }

        location = /upstream_show {
            upstream_show;
        }

    }
}
upsync_lb: 
http {
    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 8080;

        location = /proxy_test {
            proxy_pass http://test;
        }

        location = /bar {
            proxy_pass http://bar;
        }

        location = /upstream_show {
            upstream_show;
        }

    }
}

ПРИМЕЧАНИЕ: рекомендуется отключить strong_dependency, и при первом включении файл включает все сервера.

Описание

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

  • своевременно

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

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

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

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

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

  • health_check

    nginx-upsync-module поддерживает добавление или удаление серверных проверок, требуется nginx_upstream_check_module. Рекомендуется использовать nginx-upsync-module + nginx_upstream_check_module.

Директивы

upsync

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

контекст: upstream

описание: Извлечение upstream серверов из консул/etcd... .

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

  • upsync_interval

    интервал времени извлечения серверов из консул/etcd.

  • upsync_timeout

    тайм-аут запроса извлечения серверов из консул/etcd.

  • upsync_type

    тип сервера, извлекаемого из конфигурации.

  • strong_dependency

    когда strong_dependency включен, nginx будет извлекать серверы из консул/etcd каждый раз при запуске или перезагрузке nginx.

upsync_dump_path

syntax: upsync_dump_path $path

по умолчанию: /tmp/servers_$host.conf

контекст: upstream

описание: сброс бэкендов upstream в $path.

upsync_lb

syntax: upsync_lb $load_balance

по умолчанию: round_robin/ip_hash/hash modula

контекст: upstream

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

upstream_show

syntax: upstream_show

по умолчанию: none

контекст: upstream

описание: Отобразить все бэкенд-серверы конкретного upstream.

     location /upstream_list {
         upstream_show;
     }

curl http://127.0.0.1:8500/upstream_list?test;

curl http://127.0.0.1:8500/upstream_list;

показать все upstream'ы.

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_health:

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

Службы с неудачными проверками состояния помечаются как отключенные с использованием health api.

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

пример http_interface:

  • добавить 
        curl -X PUT http://$consul_ip:$port/v1/kv/upstreams/$upstream_name/$backend_ip:$backend_port
    по умолчанию: weight=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
    по умолчанию: weight=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

Check_module

Поддержка модуля проверки.

check-conf: 

http {
    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;

        check interval=1000 rise=2 fall=2 timeout=3000 type=http default_down=false;
        check_http_send "HEAD / HTTP/1.0\r\n\r\n";
        check_http_expect_alive http_2xx http_3xx;

    }

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

    server {
        listen 8080;

        location = /proxy_test {
            proxy_pass http://test;
        }

        location = /bar {
            proxy_pass http://bar;
        }

        location = /upstream_show {
            upstream_show;
        }

        location = /upstream_status {
            check_status;
            access_log off;
        }

    }
}

Стиль кода

Стиль кода в значительной степени основывается на стиле

Смотрите также

  • модуль nginx_upstream_check_module: https://github.com/alibaba/tengine/blob/master/src/http/ngx_http_upstream_check_module.c
  • патч модуля nginx_upstream_check_module: 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