Kubernetes The Hard Way:手动理解集群引导
给想看懂 Kubernetes 集群内部引导过程的人,用手工步骤替代自动化脚本。
GitHub kelseyhightower/kubernetes-the-hard-way 更新 2026-09-26 分支 master 星标 50.1K 分叉 15.9K
Kubernetes 集群引导 containerd ARM64/AMD64

🧭 决策指南

适合,如果你

  • 你想理解 Kubernetes 核心组件如何协作,而不是直接获得自动化集群。
    README 的 Target Audience 和开头说明:教程为理解 fundamentals 和 core components 设计,不面向 fully automated tool。
  • 你能提供连接到同一网络的 4 台 ARM64 或 AMD64 虚拟机或物理机。
    README 的 Labs:requires four ARM64 or AMD64 based virtual or physical machines connected to the same network。
  • 你需要逐步学习 CA、TLS、etcd、kubectl 和 Pod 网络配置。
    README 的 Labs 列出了 Certificate Authority、Bootstrapping etcd、Configuring kubectl 和 Provisioning Pod Network Routes。

不适合,如果你

  • 你要用现成工具快速创建生产 Kubernetes 集群。
    README 明确说明本教程不是给寻找 fully automated tool 的人使用,且结果不应视为 production ready。
  • 你无法准备 4 台 ARM64 或 AMD64 且处于同一网络的机器。
    README 的 Labs 将四台同网虚拟或物理机器列为要求。
  • 你只需要一个可直接运行的 Kubernetes 集群,而不想执行 13 个手动 Labs。
    README 将项目描述为 optimized for learning,并列出从 Prerequisites 到 Cleaning Up 的 13 个 Labs。

前置条件

  • 需要 4 台 ARM64 或 AMD64 虚拟机或物理机,并连接到同一网络;Requires four ARM64 or AMD64 virtual or physical machines connected to the same network.
  • 组件版本包括 Kubernetes v1.32.x、containerd v2.1.x、CNI v1.6.x 和 etcd v3.6.x;Component versions include Kubernetes v1.32.x, containerd v2.1.x, CNI v1.6.x, and etcd v3.6.x.
  • 集群拓扑为单节点控制平面加两个 Worker 节点;The cluster topology is one control-plane node and two worker nodes.

要注意

  • 控制平面组件集中在单个节点,不代表高可用拓扑。
    README 的 Cluster Details 明确写明 all control plane components running on a single node。
  • 教程结果不应直接当作生产集群部署结果。
    README 警告:The results of this tutorial should not be viewed as production ready。
  • 清理步骤位于第 13 个 Lab,部署过程包含多项手工配置。
    README 的 Labs 同时列出 Cleaning Up,以及 CA、TLS、etcd 和网络路由等步骤。
  • 项目元数据与 README 的许可证名称不一致,需要核对授权边界。
    项目元数据标为 Apache License 2.0,README Copyright 标为 Creative Commons Attribution-NonCommercial-ShareAlike 4.0。

材料未说明

  • README 未说明支持的操作系统、云平台和虚拟机资源规格;The README does not specify supported operating systems, cloud platforms, or machine resource sizes.
  • README 未提供可直接复制的启动命令;The README provides no directly copyable startup command.
  • README 未说明四台机器之间所需的具体端口和网络配置;The README does not specify the exact ports or network configuration required between the four machines.
  • README 未说明 Kubernetes v1.32.x、containerd v2.1.x、CNI v1.6.x 和 etcd v3.6.x 之外的兼容性范围;The README does not state compatibility ranges beyond Kubernetes v1.32.x, containerd v2.1.x, CNI v1.6.x, and etcd v3.6.x.
  • README 未说明社区支持的具体渠道、响应时间或故障处理范围;The README does not specify support channels, response times, or troubleshooting scope.

💡 深度解析

6
不适合 我准备把 Kubernetes v1.32.x、containerd v2.1.x 的单控制面加两个工作节点拓扑直接用于生产,这个项目能作为部署方案吗?
适合读者: 需要为生产环境交付 Kubernetes 的 DevOps 工程师,计划使用 Kubernetes v1.32.x、containerd v2.1.x 和单控制面加两个工作节点的规模作为正式集群

不适合,因为 README 明确把它定位为学习教程,并明确警告结果不是生产就绪部署。

  • Cluster Details 只描述单节点控制面和两个工作节点;控制面没有冗余,无法满足高可用要求。
  • README 的实验重点是手工 bootstrap,包括证书、配置文件、etcd、控制面、工作节点和 Pod 网络,而不是生产平台的升级、备份、监控或安全运营。
  • 项目明确说不面向寻找 fully automated tool 的用户,手工流程也会放大配置遗漏和人为输入风险。
  • 因此它可以帮助你理解 Kubernetes 原生组件,但不能直接替代生产部署设计。
  • README 原句:The results of this tutorial should not be viewed as production ready
  • Cluster Details:all control plane components running on a single node, and two worker nodes
  • README 原句:This guide is not for someone looking for a fully automated tool
  • Labs:Cleaning Up
  • 项目洞察:不覆盖高可用、备份恢复、监控、升级和安全加固
材料未说明:README 未定义生产环境所需的 SLA、容量、备份策略、升级路径、监控方案和安全基线。;README 未说明单控制面故障时 etcd 数据和 API Server 服务的恢复流程。
适合 我有 4 台连接到同一网络的 ARM64 虚拟机,想按 Kubernetes v1.32.x、containerd v2.1.x、CNI v1.6.x 和 etcd v3.6.x 的版本学习集群引导,这个项目适合我吗?
适合读者: 正在学习 Kubernetes 基础机制、手头有 4 台同网的 ARM64 或 AMD64 虚拟机,并希望使用 Kubernetes v1.32.x、containerd v2.1.x、CNI v1.6.x 和 etcd v3.6.x 的学习者

适合,因为它正是面向 Kubernetes 原理学习、而不是快速安装的手工教程。

  • README 明确说明项目用于理解每项引导任务以及核心组件如何协作。
  • 你的 4 台 ARM64 虚拟机满足实验环境要求;拓扑包含单节点控制面和两个工作节点,另有 Jumpbox。
  • 教程覆盖 CA/TLS、认证配置、数据加密密钥、etcd、控制面、工作节点、kubectl、Pod 网络和 Smoke Test,学习链路完整。
  • 但它明确不是生产就绪方案,且需要手工执行较多步骤;如果目标只是尽快得到可用集群,就不适合。
  • Target Audience:理解 Kubernetes fundamentals 以及 core components 如何协作
  • Cluster Details:single node 上运行全部 control plane components,two worker nodes
  • Labs:requires four ARM64 or AMD64 based virtual or physical machines connected to the same network
  • Labs:Provisioning the CA and Generating TLS Certificates;Bootstrapping the etcd Cluster;Smoke Test
  • README 原句:This guide is not for someone looking for a fully automated tool
材料未说明:README 未说明这 4 台机器所需的 CPU、内存、磁盘容量和具体操作系统版本。;README 未说明 ARM64 与 AMD64 在各实验命令和组件包上的兼容性差异。
适合 我想先按 Kubernetes v1.32.x 的手工流程理解证书、etcd、控制面和 Pod 网络,再把它转换成自动化部署;这个项目适合作为自动化设计的基础吗?
适合读者: 想把手工 Kubernetes 引导过程转成自动化流程的 DevOps 工程师,当前实验基线是 4 台同网机器、单控制面、两个工作节点以及 Kubernetes v1.32.x

适合,但它适合作为自动化设计的参考基线,而不是现成的自动化工具。

  • README 明确说教程不是 fully automated tool,并将学习目标放在理解每项 bootstrap task;这有助于先拆分自动化任务边界。
  • Labs 已按 Prerequisites、Jumpbox、计算资源、PKI、认证、加密密钥、etcd、控制面、工作节点、kubectl、Pod 网络和验证分阶段组织,便于映射为模块或流水线阶段。
  • 组件版本和拓扑固定为 Kubernetes v1.32.x、containerd v2.1.x、CNI v1.6.x、etcd v3.6.x,以及单控制面、双工作节点,适合建立可比对的基线。
  • 但 README 没有提供脚本、API 或幂等性设计,因此自动化实现仍需自行完成。
  • README 原句:This guide is not for someone looking for a fully automated tool
  • README 原句:optimized for learning, which means taking the long route
  • Labs:13 个按阶段组织的实验,从 Prerequisites 到 Cleaning Up
  • Cluster Details:kubernetes v1.32.x;containerd v2.1.x;cni v1.6.x;etcd v3.6.x
  • Cluster Details:single node control plane and two worker nodes
材料未说明:README 未说明如何将各阶段转换为 Ansible、Terraform 或其他自动化工具的模块。;README 未定义自动化流程的幂等性、失败重试和状态管理要求。
适合 我已经接触过 kubeadm,但现在必须在单控制面加两个工作节点的拓扑里手工理解 CA、TLS、etcd 和控制面依赖,这个教程能否满足我的排障学习目标?
适合读者: 负责理解 TLS、etcd 和 Kubernetes 控制面依赖关系的平台工程师,当前需要摆脱 kubeadm 或云平台自动化,并在单控制面、双工作节点拓扑中排查引导问题

适合,因为教程把自动化安装器通常隐藏的信任链、认证和组件启动顺序拆成独立实验。

  • Labs 按顺序安排 CA/TLS、Kubernetes 配置文件、数据加密密钥、etcd、控制面和工作节点引导,适合建立依赖关系。
  • README 的目标不是自动化交付,而是让读者理解每项 bootstrap task;这与从 kubeadm 抽离出来学习故障域的目标一致。
  • 单控制面和双工作节点足以观察核心组件交互,但不能用于学习控制面高可用或大规模故障处理。
  • 教程结果明确不应视为 production ready,因此它适合作为排障训练材料,不适合作为生产集群模板。
  • README 原句:Kubernetes The Hard Way is optimized for learning
  • Labs:Provisioning the CA and Generating TLS Certificates
  • Labs:Generating Kubernetes Configuration Files for Authentication
  • Labs:Bootstrapping the etcd Cluster;Bootstrapping the Kubernetes Control Plane;Bootstrapping the Kubernetes Worker Nodes
  • Cluster Details:all control plane components running on a single node, and two worker nodes
  • README 原句:The results of this tutorial should not be viewed as production ready
材料未说明:README 未给出每个组件失败时的详细排障矩阵、日志示例或恢复步骤。;README 未说明教程是否覆盖 kubeadm 与手工流程之间的配置差异。
视情况 我有 4 台同网的 AMD64 物理机,但想把 README 列出的 Kubernetes v1.32.x、containerd v2.1.x、CNI v1.6.x 和 etcd v3.6.x 换成其他版本,我还能直接按教程执行吗?
适合读者: 希望在 4 台 AMD64 物理机上照搬教程、但计划把 Kubernetes v1.32.x、containerd v2.1.x、CNI v1.6.x 和 etcd v3.6.x 替换成其他版本的基础设施工程师

视情况,因为硬件和网络拓扑符合要求,但 README 只明确列出了特定组件版本,未承诺任意版本替换后的兼容性。

  • 4 台 AMD64 物理机连接同一网络,满足实验环境的架构和数量要求。
  • 教程明确列出 Kubernetes v1.32.x、containerd v2.1.x、CNI v1.6.x、etcd v3.6.x;这些版本构成文档的已知基线。
  • 认证配置、服务启动参数、CNI 行为和 etcd 交互可能依赖版本细节,因此不能仅根据 README 判断替换后仍可直接执行。
  • 若你的目标是复现教程,应保留列出的版本;若必须替换,就需要额外验证兼容性,而这部分不在 README 的保证范围内。
  • Cluster Details:Component versions
  • Cluster Details:kubernetes v1.32.x;containerd v2.1.x;cni v1.6.x;etcd v3.6.x
  • Labs:requires four (4) ARM64 or AMD64 based virtual or physical machines connected to the same network
材料未说明:README 未提供替代版本的兼容性矩阵或支持的版本范围。;README 未说明各组件版本之间的最低或推荐组合。
视情况 我只有 4 台同网的 ARM64 或 AMD64 机器,想给初学者安排一套从 Jumpbox 到 Smoke Test 和 Cleaning Up 的 Kubernetes 课程,这个项目适合作为课程主线吗?
适合读者: 正在为 Kubernetes 初学者设计实验课程、只有 4 台 ARM64 或 AMD64 机器,并希望课程包含证书、etcd、kubectl、Pod 网络和清理环节的培训负责人

视情况:它很适合作为核心机制实验主线,但不适合作为完全没有 Linux、网络和 Kubernetes 基础的入门课程。

  • README 的 Target Audience 是希望理解 Kubernetes fundamentals 和核心组件关系的人,课程目标高度匹配。
  • 13 个 Labs 从 Prerequisites、Jumpbox、证书、认证、etcd、控制面、工作节点,一直覆盖到远程 kubectl、Pod 网络、Smoke Test 和清理,适合组织成连续课程。
  • 4 台同网 ARM64 或 AMD64 机器满足实验前提,单控制面加两个工作节点也能保留核心组件交互。
  • 但项目明确优化的是学习深度而非自动化,README 没有说明面向零基础学员的预备课、讲义或教学节奏。
  • Target Audience:someone who wants to understand the fundamentals of Kubernetes and how the core components fit together
  • Labs:从 Prerequisites 到 Cleaning Up 的 13 个阶段
  • Labs:requires four (4) ARM64 or AMD64 based virtual or physical machines connected to the same network
  • README 原句:Kubernetes The Hard Way is optimized for learning, which means taking the long route
材料未说明:README 未说明学员需要预先掌握哪些 Linux、网络、TLS 或容器知识。;README 未提供课程时长、教学材料、练习题或讲师指导方案。

✨ 核心亮点

  • 覆盖 Kubernetes v1.32.x 集群从零引导流程
  • 逐步配置 etcd、TLS、kubectl 与 Pod 网络
  • 明确面向 Kubernetes 核心原理学习者
  • 使用 containerd v2.1.x 与 etcd v3.6.x

🔧 工程化

  • 通过 13 个 Labs 手动完成 Kubernetes 集群引导
  • 覆盖 CA、TLS、etcd、控制平面与 Worker 节点
  • 集群结构为单控制平面节点加两个 Worker

⚠️ 风险

  • README 明确说明结果不应视为生产就绪
  • 项目不面向全自动工具,强调 No scripts
  • 社区支持可能有限,README 明确提示 limited support
  • README 使用 CC BY-NC-SA 4.0,元数据标为 Apache 2.0

👥 适合谁?

  • 想理解 Kubernetes 核心组件关系的工程师
  • 需要准备 4 台 ARM64 或 AMD64 机器的学习者
  • 希望手动学习 etcd、控制平面和 Worker 的人