Module ngx_stream_zone_sync_module

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

Note

此模块可作为commercial subscription的一部分使用。

Example Configuration

Minimal configuration:

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

Directives

Syntax:zone_sync;
Default:
Context:server

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

Syntax:zone_sync_buffers number size;
Default:zone_sync_buffers 8 4k|8k;
Context:stream , server

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

Note

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

Syntax:zone_sync_connect_retry_interval time;
Default:zone_sync_connect_retry_interval 1s;
Context:stream , server

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

Syntax:zone_sync_connect_timeout time;
Default:zone_sync_connect_timeout 5s;
Context:stream , server

定义用于与另一个群集节点构建连接的超时。

Syntax:zone_sync_interval time;
Default:zone_sync_interval 1s;
Context:stream , server

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

Syntax:zone_sync_recv_buffer_size size;
Default:zone_sync_recv_buffer_size 4k|8k;
Context:stream , server

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

Syntax:zone_sync_server address [resolve];
Default:
Context:server

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

resolve参数指示 nginx 监视与该节点的域名对应的 IP 地址的更改,并自动修改配置,而无需重新启动 nginx。

群集节点既可以动态指定为带有resolve参数的单个zone_sync_server指令,也可以静态指定为一系列不带参数的多个指令的序列。

Note

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

Note

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

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

stream {
    resolver 10.0.0.1;

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

Syntax:zone_sync_ssl on | off;
Default:zone_sync_ssl off;
Context:stream , server

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

Syntax:zone_sync_ssl_certificate file;
Default:
Context:stream , server

使用用于对另一台群集服务器进行身份验证的 PEM 格式的证书指定一个file

Syntax:zone_sync_ssl_certificate_key file;
Default:
Context:stream , server

使用 PEM 格式的密钥指定一个file,用于对另一台群集服务器进行身份验证。

Syntax:zone_sync_ssl_ciphers ciphers;
Default:zone_sync_ssl_ciphers DEFAULT;
Context:stream , server

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

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

Syntax:zone_sync_ssl_crl file;
Default:
Context:stream , server

指定带有file的 PEM 格式的吊销证书(CRL),用于verify另一台群集服务器的证书。

Syntax:zone_sync_ssl_name name;
Default:zone_sync_ssl_name host from zone_sync_server;
Context:stream , server

该指令出现在 1.15.7 版中。

与群集服务器构建连接时,允许覆盖用于verify群集服务器的证书和通过 SNI的服务器名称。

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

Syntax:zone_sync_ssl_password_file file;
Default:
Context:stream , server

指定一个带有secret keys密码短语的file,其中每个密码短语都在单独的行上指定。加载密钥时依次尝试使用密码短语。

Syntax:zone_sync_ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];
Default:zone_sync_ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
Context:stream , server

启用指定的协议以连接到另一个群集服务器。

Syntax:zone_sync_ssl_server_name on | off;
Default:zone_sync_ssl_server_name off;
Context:stream , server

该指令出现在 1.15.7 版中。

与其他群集服务器构建连接时,启用或禁用通过TLS 服务器名称指示扩展(SNI,RFC 6066)进行服务器名传递。

Syntax:zone_sync_ssl_trusted_certificate file;
Default:
Context:stream , server

指定带有file的 PEM 格式的受信任 CA 证书,该证书用于verify其他群集服务器的证书。

Syntax:zone_sync_ssl_verify on | off;
Default:zone_sync_ssl_verify off;
Context:stream , server

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

Syntax:zone_sync_ssl_verify_depth number;
Default:zone_sync_ssl_verify_depth 1;
Context:stream , server

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

Syntax:zone_sync_timeout timeout;
Default:zone_sync_timeout 5s;
Context:stream , server

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

API endpoints

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

启动,停止,删除集群节点

要启动新节点,请使用新节点的 IP 地址更新群集主机名的 DNS 记录,然后启动实例。新节点将从 DNS 或静态配置中发现其他节点,并将开始向其发送更新。其他节点最终将使用 DNS 查找新节点,并开始向其推送更新。如果是静态配置,则需要重新加载其他节点才能将更新发送到新节点。

要停止节点,请向实例发送QUITsignal。该节点将完成区域同步并正常关闭打开的连接。

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