K8s部署Hazelcast5.0集群Python智能客户端连接超时问题

核心原因 #

Hazelcast智能客户端默认工作逻辑为：先从用户配置的cluster_members地址拉取集群所有成员的内部网络地址（即K8s环境下Pod的集群内IP、内部端口），后续客户端会尝试直接连接这些内部地址实现就近路由。若客户端部署在K8s集群外部，无法访问K8s内部网络，就会触发连接超时。 #

解决方案 #

方案1：配置成员对外暴露地址（生产环境推荐）

在K8s部署Hazelcast集群时，为每个成员配置对外可访问的地址，让智能客户端拉取到的成员地址为外部可达地址，无需访问内部Pod网络：

1. 修改Hazelcast部署的StatefulSet/DaemonSet配置，为每个副本添加环境变量指定对外地址：

env:
# 该参数值对应当前副本的NodePort访问地址，格式为<K8s节点公网IP>:<NodePort端口>
- name: HZ_NETWORK_PUBLICADDRESS
  value: "192.168.1.10:30001"

多副本场景可以配合下行环境变量、Init容器为每个副本动态绑定对应的节点IP和NodePort端口。

2. 重启Hazelcast集群生效后，客户端即可正常使用智能路由模式连接。

方案2：禁用智能路由（快速验证用）

如果仅用于临时测试排查，可以直接在Python客户端关闭智能路由功能，强制所有请求走已配置的cluster_members地址：

client = HazelcastClient(
    cluster_name="dev",
    ssl_password="password",
    cluster_members=[
        "IPADDRESS1_MASTER_K8s:Nodeport1",
        "IPADDRESS2_MASTER_K8s:Nodeport2",
        "IPADDRESS3_MASTER_K8s:Nodeport3"
    ],
    # 新增配置禁用智能路由
    smart_routing=False
)

该方案会丢失智能客户端的性能优化特性，不建议生产环境使用。

其他排查项 #

• 检查客户端代码的cluster_members列表的元素之间是否添加了逗号分隔，示例代码中三个地址字符串未加逗号，Python会将其拼接为单个字符串，导致集群成员地址配置错误
• 检查K8s节点的安全组、防火墙规则是否放通了客户端IP对NodePort端口的访问权限
• 确认Hazelcast服务端SSL配置与客户端匹配，若服务端未开启SSL，可先删除ssl_password参数测试连接
• 查看Hazelcast服务端运行日志，排查是否有客户端连接被拒绝的错误记录

内容的提问来源于stack exchange，提问作者DungLe