Kubernetes The Hard Way: Learn Cluster Bootstrapping Manually
For people who want to understand Kubernetes bootstrapping by replacing automation with manual steps.
GitHub kelseyhightower/kubernetes-the-hard-way Updated 2026-09-26 Branch master Stars 50.1K Forks 15.9K
Kubernetes Cluster bootstrapping containerd ARM64/AMD64

🧭 Decision Guide

Try it if you

  • You want to understand how Kubernetes core components work together rather than obtain an automated cluster.
    The README's Target Audience and introduction say the tutorial is designed to explain fundamentals and core components, not to provide a fully automated tool.
  • You can provide four ARM64 or AMD64 virtual or physical machines connected to the same network.
    The README's Labs section requires four ARM64 or AMD64 virtual or physical machines connected to the same network.
  • You need step-by-step learning about CA, TLS, etcd, kubectl, and Pod network configuration.
    The README's Labs list Certificate Authority, Bootstrapping etcd, Configuring kubectl, and Provisioning Pod Network Routes.

Skip it if you

  • You need an existing tool to quickly create a production Kubernetes cluster.
    The README explicitly says this tutorial is not for someone looking for a fully automated tool and that its result should not be viewed as production ready.
  • You cannot provide four ARM64 or AMD64 machines connected to the same network.
    The README's Labs section lists four network-connected virtual or physical machines as a requirement.
  • You only need a running Kubernetes cluster and do not want to execute 13 manual labs.
    The README says the project is optimized for learning and lists 13 labs from Prerequisites through Cleaning Up.

Requirements

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

Watch out

  • All control-plane components run on a single node, so this is not a highly available topology.
    The README's Cluster Details explicitly says all control plane components run on a single node.
  • The tutorial result should not be used directly as a production cluster deployment.
    The README warns that the results should not be viewed as production ready.
  • Cleanup is Lab 13, and deployment includes multiple manual configuration steps.
    The README's Labs list includes Cleaning Up along with CA, TLS, etcd, and network-route steps.
  • The project metadata and README name different licenses, so the licensing boundary needs verification.
    Metadata lists Apache License 2.0, while the README Copyright section lists Creative Commons Attribution-NonCommercial-ShareAlike 4.0.

Not stated in the 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 未说明四台机器之间所需的具体端口和网络配置。
  • 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; README 未说明社区支持的具体渠道、响应时间或故障处理范围。

💡 Deep Analysis

6
No I plan to use Kubernetes v1.32.x with containerd v2.1.x in production on a topology with one control plane and two worker nodes. Can this project serve as my deployment solution?
For: A DevOps engineer planning to deliver Kubernetes v1.32.x with containerd v2.1.x in production, using one control plane and two worker nodes

No, it is not suitable because the README explicitly positions it as a learning tutorial and warns that the result is not production ready.

  • Cluster Details describes only one control-plane node and two worker nodes, so the control plane has no redundancy for high availability.
  • The labs focus on manually bootstrapping certificates, configuration files, etcd, the control plane, workers, and Pod network routes, rather than production concerns such as upgrades, backups, monitoring, or security operations.
  • The README says it is not for users looking for a fully automated tool, and manual execution increases the risk of configuration omissions and input errors.
  • It can teach you how Kubernetes native components fit together, but it should not replace a production deployment design.
  • README quote: 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 quote: This guide is not for someone looking for a fully automated tool
  • Labs: Cleaning Up
  • Project insight: it does not cover high availability, backup and recovery, monitoring, upgrades, or security hardening
Not stated in the README:The README does not define production SLAs, capacity requirements, backup strategy, upgrade path, monitoring design, or security baseline.;It does not explain how to recover etcd data and API-server service after a single control-plane failure.
Yes I have four ARM64 virtual machines connected to the same network and want to learn cluster bootstrapping with Kubernetes v1.32.x, containerd v2.1.x, CNI v1.6.x, and etcd v3.6.x. Is this project suitable for me?
For: A learner studying Kubernetes fundamentals with four ARM64 or AMD64 virtual machines on the same network, using Kubernetes v1.32.x, containerd v2.1.x, CNI v1.6.x, and etcd v3.6.x

Yes, it is suitable because it is specifically a hands-on tutorial for understanding Kubernetes internals rather than quickly installing a cluster.

  • The README states that the tutorial is optimized for learning and for understanding every task required to bootstrap Kubernetes.
  • Your four ARM64 virtual machines satisfy the stated environment requirement. The topology includes one control-plane node and two worker nodes, with a Jumpbox used during the labs.
  • The labs cover the CA and TLS certificates, authentication configuration, data-encryption keys, etcd, the control plane, workers, kubectl, Pod network routes, and a smoke test.
  • It is explicitly not production-ready and requires substantial manual work, so it is not suitable if your only goal is to obtain a working cluster quickly.
  • Target Audience: understand Kubernetes fundamentals and how the core components fit together
  • Cluster Details: all control plane components run on a single node, with 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 quote: This guide is not for someone looking for a fully automated tool
Not stated in the README:The README does not specify the required CPU, memory, disk capacity, or operating-system versions for the four machines.;It does not describe compatibility differences between ARM64 and AMD64 for the lab commands or component packages.
Yes I want to understand certificates, etcd, the control plane, and Pod networking manually with Kubernetes v1.32.x, then convert the process into automated deployment. Is this project a suitable foundation for that automation design?
For: A DevOps engineer who wants to turn the manual Kubernetes bootstrap process into automation, starting from four networked machines, one control plane, two workers, and Kubernetes v1.32.x

Yes, but it is suitable as a reference baseline for automation design, not as an automation tool that can be used directly.

  • The README explicitly says it is not a fully automated tool and focuses on understanding every bootstrap task, which helps define automation boundaries before implementation.
  • The labs are already divided into stages covering prerequisites, the Jumpbox, compute resources, PKI, authentication, encryption keys, etcd, the control plane, workers, kubectl, Pod networking, and validation; these stages can map to modules or pipeline phases.
  • The documented baseline fixes Kubernetes v1.32.x, containerd v2.1.x, CNI v1.6.x, and etcd v3.6.x, together with one control plane and two workers, making comparison easier.
  • However, the README provides no scripts, APIs, or idempotency design, so the automation implementation still has to be built independently.
  • README quote: This guide is not for someone looking for a fully automated tool
  • README quote: optimized for learning, which means taking the long route
  • Labs: 13 staged labs from Prerequisites through 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
Not stated in the README:The README does not explain how to translate the stages into Ansible, Terraform, or other automation modules.;It does not define idempotency, failure-retry, or state-management requirements for an automated workflow.
Yes I have used kubeadm, but now need to understand CA, TLS, etcd, and control-plane dependencies manually in a topology with one control plane and two workers. Can this tutorial meet my troubleshooting-learning goals?
For: A platform engineer who needs to understand TLS, etcd, and Kubernetes control-plane dependencies while moving away from kubeadm or cloud automation, using a single control plane and two workers

Yes, it is suitable because it separates the trust chain, authentication, and component startup order that automated installers usually hide.

  • The labs proceed through CA and TLS generation, Kubernetes configuration files, data-encryption keys, etcd, the control plane, and the worker nodes, making the dependency chain explicit.
  • The README says the goal is to understand every task required to bootstrap Kubernetes rather than automate delivery, which matches a learning objective centered on kubeadm’s hidden behavior.
  • One control-plane node and two workers are enough to observe the core component interactions, but not to study control-plane high availability or large-scale failure handling.
  • The tutorial explicitly says its result should not be viewed as production ready, so it fits troubleshooting practice rather than serving as a production cluster template.
  • README quote: 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 quote: The results of this tutorial should not be viewed as production ready
Not stated in the README:The README does not provide a detailed troubleshooting matrix, log examples, or recovery procedures for each component failure.;It does not explain configuration differences between kubeadm and the manual process.
It depends I have four AMD64 physical machines on the same network, but I want to replace the README’s Kubernetes v1.32.x, containerd v2.1.x, CNI v1.6.x, and etcd v3.6.x with other versions. Can I follow the tutorial directly?
For: An infrastructure engineer with four AMD64 physical machines who wants to follow the tutorial but replace Kubernetes v1.32.x, containerd v2.1.x, CNI v1.6.x, and etcd v3.6.x with other versions

It depends. Your hardware and network topology match the stated requirements, but the README lists specific component versions and does not promise compatibility with arbitrary replacements.

  • Four AMD64 physical machines connected to the same network satisfy the stated architecture, machine-count, and network requirements.
  • The tutorial explicitly lists Kubernetes v1.32.x, containerd v2.1.x, CNI v1.6.x, and etcd v3.6.x as its component versions; these are the documented baseline.
  • Authentication configuration, service startup arguments, CNI behavior, and etcd interactions can depend on version details, so the README alone cannot establish that substituted versions will work unchanged.
  • If your goal is to reproduce the tutorial, keep the listed versions. If replacement is mandatory, compatibility validation is required, but that validation is outside the README’s stated guarantees.
  • 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
Not stated in the README:The README does not provide a compatibility matrix or supported ranges for alternative versions.;It does not specify the minimum or recommended version combinations among the components.
It depends I have only four ARM64 or AMD64 machines on the same network and want to build a beginner course from the Jumpbox through Smoke Test and Cleaning Up. Is this project suitable as the course backbone?
For: A training lead designing a Kubernetes course for beginners with four ARM64 or AMD64 machines, requiring certificates, etcd, kubectl, Pod networking, and cleanup labs

It depends. The project is well suited as the backbone for a hands-on course about Kubernetes internals, but not as a complete introduction for learners with no Linux, networking, or Kubernetes background.

  • The README’s Target Audience is people who want to understand Kubernetes fundamentals and how its core components fit together, which matches an internals-focused course.
  • Its 13 labs run from Prerequisites and the Jumpbox through certificates, authentication, etcd, the control plane, workers, remote kubectl, Pod network routes, Smoke Test, and cleanup, providing a coherent course sequence.
  • Four ARM64 or AMD64 machines on the same network satisfy the lab prerequisite, while one control plane and two workers preserve the key component interactions.
  • However, the project is optimized for learning through a long manual route, and the README does not provide beginner prerequisites, teaching materials, or pacing guidance.
  • Target Audience: someone who wants to understand the fundamentals of Kubernetes and how the core components fit together
  • Labs: 13 stages from Prerequisites through Cleaning Up
  • Labs: requires four (4) ARM64 or AMD64 based virtual or physical machines connected to the same network
  • README quote: Kubernetes The Hard Way is optimized for learning, which means taking the long route
Not stated in the README:The README does not state which Linux, networking, TLS, or container skills learners should have beforehand.;It does not provide course duration, teaching materials, exercises, or instructor guidance.

✨ Highlights

  • Covers bootstrapping a Kubernetes v1.32.x cluster from scratch
  • Walks through etcd, TLS, kubectl, and Pod networking
  • Explicitly targets learners of Kubernetes fundamentals
  • Uses containerd v2.1.x and etcd v3.6.x

🔧 Engineering

  • Uses 13 labs to manually bootstrap a Kubernetes cluster
  • Covers CA, TLS, etcd, control plane, and worker nodes
  • Uses one control-plane node and two worker nodes

⚠️ Risks

  • The README explicitly says the result should not be viewed as production ready
  • The project is not an automated tool and emphasizes “No scripts”
  • Community support may be limited, as stated in the README
  • The README uses CC BY-NC-SA 4.0 while metadata lists Apache 2.0

👥 For who?

  • Engineers who want to understand Kubernetes core component relationships
  • Learners able to provide four ARM64 or AMD64 machines
  • People who want hands-on learning with etcd, control plane, and workers