Submariner 故障排除手册：常见网络连接问题的解决方案

Submariner 故障排除手册：常见网络连接问题的解决方案

【免费下载链接】submarinerNetworking component for interconnecting Pods and Services across Kubernetes clusters.项目地址: https://gitcode.com/gh_mirrors/su/submariner

Submariner 作为跨 Kubernetes 集群互连 Pod 和 Service 的关键网络组件，在实际部署中可能会遇到各种网络连接问题。本手册将帮助新手用户快速定位并解决 Submariner 常见的网络故障，确保跨集群通信顺畅。

1. 部署前环境检查要点 ✅

在部署 Submariner 前，确保环境满足以下要求，可有效避免大部分基础问题：

• 网络策略：检查防火墙规则，确保各集群间的 UDP 4500、UDP 500 端口开放，这些是 IPsec 隧道建立的关键端口。
• 节点可达性：验证集群节点间的网络连通性，可使用ping或telnet测试节点间基础网络是否通畅。
• Kubernetes 版本：确认所有集群使用的 Kubernetes 版本符合 Submariner 兼容要求，可参考项目根目录下的 README.md 文档。

2. 常见连接问题及解决方案 🔧

2.1 跨集群 Pod 无法通信

症状：不同集群的 Pod 之间无法 ping 通或建立连接。

排查步骤：

1. 检查 Submariner 组件状态：

   kubectl get pods -n submariner-operator

   确保submariner-gateway、submariner-route-agent等 Pod 均处于Running状态。

2. 查看 Gateway 日志寻找错误：

   kubectl logs -n submariner-operator <submariner-gateway-pod-name>

   常见错误如connection refused可能指示 IPsec 隧道建立失败。

3. 验证 Endpoint 状态：

   kubectl get endpoints.submariner.io -n submariner-operator

   确保所有集群的 Endpoint 状态正常，包含有效的公共 IP 和端口信息。

解决方案：

• 若发现 IPsec 隧道问题，检查 pkg/cable/libreswan/libreswan.go 中的配置，确保证书和密钥正确。
• 重启 Submariner Gateway 组件：

  kubectl rollout restart deployment submariner-gateway -n submariner-operator

2.2 服务发现失败

症状：通过 Service 名称跨集群访问服务时提示 "service not found"。

排查步骤：

1. 检查 Globalnet 状态（若启用）：

   kubectl get globalegressips.submariner.io -A

   确认全局 IP 分配正常。

2. 查看服务导出配置： 检查 deploy/crds/submariner.io_clusters.yaml 中的 CRD 定义，确保服务导出规则正确配置。

解决方案：

• 重新应用服务导出配置：

  kubectl apply -f deploy/crds/submariner.io_clusters.yaml

• 检查 pkg/globalnet/controllers/service_export_controller.go 中的控制器逻辑，确保服务导出逻辑正常。

2.3 隧道建立超时

症状：Gateway 日志中频繁出现 "tunnel establishment timeout" 错误。

排查步骤：

1. 检查节点网络配置： 确认节点的网络接口配置正确，特别是 pkg/netlink/network_interface.go 中定义的网络接口处理逻辑是否与实际环境匹配。

2. 验证 NAT 环境： Submariner 依赖 NAT 穿透功能，若集群部署在 NAT 环境下，需确保 pkg/natdiscovery/natdiscovery.go 中的 NAT 发现逻辑正常工作。

解决方案：

• 调整 IPsec 超时设置，修改 pkg/cable/libreswan/connection_file.go 中的连接超时参数。
• 检查并修复节点间的网络延迟问题，确保网络往返时间（RTT）在可接受范围内。

3. 高级故障排除工具 🛠️

Submariner 提供了多种工具帮助诊断复杂问题：

3.1 健康检查工具

使用内置的健康检查器验证跨集群连接状态：

kubectl exec -n submariner-operator <submariner-gateway-pod-name> -- /submariner healthcheck

健康检查逻辑定义在 pkg/cableengine/healthchecker/healthchecker.go。

3.2 日志收集脚本

利用项目提供的日志收集工具获取详细诊断信息：

git clone https://gitcode.com/gh_mirrors/su/submariner cd submariner ./scripts/e2e/external/utils collect-logs

日志收集脚本位于 scripts/e2e/external/utils。

4. 预防措施与最佳实践 🚀

• 定期更新：保持 Submariner 版本最新，参考 versions/version.go 了解版本信息。
• 监控部署：部署 Prometheus 和 Grafana 监控 Submariner 指标，相关指标定义在 pkg/cable/metrics.go。
• 备份配置：定期备份 Submariner 配置文件，特别是 deploy/crds/ 目录下的 CRD 定义文件。

通过本手册提供的方法，大多数 Submariner 网络连接问题都能得到快速解决。如遇到复杂问题，建议查阅项目 CONTRIBUTING.md 文档，获取社区支持渠道信息。

【免费下载链接】submarinerNetworking component for interconnecting Pods and Services across Kubernetes clusters.项目地址: https://gitcode.com/gh_mirrors/su/submariner