架构设计
项目分为两个阶段：当前阶段先跑通低成本双云双集群链路，完全体阶段再扩展到高可用控制面、GitOps、监控、日志和备份恢复。
当前架构
当前阶段的设计重点：
- 两云各自保持独立 Kubernetes 集群，不把控制面跨云拉成一个单集群。
- WireGuard 解决节点之间的跨云 underlay 可达性。
- Ansible 负责节点初始化、WireGuard 配置和 kubeadm init/join。
- Cilium VXLAN tunnel 避免要求云路由表理解 PodCIDR。
- Cluster Mesh 解决跨集群服务发现和访问。
- L4 负载均衡只暴露 Kubernetes API 和 Cluster Mesh API，不承载业务 Ingress。
完全体架构
完全体增加：
- 多 master 控制面，API 入口后端健康检查稳定。
- GitOps 控制器管理基础组件和示例应用。
- Prometheus/Grafana/Alertmanager 监控节点、Kubernetes、Cilium 和业务指标。
- Fluent Bit + Elasticsearch/OpenSearch + Kibana 查询日志。
- etcd 备份、应用备份和恢复演练。
网络规划
| 项目 | 阿里云 | 腾讯云 |
|---|---|---|
| 地域 | cn-guangzhou | ap-guangzhou |
| VPC CIDR | 10.1.0.0/16 | 10.2.0.0/16 |
| 子网 CIDR | 10.1.1.0/24 | 10.2.1.0/24 |
| Pod CIDR | 172.16.0.0/16 | 172.17.0.0/16 |
| Service CIDR | 10.96.0.0/16 | 10.97.0.0/16 |
| WireGuard | 10.255.0.0/24 | 10.255.0.0/24 |
CIDR 规划要求：
- 两云 VPC 不能重叠。
- 两云 PodCIDR 不能重叠。
- 两云 ServiceCIDR 不能重叠。
- WireGuard 网段不能和 VPC、Pod、Service 网段重叠。
关键取舍
为什么不用托管 Kubernetes 起步
托管 Kubernetes 更省事，但会隐藏控制面初始化、kubeadm、节点组件和 CNI 接入过程。这个项目需要保留从云服务器到 Kubernetes 的完整过程，所以当前阶段使用 kubeadm。
为什么先用 WireGuard
云厂商托管 IPsec VPN 更接近生产方案，但会引入费用、双端公网 IP 获取顺序、路由表和厂商 API 差异。阶段一优先使用 WireGuard 建立节点级 underlay，先验证 Kubernetes 和 Cilium 多集群链路。
为什么 Cilium 使用 tunnel mode
VXLAN tunnel mode 能把 Pod 网络封装在节点网络之上，不要求云路由表维护 PodCIDR。这样 Terraform 只需要负责云网络和节点，Pod 网络交给 Cilium。
为什么固定 Cluster Mesh NodePort
固定 32379 后，安全组、负载均衡监听、脚本和排障命令都能稳定引用同一个端口，减少动态端口带来的不确定性。
分层验收
| 层 | 命令 | 证明 |
|---|---|---|
| Terraform | make aliyun-plan && make tencent-plan | 云资源定义可解析、变量基本正确 |
| 云资源 | make aliyun-output && make tencent-output | 已有可供脚本消费的 outputs |
| SSH | ssh -i ~/.ssh/hybrid-k8s <user>@<ip> | 节点可登录 |
| Ansible | make ansible-check && make ansible-ping | inventory、playbook 和 SSH 批量执行正常 |
| Underlay | make ansible-underlay && make check-underlay | WireGuard 跨云可达 |
| Kubernetes | make check-clusters | 节点和系统 Pod 正常 |
| Cilium | cilium status --context <ctx> --wait | CNI 正常 |
| Cluster Mesh | make check-clustermesh | 多集群连接正常 |