在 Apple Silicon Mac 上手工搭建 Kubernetes 集群：Multipass 环境准备与前置条件详解

• 文档/教程

本文是《Kubernetes The Hard Way on Apple Silicon》实战路线的开篇指南，面向想在 M1/M2/M3 芯片 Mac 上、用 Multipass 在本地手工引导一个多节点 Kubernetes 集群的开发者。文章以 apple-silicon/docs/01-prerequisites.md 为核心骨架，结合仓库中的 部署脚本 与 节点初始化脚本 源码，完整讲解硬件要求、软件安装、双网卡网络设计与PRIMARY_IP机制、以及 iterm2 并行操作技巧，读完即可无缝进入下一章「Compute Resources」完成 5 台 VM 的创建与验证。

一、实验背景：为什么在 Apple Silicon 上要换一套方案

本仓库（kubernetes-the-hard-way）是 Kelsey Hightower 原版教程的本地化改编：原版基于 GCP 云平台，而本项目在本地机器上用 Hypervisor 引导集群。仓库 README.md 明确指出：Windows / Intel Mac 用户走 VirtualBox 路线，而 Apple Silicon（M1/M2/M3）用户走本套件（apple-silicon）下的 Multipass 路线。

由于 Apple Silicon 无法使用 VirtualBox，本路线改用Canonical 官方轻量级虚拟机管理器 Multipass来创建和管理 Ubuntu VM。整套实验会在一台 Mac 工作站上拉起5 台虚拟机：两台控制平面节点（controlplane01、controlplane02）、一台负载均衡器（loadbalancer，运行 HAProxy）和两台工作节点（node01、node02）。这些节点后续将承载 etcd、kube-apiserver、kube-controller-manager、kube-scheduler、kubelet、kube-proxy 与 Weave 网络等全部 Kubernetes 组件，以 systemd 服务而非 kubeadm 的方式手工引导，因此环境准备阶段做得越扎实，后续排错成本越低。

二、硬件要求：内存与 CPU 是成败关键

原文档开门见山：本实验要在工作站上同时跑 5 台 VM，「这是一个不小的计算资源消耗」。

2.1 芯片与内存基线

原文档特别强调了一个容易被忽略的事实：Apple Silicon 采用统一内存架构（Unified Memory Architecture），标称内存并非全部可供软件使用——一部分会被显示系统占用，外接显示器越多占用越多。因此：

• 少于 16GB 内存时，部署脚本会显著缩小 VM 规格，不足以保证最终 E2E 测试顺利跑通；
• 8GB 内存只适合「把集群搭起来、走通前面十几章」的最低目标。

2.2 部署脚本的自动降配逻辑（源码佐证）

原文档的内存警告并非空话，仓库中的 deploy-virtual-machines.sh 用一段精确的检测逻辑将其落实为代码。脚本先通过sysctl hw.memsize读取物理内存总量并换算为 GB（第 17 行）：

MEM_GB=$(( $(sysctl hw.memsize | cut -d ' ' -f 2) / 1073741824 ))

随后在 deploy-virtual-machines.sh 中判定：当系统 RAM 小于 15GB 时，控制平面 VM 内存降为768M、工作节点降为512M，并打印黄色警告：

if [ $MEM_GB -lt 15 ] then CPMEM="768M" WNMEM="512M" echo -e "${YELLOW}System RAM is ${MEM_GB}GB. VM size is reduced." echo -e "It will not be possible for you to run E2E tests (final step).${NC}" fi

内存充足时，脚本按下面的规格创建 5 台 VM（deploy-virtual-machines.sh）：

specs=/tmp/vm-specs cat <<EOF > $specs controlplane01,2,2048M,10G controlplane02,2,2048M,5G loadbalancer,1,512M,5G node01,2,2048M,5G node02,2,2048M,5G EOF

格式为节点名,CPU 核数,内存,磁盘。可见即使内存充足，负载均衡器也只分配 512M——它只承担 HAProxy 转发，配置故意最小化。而每台控制平面和工作节点各分配 2 核 CPU 与 2GB 内存，正是为了支撑后续多个 Kubernetes 组件进程同时运行。

2.3 CPU：Pro / Max 与 E2E 测试

原文档建议使用 Pro 或 Max 芯片，主要服务于最后一步的可选实验 E2E Tests。该文档补充说明：E2E 测试通过 kubetest2 + ginkgo 并发执行大量 Conformance 用例，并以controlplane01的 CPU 核数决定并行度（--parallel $NUM_CPU）；低配处理器容易因降频或大小核切换导致集群不稳定、测试超时。因此在环境准备阶段就该明白：本实验的「标准配置」是 16GB 内存 + Pro/Max 芯片，低配机器请把期望值设定为「成功引导集群」而非「跑完 E2E」。

三、必备软件：Multipass、JQ 与管理员权限

3.1 Multipass：本路线的核心虚拟化引擎

Multipass 是 Canonical 出品的轻量虚拟机工具，macOS 下以 GUI 安装包分发，也支持通过 Homebrew 等方式安装（brew install --cask multipass）。原文档给出的验收标准非常明确：安装后必须先按其官方指引成功创建一台测试用的 Ubuntu VM，确认工具工作正常，然后删除这台测试 VM，再进入本实验。

这一验收步骤之所以必要，是因为后续所有章节都建立在multipass launch、multipass shell、multipass transfer、multipass exec等命令正常可用的基础上——部署脚本 deploy-virtual-machines.sh 在启动阶段就会显式检查multipass命令是否存在，缺失则直接报错退出：

if ! command -v multipass > /dev/null then echo -e "${RED}Cannot find multipass. Did you install it as per the instructions?${NC}" exit 1 fi

3.2 JQ：JSON 解析必备工具

JQ 在部署阶段承担关键角色：部署脚本用multipass list --format json、multipass info <node> --format json获取 JSON 输出，再交给jq提取节点名、IP 地址等信息（见 deploy-virtual-machines.sh 与 deploy-virtual-machines.sh）。macOS 上通过brew install jq即可安装。与 multipass 一样，脚本启动时也会校验 jq 是否可用（deploy-virtual-machines.sh）。

3.3 管理员权限

Mac 登录账号必须具备管理员权限并能使用sudo。原因有两层：

• 本机层面：Multipass 创建 VM 需要 Hypervisor 权限；
• VM 内部层面：节点初始化脚本大量使用sudo（修改/etc/hosts、写入/etc/environment、重启 sshd 等）。

3.4 克隆仓库

在 Mac 终端中执行以下命令拉取仓库并进入 Apple Silicon 工作目录：

mkdir ~/kodekloud cd ~/kodekloud git clone https://gitcode.com/gh_mirrors/kub/kubernetes-the-hard-way.git cd kubernetes-the-hard-way/apple-silicon

后续所有命令默认都在该apple-silicon目录下执行。注意：本套件的文档体系与 VirtualBox 套件共享docs/下从「Client Tools」开始的所有实验章节，二者的分叉点只在 VM 创建方式（Multipass vs VirtualBox）。

四、虚拟机网络架构：双网卡与 PRIMARY_IP 机制

4.1 为什么每台 VM 需要两块网卡

原文档指出，Multipass 的虚拟化方式决定了每台 VM 拥有两块网络适配器：一块由 Multipass 管理（用于multipass shell等管理通道），另一块用于其余一切通信。问题在于，Kubernetes 各组件默认可能绑定到 Multipass 适配器对应的网卡，而这不是我们想要的。

解决办法是本套件在设计上的一个精髓：在每台 VM 上预置一个环境变量PRIMARY_IP，所有 Kubernetes 组件统一以它作为绑定/监听的 IP 地址。后续各章节（etcd、kube-apiserver、kubelet 等）的 systemd 单元文件中都会引用PRIMARY_IP，确保流量走正确的网卡。

PRIMARY_IP的定义非常明确：

节点上「连接了默认网关所在网络」的那块网卡的 IP 地址，也就是该节点用来与其他节点通信的地址。

4.2 源码级印证：PRIMARY_IP 与 ARCH 如何落盘

仓库中的节点初始化脚本 scripts/01-setup-hosts.sh 忠实实现了上述设计。该脚本在第 8 行通过路由表推导出 PRIMARY_IP 并写入/etc/environment（对 systemd 环境变量全局生效）：

# Export internal IP of primary NIC as an environment variable echo "PRIMARY_IP=$(ip route | grep default | awk '{ print $9 }')" | sudo tee -a /etc/environment > /dev/null

同时在第 11 行写入架构变量ARCH=arm64：

# Export architecture as environment variable to download correct versions of software echo "ARCH=arm64" | sudo tee -a /etc/environment > /dev/null

这个ARCH变量在后续章节中持续发挥作用——例如 docs/03-client-tools.md 中的kubectl安装命令就依赖它拼接 arm64 下载路径（bin/linux/${ARCH}/kubectl），保证在 Apple Silicon 上拉取正确的二进制。

01-setup-hosts.sh还做了另外几件与网络/访问密切相关的事：

• 将本机节点名从/etc/hosts中移除，并把部署脚本生成的hostentries（节点名 ↔ IP 映射）追加进去，实现节点间主机名解析；
• 开启 sshd 的密码认证并重启 sshd（为后续ssh-copy-id做准备）；
• 在controlplane01上额外安装sshpass（用于自动化的跨节点拷贝）；
• 将ubuntu用户密码统一设为ubuntu（后续登录其他节点时的统一口令）。

4.3 NAT 网络模式：出得去、进不来

Multipass 默认的 NAT 配置下，VM 所在网络与你的宽带路由器网络之间隔着一道由 Hypervisor 管理的 NAT 网关，因此：

• VM 可以访问外网（apt 下载软件包、curl 拉取 Kubernetes 二进制等，全部依赖这一点）；
• 外部无法进入 VM 网络，例如你无法用浏览器通过 NodePort 访问集群里的服务。

原文档特别提醒：Multipass目前不支持为这种 NAT 网络配置端口转发规则，所以「浏览器访问 NodePort」这种需求在本实验的默认网络下是做不到的。VM 所在网段由 Multipass 自动选择（通常是192.168.64.0/24），无需也不建议手工指定。

4.4 Pod 与 Service 网段：保持默认

原文档强烈建议保持 Pod 网络与 Service 网络的默认取值。原因有二：

1. 后续章节使用的 Weave 网络清单（deployments/coredns.yaml 对应的 Weave 清单体系）是按默认网段写死的，改动网段意味着要同步修改 Weave manifest；
2. 自定义网段属于个人偏好调整，仓库作者明确表示不建议为此提交 Pull Request（见原文档说明）。

五、iterm2 并行命令执行：批量操作提速技巧

5.1 为什么需要并行执行

本实验存在大量「同一命令需要在多台节点上执行」的场景，典型如：为所有节点安装 containerd、kubelet 等 Kubernetes 软件。逐台登录、逐台敲命令既慢又容易漏。原文档给出的提速方案是使用iterm2的分屏 + 广播（Broadcast）功能，让一份输入同时送达多个会话。

注意：iterm2 属于可选工具，不装也完全可以完成整个实验。

5.2 配置步骤

按原文档，在 iterm2 中按以下三步即可搭建上图所示的并行操作环境：

1. 右键点击窗口，选择「Split Pane Horizontally（水平分屏）」，根据需要拆出多个面板；
2. 在每个面板中，用multipass shell <节点名>分别连接到不同的节点（例如controlplane01、controlplane02、node01、node02）；
3. 从顶部Session菜单勾选Broadcast → Broadcast input to all panes（快捷键ALT-CMD-I）。面板右上角的小图标会提示广播模式已开启。

之后在任意一个命令提示符中输入的内容都会被同时回显到其他所有面板。

5.3 使用注意事项

• 广播模式下，任何输入（包括确认密码、回车）都会同步到所有节点，因此只应在「所有节点都需要执行完全相同命令」时开启；
• 完成某段适用于多节点的操作后，务必关闭广播，再回到单节点操作，避免误把只应在controlplane01上执行的命令广播出去；
• 每块面板对应一台独立节点，配合hostname命令随时确认当前会话所在节点，是避免「在错误的节点执行命令」的最有效手段。

六、下一步：创建并验证虚拟机（Compute Resources）

环境准备就绪后，进入下一章 Compute Resources。核心动作是执行部署脚本：

./deploy-virtual-machines.sh

该脚本（deploy-virtual-machines.sh）的执行流程与上文内容完全闭环：

1. 兼容性检查：校验multipass、jq存在，并根据物理内存决定 VM 规格（见第二节）；
2. 防重入处理：若同名 VM 已在运行，会询问是否删除重建；
3. 批量创建：对规格表中的每台 VM 执行multipass launch --disk <磁盘> --memory <内存> --cpus <核数> --name <节点名> jammy（第 84 行），镜像固定为 Ubuntu 22.04 LTS（jammy）；
4. 网络与主机名初始化：收集各 VM 的 IPv4 地址生成hostentries，连同 scripts/01-setup-hosts.sh 一起通过multipass transfer推送到每台节点并执行，完成/etc/hosts、PRIMARY_IP、ARCH=arm64、sshd 密码认证等初始化（见第四节）；
5. 工具分发：将证书校验脚本 cert_verify.sh 分发到所有节点，将 approve-csr.sh 分发到controlplane01（后者用于后续 TLS Bootstrap 阶段批准 node02 的证书签名请求）。

创建完成后，用multipass shell <节点名>逐一验证 5 台 VM 均可登录（提示符形如ubuntu@controlplane01:~$），exit返回 Mac 终端。

实验全部结束、想回收资源时，运行 delete-virtual-machines.sh 停止并删除全部 VM，然后手工清理 stale DHCP 租约：Multipass 不会自动清理，长期不清理会导致 Multipass VM 网段的 IP 地址被耗尽。清理方式为编辑/var/db/dhcpd_leases（macOS 上sudo vi /var/db/dhcpd_leases），删除所有name形如controlplane、node、loadbalancer的租约块：

{ name=controlplane01 ip_address=192.168.64.4 hw_address=1,52:54:0:78:4d:ff identifier=1,52:54:0:78:4d:ff lease=0x65dc3134 }

七、常见问题与排错要点

• multipass命令找不到：未安装或未加入 PATH。先按官方指引安装并成功创建一台测试 Ubuntu VM，验证后再删除测试 VM 进入本实验。
• VM 规格明显偏小（如 512M）：说明本机物理内存不足 15GB，部署脚本已自动降配。请查看sysctl hw.memsize确认实际内存，并接受「跑不了 E2E 测试」的限制。
• PRIMARY_IP未生效：检查/etc/environment是否包含PRIMARY_IP=行；该变量由 01-setup-hosts.sh 写入，若曾手工改过/etc/hosts或网络配置，可能导致 IP 与后续章节 systemd 单元文件中的引用不一致。
• 节点间无法互访：确认/etc/hosts中已包含全部 5 个节点的hostentries映射，且未残留本机主机名的旧条目（脚本第 4 行会先删除旧条目再追加）。
• 后续章节证书校验失败：本实验对细节要求极高，仓库 README.md 建议在关键步骤后运行cert_verify.sh（apple-silicon/scripts/cert_verify.sh），若输出红色信息，说明此前某一步做错了，应回溯修正而非继续。

完成上述准备后，你就拥有了一个由 5 台 Multipass VM 组成的、具备正确双网卡路由与统一PRIMARY_IP语义的实验环境。下一站是 Compute Resources 的 VM 部署与验证，之后从 Client Tools 开始，控制平面与工作节点的引导工作将正式展开。

• 文档/教程