Kubernetes from scratch with k3s

Most people meet Kubernetes the hard way: a corporate cluster someone else built, a wall of YAML, and a dozen new words that all sound interchangeable. You learn to copy-paste commands without ever forming a mental model of what is actually happening. This series takes the opposite route. You build a real cluster yourself, on your own machines, and learn each piece the moment you need it — nothing abstract, nothing you cannot poke at with kubectl.

level:Beginner

ℹ️ How to read this series — the early parts are read-along concepts; from part 3 on they're hands-on against a real k3s cluster you build. Each part says which at the top.

What this series is

This is a guided path from "I run a few containers" to "I run a small Kubernetes cluster and deployed a real app on it." It is nine parts plus this hub. Each part introduces one idea, explains what it is and why it exists before showing how to use it, and links forward to the next.

The cluster you build runs on k3s — a fully compliant Kubernetes distribution packaged as a single binary under 100 MB. That word compliant matters: k3s is not a toy or a simplified clone. It is real, CNCF-certified Kubernetes with the operational weight stripped out, which makes it the ideal thing to learn on. What you learn here transfers directly to a managed cluster at work.

flowchart TD
  A["You: run a few containers"] --> B["Part 1-2<br/><i>the model + the cluster</i>"]
  B --> C["Part 3<br/><i>stand up k3s</i>"]
  C --> D["Part 4-6<br/><i>pods, deployments, services</i>"]
  D --> E["Part 7-8<br/><i>ingress, config, storage</i>"]
  E --> F["Part 9<br/><i>a real app, end to end</i>"]

The series moves from mental model, to a running cluster, to the objects you deploy on it, to a real application.

Why learn Kubernetes on k3s

A normal Kubernetes install is genuinely heavy. The control plane is not one program — it is an API server, a scheduler, a controller manager, and an etcd datastore, plus an agent and a runtime and a networking layer on every node. Installing, securing, and upgrading all of that is a real job, and it gets between a beginner and the concepts worth learning.

k3s removes that friction without removing the concepts. One binary becomes either the control plane or a worker depending on a couple of environment variables, and it bundles containerd, the Flannel network plugin, CoreDNS, a Traefik ingress controller, a service load balancer, and local-path storage, with SQLite as the default datastore instead of a standalone etcd cluster. The result is that you spend your time learning Kubernetes rather than fighting its installer.

There is a second reason: a k3s cluster is useful. The same cluster you learn on can host your homelab — the services you actually run day to day. This is not a throwaway sandbox. My own site runs on k3s, so everything in this series is something I live with rather than something I read about.

💡 Tip You do not need three servers. The standard homelab approach is three small virtual machines on one physical box. From Docker to k3s covers how to carve those VMs out with Proxmox — that post is the natural lead-in to this series.

The Docker Compose to Kubernetes leap

If you have used Docker Compose, you already understand more of Kubernetes than you think. Compose lets you declare a set of services in a YAML file and bring them up together on one machine. Kubernetes does the same thing — declare what you want in YAML — but across a cluster of machines, and it never stops working to keep reality matching your declaration.

The vocabulary is heavier, but most Compose concepts map cleanly onto a Kubernetes object. That mapping is the bridge this series walks you across.

flowchart LR
  A["Compose service<br/><i>image + replicas</i>"] -->|"becomes"| B["Deployment"]
  C["service-name DNS<br/><i>between containers</i>"] -->|"becomes"| D["Service"]
  E["reverse-proxy rules<br/><i>host + path</i>"] -->|"becomes"| F["Ingress"]
  G["volumes:"] -->|"becomes"| H["PersistentVolumeClaim"]

The Compose mental model transfers almost one-to-one — the names change and the system spans many machines, but the idea of "declare it, the platform runs it" is the same.

The real jump is not the vocabulary. It is the shift from one host to a cluster, and from imperative commands to declarative state that a control loop continuously enforces. Part one unpacks exactly that.

ℹ️ Note This series assumes you are comfortable with containers and Docker Compose. If you are not there yet, Docker and Compose on Debian is the prerequisite — it teaches the container model this series builds on.

The reading order

Read the parts in order. Each one assumes the one before it.

1. What Kubernetes actually is — orchestration, the desired-state control loop, and when you actually need any of this.
2. Clusters, the control plane, and nodes — the machines and the brain that coordinates them.
3. Set up a k3s cluster — install k3s, join a node, and run your first kubectl get nodes.
4. Pods explained — the smallest thing Kubernetes schedules, and why it is not just "a container."
5. Deployments and self-healing — declaring replicas, rolling updates, and how the cluster repairs itself.
6. Services and networking — stable addresses for ephemeral pods, and how traffic finds them.
7. Ingress with Traefik — exposing services to the outside world by hostname and path.
8. Config, secrets, and storage — ConfigMaps, Secrets, and persistent volumes for stateful data.
9. Deploy a real app on k3s — putting every piece together to run something you actually use.

⚠️ Warning Kubernetes is a real step up in complexity, and most homelabs never need it. If you have one well-backed-up Docker host that works, you may not have a problem this solves. Learn it because you are curious or because work demands it — not because the diagrams look impressive. From Docker to k3s makes the honest case for when the jump is worth it.

A short close

Start with part one for the mental model, or jump to part three if you want a cluster running first and the theory second. Either way, the goal is the same: by the end you will have built real Kubernetes, understood each piece as you added it, and have a cluster you can keep. If you want to see where that ends up, my own /server stack is exactly this, running for real.