Open-source project
kelseyhightower/kubernetes-the-hard-way avatar
kelseyhightower/kubernetes-the-hard-way

Kubernetes The Hard Way: A Manual Bootstrap Tutorial for Learning Core Components

GitHub describes it as Bootstrap Kubernetes the hard way. No scripts.. The metadata lists the Apache-2.0 license. This article stays within the project description and details documented in the GitHub repository README.

50,684 stars15,963 forksUnknownApache-2.0

At a glance

What is it?
This tutorial builds a single-control-plane, two-worker Kubernetes cluster by hand, with no scripts. It is a learning path, not a production deployment guide.
Who is it for?
Adopt this tutorial if you are an engineer or student who wants to understand Kubernetes internals by performing every step manually. Do not use it for production clusters, as the README explicitly states the results are not production ready and may receive limited community support.
Can I use it commercially?
Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Probably not. The repository last received commits 19 months ago, on April 10, 2025.
What is it written in?
GitHub does not report a main language for this repository.

Answers come from the project's GitHub data, last synced on November 13, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • kelseyhightower/kubernetes-the-hard-way50,684 ★ · +1,241
Star history
Repository2026-08-132026-11-13
kelseyhightower/kubernetes-the-hard-way49.4k50.7k

1,241 Stars in the last 92 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What the Tutorial Actually Teaches

Kubernetes The Hard Way is a written tutorial, not a tool. It walks through bootstrapping a basic Kubernetes cluster with all control plane components on a single node and two worker nodes. The stated purpose is learning, not automation. The README is explicit: this guide is not for someone looking for a fully automated tool to bring up a cluster. It optimizes for understanding each task required to bootstrap a Kubernetes cluster. The target audience is someone who wants to grasp the fundamentals and how the core components fit together. If you already know how to run kubectl but cannot explain what etcd does or why the API server needs a certificate, this tutorial fills that gap. It forces you to touch every piece, from the CA to the pod network routes.

The Manual Mechanism: No Scripts, Every Step Typed

The core mechanism is the absence of abstraction. Instead of running kubeadm or a cloud provisioner, you execute each command yourself. The tutorial is divided into thirteen labs, starting with prerequisites and ending with cleanup. You set up a jumpbox, provision compute resources, generate a CA and TLS certificates, create Kubernetes configuration files, and produce a data encryption key. Then you bootstrap etcd, the control plane, and the worker nodes. After that, you configure kubectl for remote access, provision pod network routes, and run a smoke test. The tutorial uses no scripts; the repository holds the lab docs plus supporting files such as `ca.conf`, `configs/`, `units/` and the download lists. This means you run every command yourself, from certificate signing to kubeconfig creation. The learning comes from seeing how the pieces connect: the CA signs certificates for each component, the encryption config protects secrets at rest, and the pod network routes connect worker nodes.

Getting Started: Four Machines and a Network

The tutorial requires four virtual or physical machines, either ARM64 or AMD64, connected to the same network. The README lists the component versions: Kubernetes v1.32.x, containerd v2.1.x, CNI plugins v1.6.x, and etcd v3.6.x. You start with the prerequisites lab, then set up a jumpbox. From there, you provision compute resources, which likely involves creating three nodes: one for the control plane and two for workers. The exact commands are in the docs, but the README gives no shortcuts. You must read each lab and follow along. The lack of scripts means you cannot copy-paste a single file to automate the process. Every command is typed or pasted individually, which is the point. But it also means a single typo in a certificate name can break the cluster, and you have to debug it yourself.

A Real Limitation: Not Production Ready, Limited Support

The README contains a warning that the results of this tutorial should not be viewed as production ready, and may receive limited support from the community. This is a genuine limitation, not a disclaimer. The cluster design is minimal: a single control plane node means no high availability for the API server or etcd. The tutorial does not cover upgrades, backups, or scaling. If a worker node fails, there is no automated recovery. The tutorial's goal is education, so it omits operational concerns. For someone who needs a working cluster for a real workload, this is the wrong tool. The warning also implies that if you run into issues, you cannot expect the maintainer or community to help you fix a broken cluster. You are on your own after the smoke test. This is a deliberate trade-off, but you should know it before starting.

Alternative: kubeadm for Automated Bootstrap

The obvious alternative is kubeadm, the official Kubernetes tool for bootstrapping a cluster. kubeadm automates the steps that Kubernetes The Hard Way does manually: it generates certificates, creates kubeconfig files, and starts the control plane components as static pods. The difference in approach is fundamental. With kubeadm, you run kubeadm init on the control plane node and kubeadm join on workers, and the cluster comes up. You do not see the individual components or the TLS handshakes. Kubernetes The Hard Way removes that automation so you can see each piece. If your goal is to stand up a cluster quickly for development or production, kubeadm is the better choice. If your goal is to understand what kubeadm does under the hood, this tutorial is the better path. The two serve different purposes, and the README acknowledges this by saying the tutorial is not for those seeking automation.

Maintenance and Upgrade Cost: Manual and Version-Specific

The tutorial is tied to specific component versions: Kubernetes v1.32.x, containerd v2.1.x, CNI v1.6.x, and etcd v3.6.x. This means the commands and configuration files in the docs are valid for those versions. If you try to use a newer Kubernetes release, the steps may not work. The repository is not archived, but the last push was on April 10, 2025, and the repository has no GitHub releases. That suggests the tutorial is updated infrequently. The maintenance cost for you is high: you must manually upgrade each component if you want to stay current. There is no upgrade path in the tutorial. The cleanup lab suggests you can tear down the cluster, but there is no mention of updating an existing one. The license is Apache-2.0 for the repository itself, which permits reuse with attribution. The README also mentions a Creative Commons license for the work, so check both if you plan to redistribute the content.

Who Should Skip This Tutorial

This tutorial is wrong for you if you need a production cluster, if you are on a deadline, or if you prefer hands-off automation. The README is clear that the results are not production ready. If you are a developer who just wants to run Kubernetes for local testing, tools like kind or minikube are faster and require fewer machines. If you are a platform engineer building a real cluster, kubeadm or a managed service is more appropriate. The tutorial also assumes you have four machines available and are comfortable with the command line. If you are new to Linux or networking, the certificate and route labs will be challenging. The value of this tutorial is in the deliberate struggle. If you do not have time for that struggle, or if you need a cluster that works, skip it. If you do have time and curiosity, it offers a rare, script-free view of Kubernetes internals.

Editorial conclusion

Adopt this tutorial if you are an engineer or student who wants to understand Kubernetes internals by performing every step manually. Do not use it for production clusters, as the README explicitly states the results are not production ready and may receive limited community support. Before starting, verify you have four ARM64 or AMD64 machines on the same network and that you have time to follow every lab. The tutorial is a deliberate, slow path to comprehension, not a tool for cluster deployment.

Frequently asked questions

Is Kubernetes the hard way worth it?

It is built for learning rather than for standing up a cluster: the README says the guide is not for someone looking for a fully automated tool, that the target audience is someone who wants to understand the fundamentals and how the core components fit together, and that the results are not production ready. What you get is thirteen labs with no scripts, from prerequisites through cleanup.

install kubernetes the hard way

There is nothing to install from this repository. It is a set of labs in `docs/`, and the README requires four ARM64 or AMD64 based virtual or physical machines connected to the same network, with all control plane components on one node and two worker nodes, using kubernetes v1.32.x, containerd v2.1.x, cni v1.6.x and etcd v3.6.x.

what is kubernetes the hard way

A tutorial that bootstraps a Kubernetes cluster by hand, with no scripts, so that every task required to build a cluster is visible. The labs cover the CA and TLS certificates, authentication configuration files, the data encryption key, the etcd cluster, the control plane, the worker nodes, remote kubectl access, pod network routes, a smoke test and cleanup.

Official sources

  1. Official README
  2. Project repository
  3. README
  4. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/kelseyhightower-kubernetes-the-hard-way.svg)](https://hysenlabs.com/projects/kelseyhightower-kubernetes-the-hard-way)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/kelseyhightower-kubernetes-the-hard-way.svg)](https://hysenlabs.com/projects/kelseyhightower-kubernetes-the-hard-way)

Was this useful?