DEV Community

ranjit sahoo
ranjit sahoo

Posted on

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

#kubernetes #beginners #devops #tutorial

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.

First, install Docker and kind (their official docs cover every OS). Then there's
one small gotcha on Linux: by default Docker needs sudo. Fix that by adding yourself to
the docker group and refreshing your session:

sudo usermod -aG docker $USER && newgrp docker
Enter fullscreen mode Exit fullscreen mode

newgrp docker reloads your group membership in the current shell, so you don't have to
log out and back in. Now create your cluster:

kind create cluster --name practice
kubectl get nodes
Enter fullscreen mode Exit fullscreen mode

If kubectl get nodes shows a node in Ready state — congratulations, you're running
Kubernetes.

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode 
kubectl apply -f namespace.yml
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Apply it, then scale it with a single command:

kubectl apply -f deployment.yml
kubectl scale deployment/nginx-deployment -n nginx --replicas=5
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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"}]'
Enter fullscreen mode Exit fullscreen mode

Confirm metrics are flowing:

kubectl top nodes
kubectl top pods -n nginx
Enter fullscreen mode Exit fullscreen mode

(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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (0)