Module ngx_stream_zone_sync_module

配置示例
指令
     zone_sync
     zone_sync_buffers
     zone_sync_connect_retry_interval
     zone_sync_connect_timeout
     zone_sync_interval
     zone_sync_recv_buffer_size
     zone_sync_server
     zone_sync_ssl
     zone_sync_ssl_certificate
     zone_sync_ssl_certificate_key
     zone_sync_ssl_ciphers
     zone_sync_ssl_conf_command
     zone_sync_ssl_crl
     zone_sync_ssl_name
     zone_sync_ssl_password_file
     zone_sync_ssl_protocols
     zone_sync_ssl_server_name
     zone_sync_ssl_trusted_certificate
     zone_sync_ssl_verify
     zone_sync_ssl_verify_depth
     zone_sync_timeout
API 端点
启动、停止和移除集群节点

ngx_stream_zone_sync_module 模块 (1.13.8) 提供了在集群节点之间同步 共享内存区域 内容所需的支持。要启用特定区域的同步,对应的模块必须支持此功能。目前,可以同步 HTTP sticky 会话、有关 过多 HTTP 请求 的信息以及 httpstream 中的键值对。

此模块作为我们的 商业订阅 的一部分提供。

配置示例

最小配置

http {
    ...

    upstream backend {
       server backend1.example.com:8080;
       server backend2.example.com:8081;

       sticky learn
              create=$upstream_cookie_examplecookie
              lookup=$cookie_examplecookie
              zone=client_sessions:1m sync;
    }

    ...
}

stream {
    ...


    server {
        zone_sync;

        listen 127.0.0.1:12345;

        # cluster of 2 nodes
        zone_sync_server a.example.com:12345;
        zone_sync_server b.example.com:12345;

    }

启用 SSL 并通过 DNS 定义集群成员的更复杂配置

...

stream {
    ...

    resolver 127.0.0.1 valid=10s;

    server {
        zone_sync;

        # the name resolves to multiple addresses that correspond to cluster nodes
        zone_sync_server cluster.example.com:12345 resolve;

        listen 127.0.0.1:4433 ssl;

        ssl_certificate     localhost.crt;
        ssl_certificate_key localhost.key;

        zone_sync_ssl on;

        zone_sync_ssl_certificate     localhost.crt;
        zone_sync_ssl_certificate_key localhost.key;
    }
}

指令

语法 zone_sync;
默认值
上下文 server

启用集群节点之间的共享内存区域同步。集群节点使用 zone_sync_server 指令定义。

语法 zone_sync_buffers 数量 大小;
默认值
zone_sync_buffers 8 4k|8k;
上下文 stream, server

设置用于推送区域内容的每个区域缓冲区的 数量大小。默认情况下,缓冲区大小等于一个内存页。根据平台不同,这可能是 4K 或 8K。

单个缓冲区必须足够大,以容纳正在同步的每个区域的任何条目。

语法 zone_sync_connect_retry_interval 时间;
默认值
zone_sync_connect_retry_interval 1s;
上下文 stream, server

定义连接另一个集群节点的尝试间隔。

语法 zone_sync_connect_timeout 时间;
默认值
zone_sync_connect_timeout 5s;
上下文 stream, server

定义与另一个集群节点建立连接的超时时间。

语法 zone_sync_interval 时间;
默认值
zone_sync_interval 1s;
上下文 stream, server

定义轮询共享内存区域更新的间隔。

语法 zone_sync_recv_buffer_size 大小;
默认值
zone_sync_recv_buffer_size 4k|8k;
上下文 stream, server

设置用于解析传入同步消息流的每个连接接收缓冲区的 大小。缓冲区大小必须等于或大于 zone_sync_buffers 之一。默认情况下,缓冲区大小等于 zone_sync_buffers大小 乘以 数量

语法 zone_sync_server 地址 [resolve];
默认值
上下文 server

定义集群节点的 地址。地址可以指定为带有强制端口的域名或 IP 地址,或指定为在“unix:”前缀后的 UNIX 域套接字路径。解析为多个 IP 地址的域名可一次定义多个节点。

resolve 参数指示 nginx 监控对应节点域名的 IP 地址变化,并自动修改配置,无需重新启动 nginx。

集群节点可以动态指定为带有 resolve 参数的单个 zone_sync_server 指令,或静态指定为一系列没有该参数的指令。

每个集群节点应仅指定一次。

所有集群节点应使用相同的配置。

为了使 resolve 参数工作,必须在 stream 块中指定 resolver 指令。示例

stream {
    resolver 10.0.0.1;

    server {
        zone_sync;
        zone_sync_server cluster.example.com:12345 resolve;
        ...
    }
}

语法 zone_sync_ssl on | off;
默认值
zone_sync_ssl off;
上下文 stream, server

启用连接到另一个集群服务器的 SSL/TLS 协议。

语法 zone_sync_ssl_certificate 文件;
默认值
上下文 stream, server

指定一个 文件,其中包含 PEM 格式的证书,用于对另一个集群服务器进行身份验证。

语法 zone_sync_ssl_certificate_key 文件;
默认值
上下文 stream, server

指定一个 文件,其中包含 PEM 格式的密钥,用于对另一个集群服务器进行身份验证。

语法 zone_sync_ssl_ciphers 密码套件;
默认值
zone_sync_ssl_ciphers DEFAULT;
上下文 stream, server

指定连接到另一个集群服务器时启用的密码套件。密码套件使用 OpenSSL 库可理解的格式指定。

完整的列表可以使用“openssl ciphers”命令查看。

语法 zone_sync_ssl_conf_command 名称 ;
默认值
上下文 stream, server

此指令出现在 1.19.4 版本中。

与另一个集群服务器建立连接时,设置任意 OpenSSL 配置命令

使用 OpenSSL 1.0.2 或更高版本时支持此指令。

可以在同一级别指定多个 zone_sync_ssl_conf_command 指令。当且仅当当前级别未定义 zone_sync_ssl_conf_command 指令时,这些指令才会从先前的配置级别继承。

请注意,直接配置 OpenSSL 可能会导致意外行为。

语法 zone_sync_ssl_crl 文件;
默认值
上下文 stream, server

指定一个 文件,其中包含 PEM 格式的吊销证书列表 (CRL),用于验证另一个集群服务器的证书。

语法 zone_sync_ssl_name 名称;
默认值
zone_sync_ssl_name host from zone_sync_server;
上下文 stream, server

此指令出现在 1.15.7 版本中。

允许覆盖用于验证集群服务器证书以及在与集群服务器建立连接时通过 SNI 传递的服务器名称。

默认情况下,使用 zone_sync_server 地址的主机部分;如果指定了 resolve 参数,则使用解析后的 IP 地址。

语法 zone_sync_ssl_password_file 文件;
默认值
上下文 stream, server

指定一个 文件,其中包含用于密钥的密码短语,每个密码短语指定为单独的一行。加载密钥时会依次尝试这些密码短语。

语法 zone_sync_ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];
默认值
zone_sync_ssl_protocols TLSv1.2 TLSv1.3;
上下文 stream, server

启用与另一个集群服务器建立连接时指定的协议。

语法 zone_sync_ssl_server_name on | off;
默认值
zone_sync_ssl_server_name off;
上下文 stream, server

此指令出现在 1.15.7 版本中。

与另一个集群服务器建立连接时,启用或禁用通过TLS 服务器名称指示扩展 (SNI, RFC 6066) 传递服务器名称。

语法 zone_sync_ssl_trusted_certificate 文件;
默认值
上下文 stream, server

指定一个 文件,其中包含 PEM 格式的受信任 CA 证书,用于验证另一个集群服务器的证书。

语法 zone_sync_ssl_verify on | off;
默认值
zone_sync_ssl_verify off;
上下文 stream, server

启用或禁用对另一个集群服务器证书的验证。

语法 zone_sync_ssl_verify_depth 数量;
默认值
zone_sync_ssl_verify_depth 1;
上下文 stream, server

设置另一个集群服务器证书链中的验证深度。

语法 zone_sync_timeout 超时时间;
默认值
zone_sync_timeout 5s;
上下文 stream, server

设置与另一个集群节点连接时,两次连续读写操作之间的 超时时间。如果在此时间内没有数据传输,则连接将被关闭。

API 端点

节点的同步状态可通过 API 的 /stream/zone_sync/ 端点获取,该端点返回以下指标。

启动、停止和移除集群节点

要启动一个新节点,请更新集群主机名的 DNS 记录,将其指向新节点的 IP 地址,然后启动实例。新节点将从 DNS 或静态配置中发现其他节点,并开始向它们发送更新。其他节点最终将使用 DNS 发现新节点,并开始向其推送更新。在静态配置的情况下,其他节点需要重新加载才能向新节点发送更新。

要停止一个节点,请向实例发送 QUIT 信号。节点将完成区域同步并优雅地关闭打开的连接。

要移除一个节点,请更新集群主机名的 DNS 记录并移除该节点的 IP 地址。所有其他节点最终将发现该节点已移除,关闭与该节点的连接,并且不再尝试连接到它。节点移除后,可以按照上述方法停止。在静态配置的情况下,其他节点需要重新加载才能停止向已移除的节点发送更新。