# Kubernetes for Absolute Beginners: Build Your First Local Cluster with kind

A hands-on, copy-paste guide to going from a bare Linux machine to running, scaling, and exposing real workloads on Kubernetes — no cloud account required.

---

When I started learning Kubernetes, every tutorial either assumed I already had a cloud
cluster or buried the basics under a mountain of YAML. So I did what most of us do: I
opened a terminal, broke things, fixed them, and wrote down what actually worked.

This post is that notebook, cleaned up. By the end you'll have a real Kubernetes cluster
running on your own laptop with kind, and you'll understand the core building blocks —
Pods, Deployments, Services, Ingress, storage, autoscaling — not as abstract diagrams, but
as commands you can run right now.

Let's get into it.

---

Step 1: Spin Up a Cluster on Your Own Machine

You don't need AWS or GCP to learn Kubernetes. kind ("Kubernetes IN Docker") runs an
entire cluster inside Docker containers on your machine. It's fast, free, and disposable.

You'll need three tools, and it's worth calling out that they're separate: Docker (kind
runs the cluster inside it), kind itself, and kubectl — the CLI you actually drive
the cluster with. kind does not install kubectl for you, which trips up a lot of
beginners. Grab all three from their official docs; kubectl is a one-liner on Linux:

curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl

On Linux, Docker needs sudo by default. Add yourself to the docker group and refresh
your session so you don't have to keep typing it:

sudo usermod -aG docker $USER && newgrp docker

Now — and this is the part most quick-start guides skip — don't just run
kind create cluster. A bare cluster has no way to accept web traffic on ports 80/443,
and later when you add an Ingress its controller will sit there Pending forever because no
node is marked as "ingress-ready". You fix both up front with a tiny config file. Save this
as kind-config.yml:

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
  kubeadmConfigPatches:
  - |
    kind: InitConfiguration
    nodeRegistration:
      kubeletExtraArgs:
        node-labels: "ingress-ready=true"
  extraPortMappings:
  - containerPort: 80
    hostPort: 80
    protocol: TCP
  - containerPort: 443
    hostPort: 443
    protocol: TCP

The extraPortMappings wire your laptop's localhost:80/443 straight into the cluster, and
the ingress-ready=true label gives the ingress controller a node to land on. Create the
cluster with that config:

kind create cluster --name practice --config kind-config.yml
kubectl get nodes

A node in Ready state? You're officially running Kubernetes. Two add-ons round out the
setup — they aren't bundled with kind, so install them now and forget about them:

# Ingress controller (kind-flavored build) — powers the /apache and /nginx routing later
kubectl apply -f https://kind.sigs.k8s.io/examples/ingress/deploy-ingress-nginx.yaml

# metrics-server — required before any autoscaling or `kubectl top` will work
kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml

(One quirk: on kind, metrics-server usually needs a small --kubelet-insecure-tls tweak to
go healthy — we'll cover that when we reach autoscaling.)

---

Step 2: Namespaces — Your Cluster's Folders

Before deploying anything, it helps to create a namespace: a logical partition that
keeps your resources tidy and isolated.

kubectl create namespace nginx

You can also do it declaratively in a YAML file — and honestly, the declarative approach
is what you should get comfortable with, because it's how real teams manage clusters:

apiVersion: v1
kind: Namespace
metadata:
  name: nginx

kubectl apply -f namespace.yml

From here on, almost every command takes a -n <namespace> flag to say where it should
act.

---

Step 3: Pods — The Smallest Unit That Runs

A Pod is the smallest thing Kubernetes runs: one (or a few tightly-coupled) containers
sharing a network and storage. You can launch one directly:

kubectl run nginx --image=nginx -n nginx

But here's the thing nobody tells beginners early enough: you almost never create bare
Pods in real life. If that pod dies, nothing brings it back. Instead, you let a higher-
level controller — a Deployment — manage Pods for you so they self-heal and scale.

---

Step 4: Deployments, and Their Cousins

This is where Kubernetes gets powerful. A Deployment doesn't just run your Pods — it
keeps the desired number alive, replaces crashed ones, and rolls out new versions safely.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  namespace: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:latest
        ports:
        - containerPort: 80

Apply it, then scale it with a single command:

kubectl apply -f deployment.yml
kubectl scale deployment/nginx-deployment -n nginx --replicas=5

Once you understand Deployments, three siblings fall into place:

• ReplicaSet — keeps N identical pods running. Its YAML is almost identical to a Deployment (just a different kind), but it can't do rollouts or rollbacks. In practice a Deployment manages ReplicaSets for you, so you rarely write one yourself.
• DaemonSet — guarantees one pod on every node in the cluster. Perfect for node-level agents like log shippers or monitoring.
• StatefulSet — for stateful apps like databases. When a pod crashes, it comes back with the same name and the same storage, unlike a Deployment where replacements get random names. This stable identity is exactly what databases need.

---

Step 5: Updating Without Downtime (and Undoing Mistakes)

Two concepts often get confused here, so let's be precise — because they're different.

Rolling update is the default Deployment strategy. When you change the image, new pods
start before old ones are removed, so users never see downtime:

kubectl set image deployment/nginx-deployment -n nginx nginx=nginx:1.27.3
kubectl rollout status deployment/nginx-deployment -n nginx

Rollback is the safety net for when an update goes wrong. Kubernetes keeps a history,
so you can revert in seconds:

kubectl rollout history deployment/nginx-deployment -n nginx
kubectl rollout undo deployment/nginx-deployment -n nginx

So: rolling update = how new versions ship smoothly. Rollback = how you undo a bad
one. Don't mix them up — I did at first.

---

Step 6: Making Pods Reachable — Services & Ingress

Pods are ephemeral and get new IPs constantly, so you never talk to them directly. A
Service gives a stable address in front of a group of pods (selected by label):

apiVersion: v1
kind: Service
metadata:
  name: nginx-service
  namespace: nginx
spec:
  selector:
    app: nginx
  ports:
  - port: 80
    targetPort: 80
  type: ClusterIP

To poke at it from your laptop during development, port-forward it:

kubectl port-forward service/nginx-service -n nginx 80:80 --address=0.0.0.0

For real HTTP routing — exposing multiple apps under one entry point, routing by path like
/apache and /nginx — you graduate to an Ingress:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: web-ingress
  namespace: apache
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$2
    nginx.ingress.kubernetes.io/use-regex: "true"
spec:
  ingressClassName: nginx
  rules:
  - host: practice.local
    http:
      paths:
      - path: /apache(/|$)(.*)
        pathType: ImplementationSpecific
        backend:
          service:
            name: apache-service
            port:
              number: 80

Three things tripped me up with Ingress, so learn from my mistakes:

1. An Ingress is namespaced — it can only route to Services in its own namespace.
2. It does nothing until you install an ingress controller (like ingress-nginx).
3. Path prefixes usually need a rewrite annotation, or your backend (which serves at /) will return 404 for /apache.

---

Step 7: Storage That Survives a Restart

Containers are throwaway — kill the pod and the data is gone. For anything that must
persist (think databases), Kubernetes splits storage into two pieces:

• A PersistentVolume (PV) — the actual storage in the cluster. It's cluster-scoped, so it has no namespace.
• A PersistentVolumeClaim (PVC) — a pod's request for storage. It's namespaced, and it binds to a PV that matches its size, access mode, and storage class.

Your pod then mounts the claim like any other volume:

volumeMounts:
- name: data
  mountPath: /var/lib/mysql
volumes:
- name: data
  persistentVolumeClaim:
    claimName: mysql-pvc

Now your database keeps its data even when the pod is rescheduled.

---

Step 8: Configuration & Secrets

Hardcoding config into images is an anti-pattern. Kubernetes gives you two tools:

• ConfigMap — non-sensitive key/value config, injected as env vars or mounted files.
• Secret — sensitive values (passwords, API keys), referenced via secretKeyRef.

env:
- name: MYSQL_ROOT_PASSWORD
  valueFrom:
    secretKeyRef:
      name: mysql-secret
      key: mysql-root-password

One important warning: a Secret is only base64-encoded, not encrypted. Never commit
real credentials to Git.

---

Step 9: Autoscaling — Let the Cluster React to Load

Here's the feature that makes Kubernetes feel like magic. A Horizontal Pod Autoscaler
(HPA) watches a metric (usually CPU) and adds or removes pods automatically between a
min and max you define.

But HPA can't read CPU out of the box on a fresh kind cluster — you first need
metrics-server:

kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml

On kind specifically, metrics-server often gets stuck because it can't verify the
kubelet's TLS cert. The local-only fix:

kubectl patch deployment metrics-server -n kube-system --type=json \
  -p='[{"op":"add","path":"/spec/template/spec/containers/0/args/-","value":"--kubelet-insecure-tls"}]'

Confirm metrics are flowing:

kubectl top nodes
kubectl top pods -n nginx

(Note: kubectl top nodes is cluster-wide, so no -n flag — that one caught me.)

Now define the HPA. It needs your Deployment to declare CPU requests, then it targets
a utilization percentage and scales between min and max replicas — and you can even tune
how quickly it reacts:

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: apache-hpa
  namespace: apache
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: apache-deployment
  minReplicas: 1
  maxReplicas: 5
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 50

The Other Direction: Vertical Scaling with VPA

HPA answers "how many pods?" But there's a second question hiding in plain sight: "how
big should each pod be?" That's the job of the Vertical Pod Autoscaler (VPA). Instead
of adding replicas, it right-sizes a pod's CPU and memory based on what it actually uses —
so you stop guessing at requests: values and stop paying for headroom you never touch.

VPA isn't bundled with the cluster like HPA, so you install it from the official autoscaler
repository:

git clone https://github.com/kubernetes/autoscaler.git
cd autoscaler/vertical-pod-autoscaler
./hack/vpa-up.sh

Then point it at a Deployment and choose how bold it should be with updateMode:

apiVersion: autoscaling.k8s.io/v1
kind: VerticalPodAutoscaler
metadata:
  name: apache-vpa
  namespace: apache
spec:
  targetRef:
    apiVersion: "apps/v1"
    kind: Deployment
    name: apache-deployment
  updatePolicy:
    updateMode: "Auto"

"Off" just hands you recommendations to eyeball (kubectl describe vpa apache-vpa -n
apache), "Initial" applies them only to brand-new pods, and "Auto" actively evicts and
recreates pods to resize them on the fly.

One hard-earned warning: never aim HPA and VPA at the same metric on the same workload.
If both manage CPU, they fight — VPA resizing pods while HPA changes their count, each one
reacting to the other's moves. Pick one for CPU and you'll save yourself a very confusing
afternoon.

While we're on the topic of resources: every container should declare requests
(guaranteed) and limits (ceiling) for CPU and memory. And if you share a cluster
across teams, a ResourceQuota caps total consumption per namespace.

---

Step 10: The Debugging Commands You'll Use Every Day

When something won't start, these four commands answer 90% of "why?":

# Get a shell inside a running pod
kubectl exec -it nginx-pod -n nginx -- bash      # use -- sh if bash isn't installed

# See events and the real reason a pod is unhealthy
kubectl describe pod/nginx-pod -n nginx

# Read the logs (-f to follow, --previous for a crashed container)
kubectl logs nginx-pod -n nginx -f

# See everything in a namespace at once
kubectl get all -n nginx

A small but real detail: the separator before the command is -- (two hyphens), and the
shell is bash or sh. Copying en-dashes from notes will silently break the command.

---

Wrapping Up

If you followed along, you went from a bare machine to a running cluster where you can
deploy apps, expose them over HTTP, give them persistent storage, secure their config, and
let them scale themselves under load. That's genuinely most of what you do with Kubernetes
day to day.

My advice: don't just read this — kind create cluster and run every command. Break a
Deployment, watch it self-heal. Crank the HPA and hammer it with load. The concepts only
click once you've watched the cluster react in real time.

If this helped, I'd love to hear what you build next. Happy shipping! 🚀

---

Found this useful? Follow for more hands-on DevOps and Kubernetes write-ups.