2. ClusterMesh 安装与初始化：Helm 部署 Cilium 并启用 ClusterMesh、ClusterMesh API Server 配置、集群间证书与密钥交换

ClusterMesh 的初始化是构建多集群网络的核心步骤。本节将引导你完成从 Helm 部署 Cilium 到启用 ClusterMesh、配置 API Server 以及完成集群间证书与密钥交换的全过程。正确的初始化是后续拓扑编排与租户隔离的基础。

2.1 环境准备与前提条件

在开始安装前，请确保每个集群满足以下条件。这是避免后续故障的关键检查清单。

2.2 Helm 部署 Cilium 并启用 ClusterMesh

使用 Helm 部署 Cilium 时，需要同时启用 ClusterMesh 相关参数。以下为推荐的生产级配置模板。

# 添加 Cilium Helm 仓库
helm repo add cilium https://helm.cilium.io/
helm repo update

# 部署 Cilium 并启用 ClusterMesh（以 cluster1 为例）
helm upgrade --install cilium cilium/cilium \
  --namespace kube-system \
  --set cluster.name=cluster1 \
  --set cluster.id=1 \
  --set ipam.mode=kubernetes \
  --set ipv4NativeRoutingCIDR=10.0.0.0/8 \
  --set autoDirectNodeRoutes=true \
  --set routingMode=native \
  --set bpf.masquerade=true \
  --set tunnelProtocol=vxlan \
  --set clusterMesh.enabled=true \
  --set clusterMesh.config.enabled=true \
  --set clusterMesh.config.domain="mesh.example.com" \
  --set clusterMesh.config.etcd.enabled=true \
  --set clusterMesh.config.etcd.endpoints[0]="https://etcd-0.mesh.example.com:2379" \
  --set clusterMesh.config.etcd.endpoints[1]="https://etcd-1.mesh.example.com:2379" \
  --set clusterMesh.config.etcd.endpoints[2]="https://etcd-2.mesh.example.com:2379" \
  --set clusterMesh.config.etcd.caCert="<base64-ca-cert>" \
  --set clusterMesh.config.etcd.clientCert="<base64-client-cert>" \
  --set clusterMesh.config.etcd.clientKey="<base64-client-key>"

2.3 ClusterMesh API Server 配置

每个集群的 ClusterMesh API Server 负责暴露本集群的 etcd 状态，供其他集群发现服务与端点。配置过程包括生成证书、创建 Secret 以及验证 API Server 状态。

2.3.1 生成 API Server 证书

使用 cfssl 或 openssl 为每个集群生成独立的 TLS 证书。证书 CN 必须包含集群域名。

# 生成 CA 证书（仅首次执行）
cfssl gencert -initca ca-csr.json | cfssljson -bare ca

# 为 cluster1 生成 API Server 证书
cfssl gencert \
  -ca=ca.pem \
  -ca-key=ca-key.pem \
  -config=ca-config.json \
  -profile=server \
  -hostname="cluster1.mesh.example.com,10.0.1.1" \
  cluster1-csr.json | cfssljson -bare cluster1

# 为 cluster2 生成 API Server 证书
cfssl gencert \
  -ca=ca.pem \
  -ca-key=ca-key.pem \
  -config=ca-config.json \
  -profile=server \
  -hostname="cluster2.mesh.example.com,10.0.2.1" \
  cluster2-csr.json | cfssljson -bare cluster2

2.3.2 创建 Kubernetes Secret

将生成的证书和密钥以 Secret 形式注入集群，供 Cilium 组件挂载。

# 在 cluster1 中创建 Secret
kubectl create secret generic clustermesh-apiserver-certs \
  --namespace kube-system \
  --from-file=ca.crt=ca.pem \
  --from-file=tls.crt=cluster1.pem \
  --from-file=tls.key=cluster1-key.pem

# 在 cluster2 中创建 Secret
kubectl create secret generic clustermesh-apiserver-certs \
  --namespace kube-system \
  --from-file=ca.crt=ca.pem \
  --from-file=tls.crt=cluster2.pem \
  --from-file=tls.key=cluster2-key.pem

2.3.3 验证 API Server 状态

部署完成后，检查 ClusterMesh API Server Pod 是否正常运行。

# 查看 ClusterMesh API Server Pod
kubectl get pods -n kube-system -l k8s-app=clustermesh-apiserver

# 查看 Service 暴露的端口
kubectl get svc -n kube-system clustermesh-apiserver

# 测试 API Server 连通性（从其他集群节点）
curl --cacert ca.pem --cert cluster2.pem --key cluster2-key.pem \
  https://cluster1.mesh.example.com:2379/health

2.4 集群间证书与密钥交换

证书交换是建立信任关系的关键步骤。每个集群需要将自身的 CA 证书和 API Server 证书分发给其他集群。Cilium 提供了 cilium clustermesh 命令行工具简化此过程。

2.4.1 使用 Cilium CLI 导出配置

# 在 cluster1 上导出 ClusterMesh 配置
cilium clustermesh export --output clustermesh-config-cluster1.yaml

# 在 cluster2 上导出 ClusterMesh 配置
cilium clustermesh export --output clustermesh-config-cluster2.yaml

2.4.2 手动交换证书文件

当 CLI 工具不可用时，可手动交换以下文件：

2.4.3 导入配置到目标集群

# 在 cluster2 上导入 cluster1 的配置
cilium clustermesh import -f clustermesh-config-cluster1.yaml

# 在 cluster1 上导入 cluster2 的配置
cilium clustermesh import -f clustermesh-config-cluster2.yaml

2.5 验证 ClusterMesh 初始化状态

完成上述步骤后，使用以下命令验证 ClusterMesh 是否成功建立。

# 查看 ClusterMesh 状态
cilium clustermesh status

# 查看集群间连接状态
cilium clustermesh connectivity check

# 查看 etcd 中注册的集群列表
etcdctl --endpoints=https://etcd-0.mesh.example.com:2379 \
  --cacert=ca.pem --cert=cluster1.pem --key=cluster1-key.pem \
  get /cilium/state/clustermesh/ --prefix

预期输出应显示所有集群状态为 Connected，且 etcd 中可列出各集群的节点信息。

2.6 常见问题与排错