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

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

Установка

Вы можете установить этот модуль в любой дистрибутив на базе RHEL, включая, но не ограничиваясь:

  • RedHat Enterprise Linux 7, 8, 9 и 10
  • CentOS 7, 8, 9
  • AlmaLinux 8, 9
  • Rocky Linux 8, 9
  • Amazon Linux 2 и Amazon Linux 2023
dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-upsync

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-upsync

Включите модуль, добавив следующее в верхнюю часть файла /etc/nginx/nginx.conf:

load_module modules/ngx_http_upsync_module.so;

Этот документ описывает nginx-module-upsync v2.1.3, выпущенный 20 ноября 2020 года.

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

Описание

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

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

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

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

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

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

    Даже если одно извлечение не удалось, оно будет повторяться на следующем upsync_interval, гарантируя, что бэкенд-сервер стабильно предоставляет услуги. И поддерживает выгрузку последней конфигурации в указанное место, так что даже если consul/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]
по умолчанию: нет, если параметры опущены, параметры по умолчанию: upsync_interval=5s upsync_timeout=6m strong_dependency=off

контекст: upstream

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

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

  • upsync_interval

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

  • upsync_timeout

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

  • upsync_type

    тип сервера для извлечения из конфигурации.

  • strong_dependency

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

upsync_dump_path

syntax: upsync_dump_path $path

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

контекст: 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

по умолчанию: нет

контекст: 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;
        }

    }
}

Стиль кода

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

см. также

зависимости исходного кода

GitHub

Вы можете найти дополнительные советы по конфигурации и документацию для этого модуля в репозитории GitHub для nginx-module-upsync.