Kubernetes The Hard Way 前置条件全解：手工搭建集群的四台机器规划、环境验证与资源核对清单

本篇基于 Kubernetes The Hard Way 教程的第一步实验（docs/01-prerequisites.md）展开，系统讲解在没有脚本自动化的前提下，手工引导一个 Kubernetes 集群所需的机器规格、操作系统版本与架构要求。读完本文，你将能够规划出满足教程最低要求的四台 Debian 12 机器，掌握用 /etc/os-release 验证系统环境的方法，并了解后续各实验中将在这几台机器上部署哪些 Kubernetes 组件及其版本依据。

教程定位：为什么叫“Hard Way”

Kubernetes The Hard Way 的目标不是用自动化工具快速拉起集群，而是刻意选择“长路径”：每一步（证书签发、组件配置、系统服务安装）都由操作者亲手完成，以确保读者真正理解引导一个 Kubernetes 集群所需的每个任务。正如 README.md 所述，该教程“optimized for learning”，其结果不应被视为生产就绪的部署方式。

该教程最终引导出的集群拓扑是：所有控制面组件运行在单台节点上，外加两台工作节点。这一规模足以覆盖 Kubernetes 核心概念的完整学习路径，也是后文机器规格表的设计依据。

机器数量与规格要求

教程明确要求 四台（4 台）虚拟或物理机器，架构必须是 ARM64 或 AMD64，操作系统必须是 Debian 12 (bookworm)。原文档给出的规格表如下，本文完整保留：

名称	用途	CPU	内存	存储
jumpbox	管理主机（Administration host）	1	512MB	10GB
server	Kubernetes 服务器（承载全部控制面组件）	1	2GB	20GB
node-0	Kubernetes 工作节点	1	2GB	20GB
node-1	Kubernetes 工作节点	1	2GB	20GB

需要特别注意的是，原文档强调：如何创建这四台机器由你自行决定，唯一的要求是每台机器满足上表中的规格和操作系统版本。这意味着你可以使用本地虚拟化（QEMU、VirtualBox、VMware）、公有云实例，甚至现成的物理服务器；但 jumpbox 的角色（运行 kubectl、存放二进制、作为所有操作的出发点）在后续实验中不可替换。

四个角色各自承担什么

结合仓库中的其他文档与配置文件，可以清楚看到这四台机器在教程中的分工：

• jumpbox：在 docs/02-jumpbox.md 中安装命令行工具（wget、curl、openssl、git 等）、克隆本仓库、下载并整理所有组件二进制，并安装 kubectl 作为集群就绪后的交互入口。它不加入集群，只负责“指挥”。
• server：从 units/ 目录中的服务单元可以看到，它将运行 kube-apiserver、kube-controller-manager、kube-scheduler、etcd 四个控制面系统服务，以及容器运行时 containerd——这也解释了为什么它的内存要求（2GB）高于 jumpbox。
• node-0 / node-1：运行 kubelet、kube-proxy 和 containerd、runc，即真正承载 Pod 工作负载的节点。units/kubelet.service 与 units/kube-proxy.service 分别对应这两个组件的 systemd 单元。

验证操作系统版本

四台机器全部创建完成后，第一步的验收动作是逐台查看 /etc/os-release 文件：

cat /etc/os-release

原文档给出的预期输出如下（Debian 12 bookworm 的典型内容）：

PRETTY_NAME="Debian GNU/Linux 12 (bookworm)"
NAME="Debian GNU/Linux"
VERSION_ID="12"
VERSION="12 (bookworm)"
VERSION_CODENAME=bookworm
ID=debian

验证要点：

• VERSION_ID 必须是 "12"，VERSION_CODENAME 必须是 bookworm。后续实验中的包管理操作（apt-get）、系统默认工具链都基于 Debian 12 的发行版特性编写，使用其他发行版可能无法按文档步骤原样执行；
• 该检查应在全部四台机器上分别执行，而不是只在其中一台上验证。

架构要求与二进制对应关系

“ARM64 或 AMD64”这一要求并非泛泛而谈——仓库中的 downloads-amd64.txt 和 downloads-arm64.txt 分别维护了两套架构下的完整二进制下载清单。以 AMD64 清单为例（downloads-amd64.txt）：

https://dl.k8s.io/v1.32.3/bin/linux/amd64/kubectl
https://dl.k8s.io/v1.32.3/bin/linux/amd64/kube-apiserver
https://dl.k8s.io/v1.32.3/bin/linux/amd64/kube-controller-manager
https://dl.k8s.io/v1.32.3/bin/linux/amd64/kube-scheduler
https://dl.k8s.io/v1.32.3/bin/linux/amd64/kube-proxy
https://dl.k8s.io/v1.32.3/bin/linux/amd64/kubelet
https://github.com/kubernetes-sigs/cri-tools/releases/download/v1.32.0/crictl-v1.32.0-linux-amd64.tar.gz
https://github.com/opencontainers/runc/releases/download/v1.3.0-rc.1/runc.amd64
https://github.com/containernetworking/plugins/releases/download/v1.6.2/cni-plugins-linux-amd64-v1.6.2.tgz
https://github.com/containerd/containerd/releases/download/v2.1.0-beta.0/containerd-2.1.0-beta.0-linux-amd64.tar.gz
https://github.com/etcd-io/etcd/releases/download/v3.6.0-rc.3/etcd-v3.6.0-rc.3-linux-amd64.tar.gz

ARM64 清单（downloads-arm64.txt）结构与之一一对应，仅将路径中的 amd64 替换为 arm64。这与 README.md 中声明的组件版本完全吻合：

• Kubernetes v1.32.x（清单中精确到 v1.32.3）
• containerd v2.1.x（清单中为 2.1.0-beta.0）
• CNI plugins v1.6.x（清单中为 v1.6.2）
• etcd v3.6.x（清单中为 3.6.0-rc.3）

这些版本组合定义了本教程的适用边界：如果你计划使用其他 Kubernetes 大版本，仓库中的配置模板与下载清单需要相应调整，不能直接套用。

后续实验对环境的隐含要求

虽然第一步实验只要求“满足规格 + 系统正确”，但通读后续实验可以从源码级材料确认几个在规划阶段就应该满足的前提，避免中途返工：

1. 同网段可达性：README.md 明确说明四台机器需连接到同一网络。docs/03-compute-resources.md 进一步指出，机器地址可以任意，前提是“每台机器之间以及 jumpbox 之间互可达”。
2. root SSH 访问：教程所有命令都以 root 用户执行（见 docs/02-jumpbox.md 中 ssh root@jumpbox 的用法），三台集群机器需要预先具备或后续开通 root SSH 登录。
3. 主机名与 FQDN 规划：机器数据库 schema 为 IPV4_ADDRESS FQDN HOSTNAME POD_SUBNET（docs/03-compute-resources.md），示例条目使用 server.kubernetes.local、node-0.kubernetes.local、node-1.kubernetes.local 作为 FQDN。这些名称并非随意：
   • 从 ca.conf 可以看到，node-0、node-1 的客户端证书 SAN 写死为 DNS:node-0, IP:127.0.0.1 与 DNS:node-1, IP:127.0.0.1，证书主体为 system:node:node-0 / system:node:node-1，即 kubelet 注册集群所用的身份；
   • API Server 证书 SAN 中包含 DNS:server.kubernetes.local 与 DNS:api-server.kubernetes.local（ca.conf 的 kube-api-server_alt_names 段）。 因此规划阶段就应确定沿用这套命名，或同步修改 ca.conf。
4. Pod 网段预留：机器数据库中的 POD_SUBNET 列（示例为 10.200.0.0/24 与 10.200.1.0/24）是每台工作节点上 Pod 使用的独立地址段，由 docs/11-pod-network-routes.md 中手工配置的路由来打通，规划网段时需保证与机器所在物理网段不冲突。

开始前核对清单

综合第一步实验与仓库中可验证的材料，开始正式操作（进入 Setting up the Jumpbox）前建议逐项核对：

核对项	标准	验证方式 / 依据
机器数量	4 台（jumpbox + server + node-0 + node-1）	docs/01-prerequisites.md
CPU 架构	ARM64 或 AMD64 之一，且全集群一致	downloads-amd64.txt / downloads-arm64.txt
操作系统	Debian 12 (bookworm)，四台全部一致	各机执行 cat /etc/os-release
资源规格	jumpbox：1C/512MB/10GB；server 与两台 node：1C/2GB/20GB	docs/01-prerequisites.md
网络	四台机器两两可达，jumpbox 可 SSH 到其余三台	README.md、docs/03-compute-resources.md
命名	确定 HOSTNAME/FQDN（默认 server、node-0、node-1）与各自 Pod 子网	docs/03-compute-resources.md、ca.conf

当以上核对项全部通过时，即可按教程的既定顺序推进：先配置 jumpbox 并下载二进制（docs/02-jumpbox.md），再完成计算资源的 SSH、主机名与 hosts 配置（docs/03-compute-resources.md），随后进入证书与 CA 引导（docs/04-certificate-authority.md）等后续实验。