stream-upsync: NGINX 模块用于从 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

CentOS/RHEL 8+、Fedora Linux、Amazon Linux 2023+CentOS/RHEL 7 和 Amazon Linux 2

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-stream-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-stream-upsync

通过在 /etc/nginx/nginx.conf 的顶部添加以下内容来启用该模块：

load_module modules/ngx_stream_upsync_module.so;

本文档描述了 nginx-module-stream-upsync v1.2.2，于 2020 年 1 月 02 日发布。

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;
    }
}

注意：upstream: include 命令是必要的，第一次转储的文件应包含所有服务器。

描述

该模块提供了一种发现后端服务器的方法。支持通过 consul/etcd 动态添加或删除后端服务器，并动态调整后端服务器的权重，模块将及时从 consul/etcd 拉取新的后端服务器列表以同步到 nginx ip 路由器。Nginx 无需重新加载。相比其他方法具有一些优势：

及时

模块向 consul/etcd 发送带索引的键，consul/etcd 将其与索引进行比较，如果索引没有变化，连接将挂起五分钟，在此期间对键值的任何操作将立即反馈。
性能

从 consul/etcd 拉取相当于对 nginx 的一次请求，更新 ip 路由器时 nginx 无需重新加载，因此对 nginx 性能的影响很小。
稳定性

即使一次拉取失败，它也会在下一个 upsync_interval 进行拉取，从而保证后端服务器稳定提供服务。并支持将最新配置转储到位置，因此即使 consul/etcd 挂起，nginx 也可以随时重新加载。

指令

upsync

语法: 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

描述：从 consul/etcd 拉取上游服务器。

参数的含义为：

upsync_interval

从 consul/etcd 拉取服务器的间隔时间。
upsync_timeout

从 consul/etcd 拉取服务器的请求超时。
upsync_type

从配置服务器拉取服务器的类型。
strong_dependency

当 nginx 启动时，如果 strong_dependency 打开，则表示服务器将依赖于 consul/etcd，并将从 consul/etcd 拉取服务器。

upsync_dump_path

语法: upsync_dump_path $path

默认值：/tmp/servers_$host.conf

上下文：upstream

描述：将上游后端转储到 $path。

upsync_lb

语法: upsync_lb $load_balance

默认值：round_robin/ip_hash/hash modula

上下文：upstream

描述：主要用于 least_conn 和 hash consistent，当使用其中之一时，您必须指出使用 upsync_lb。

upsync_show

语法: upsync_show

默认值：无

上下文：server

描述：显示所有上游。

curl http://localhost:2345/upstream_show

显示所有上游

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

默认值：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

代码风格

代码风格主要基于 style

参见

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

GitHub

您可以在 nginx-module-stream-upsync 的 GitHub 仓库中找到此模块的其他配置提示和文档。