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-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，于 2020 年 11 月 20 日发布。

Nginx C 模块，可以从 Consul 或其他地方同步上游。它动态修改后端服务器属性（权重、最大失败次数等），无需重新加载 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 拉取新的后端服务器列表以同步 nginx ip 路由。Nginx 无需重新加载。相比其他方法具有一些优势：

及时

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

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

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

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

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

参数的含义：

upsync_interval

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

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

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

当 strong_dependency 打开时，nginx 每次启动或重新加载时都会从 consul/etcd 拉取服务器。

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 模式

上下文：upstream

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

upstream_show

syntax: upstream_show

默认值：无

上下文：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;

显示所有上游。

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;

健康检查失败的服务会在健康 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

另请参阅

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-upsync 的 GitHub 仓库中找到有关此模块的其他配置提示和文档。