如何使用k3d在多台Mac Mini主机上搭建K8s集群

前提：两台Mac Mini处于同一个二层局域网、可互相ping通，且均已安装适配版本的k3d、Docker Desktop。

方案1：Docker Overlay网络（通用适配方案） #

k3d默认使用主机本地Docker网络，通过Docker Swarm的overlay网络可实现跨主机容器互通，是兼容性最高的实现方式：

• 选择其中一台Mac Mini作为控制平面所在主机（记为主机A，假设物理IP为192.168.1.10），执行命令初始化Swarm集群：docker swarm init --advertise-addr 192.168.1.10
• 执行完成后终端会输出worker节点加入命令，复制该命令到另一台Mac Mini（记为主机B）执行，完成Swarm集群组建
• 在主机A上创建可跨主机共享的attachable类型overlay网络：docker network create --driver overlay --attachable k3d-overlay，Swarm会自动将该网络同步到主机B
• 在主机A上创建k3d控制平面，指定使用overlay网络、监听物理IP的API端口：k3d cluster create --network k3d-overlay --api-port 192.168.1.10:6443 --no-workers，如果需要在主机A上部署本地worker节点可删除--no-workers参数
• 执行命令获取集群加入token，记录输出的token值：docker exec -it k3d-k3s-default-server-0 cat /var/lib/rancher/k3s/server/token
• 在主机B上执行命令启动k3s容器作为worker节点加入集群，注意替换命令中的token和k3s版本号（需和主机A的k3s版本完全一致）：

  docker run -d --name k3d-worker-b-0 \
  --network k3d-overlay \
  --privileged \
  --tmpfs /run \
  --tmpfs /var/run \
  -e K3S_URL=https://192.168.1.10:6443 \
  -e K3S_TOKEN=刚才记录的token值 \
  rancher/k3s:<对应版本号> agent
  

• 回到主机A执行kubectl get nodes即可看到跨主机的worker节点已成功加入集群

方案2：Macvlan网络（高性能方案） #

如果对集群网络性能要求更高，可使用Docker macvlan驱动直接给k3d容器分配局域网物理IP，减少网络转发损耗：

• 首先通过ifconfig确认两台Mac Mini的物理网卡名称，有线网卡通常为en0，无线网卡通常为en1
• 在两台机器上分别创建同配置的macvlan网络，假设你的局域网网段为192.168.1.0/24、网关为192.168.1.1，执行命令：

  docker network create -d macvlan \
  --subnet=192.168.1.0/24 \
  --gateway=192.168.1.1 \
  -o parent=en0 \
  k3d-macvlan
  

• 后续集群创建、节点加入逻辑和方案1完全一致，仅需将网络参数替换为k3d-macvlan，同时可以给控制平面容器直接分配静态局域网IP作为API Server地址。

注意事项 #

• Docker Desktop for Mac的网络实现有特殊适配，overlay模式下如果出现跨主机容器不通的情况，先检查两台机器的防火墙是否放开了Swarm所需端口：2377/tcp、7946/tcp/udp、4789/udp
• 两种方案均兼容k3d原有命令逻辑，不需要修改核心配置，后续新增节点可复用相同的加入流程
• 集群的Ingress、LoadBalancer等功能可直接使用物理主机IP做端口映射，配置逻辑和单主机k3d完全一致

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