DEV Community

Cover image for Deploying Your First App on Kubernetes: A Beginner's Guide (Minikube & Kind)
Emmanuel Chukwudi
Emmanuel Chukwudi

Posted on

Deploying Your First App on Kubernetes: A Beginner's Guide (Minikube & Kind)

#kubernetes #devops #docker #beginners

If you've just learned the basics of Kubernetes Pods, Deployments, ReplicaSets, and Services the best next step is to actually use them. Reading about self-healing and rolling updates is one thing; watching Kubernetes recreate a deleted Pod in real time is another.

In this guide, you'll deploy a simple Node.js app on a local Kubernetes cluster. We'll cover both Minikube and Kind (Kubernetes in Docker), so you can follow along whichever tool you prefer.

By the end, you'll have:

  • A containerised Node.js app running in Kubernetes
  • 3 replicas managed by a Deployment and ReplicaSet
  • A Service exposing the app to your browser
  • Hands-on experience with self-healing and scaling

Prerequisites

Before we start, make sure you have these installed:

  • Docker required by both Minikube and Kind
  • kubectl the Kubernetes CLI
  • Either Minikube or Kind (installation covered below)

Part 1: Setting Up Your Local Cluster

You only need one of these. If you're not sure which to pick:

  • Minikube: slightly friendlier for beginners, has a built-in way to open services in the browser
  • Kind: lighter, faster, great if you already have Docker set up

Option A: Minikube

Install Minikube

macOS (Homebrew):

brew install minikube
Enter fullscreen mode Exit fullscreen mode

Linux:

curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
sudo install minikube-linux-amd64 /usr/local/bin/minikube
Enter fullscreen mode Exit fullscreen mode

Windows (via winget):

winget install Kubernetes.minikube
Enter fullscreen mode Exit fullscreen mode

Start your cluster:

minikube start
Enter fullscreen mode Exit fullscreen mode

Verify it's running:

kubectl get nodes
# NAME       STATUS   ROLES           AGE   VERSION
# minikube   Ready    control-plane   10s   v1.x.x
Enter fullscreen mode Exit fullscreen mode

Option B: Kind (Kubernetes in Docker)

Install Kind

macOS (Homebrew):

brew install kind
Enter fullscreen mode Exit fullscreen mode

Linux:

curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.22.0/kind-linux-amd64
chmod +x ./kind
sudo mv ./kind /usr/local/bin/kind
Enter fullscreen mode Exit fullscreen mode

Windows (via Chocolatey):

choco install kind
Enter fullscreen mode Exit fullscreen mode

Create your cluster:

kind create cluster --name hello-cluster
Enter fullscreen mode Exit fullscreen mode

Verify it's running:

kubectl get nodes
# NAME                         STATUS   ROLES           AGE   VERSION
# hello-cluster-control-plane  Ready    control-plane   10s   v1.x.x
Enter fullscreen mode Exit fullscreen mode

Part 2: Build the Node.js App

Create a new folder for the project:

mkdir k8s-hello && cd k8s-hello
Enter fullscreen mode Exit fullscreen mode

Create app.js:

nano/vim app.js

const http = require('http');
const os = require('os');

const server = http.createServer((req, res) => {
  res.end(`Hello from Pod: ${os.hostname()}\n`);
});

server.listen(3000, () => console.log('Running on port 3000'));
Enter fullscreen mode Exit fullscreen mode

Why os.hostname()? In Kubernetes, each Pod gets a unique hostname. When the Service load-balances traffic across multiple Pods, you'll see different hostnames on each refresh proving which Pod served you.

Create Dockerfile:

FROM node:18-alpine
WORKDIR /app
COPY app.js .
CMD ["node", "app.js"]
Enter fullscreen mode Exit fullscreen mode

Part 3: Build and Load the Docker Image

This step differs between Minikube and Kind pay attention here.

Minikube

Minikube runs its own Docker daemon inside a VM. Point your local Docker CLI at it so your build lands inside Minikube directly:

eval $(minikube docker-env)
docker build -t hello-app:v1 .
Enter fullscreen mode Exit fullscreen mode

From this point, Minikube can see the image locally without needing Docker Hub.

Kind

Kind doesn't share a Docker daemon. You build the image normally, then explicitly load it into the cluster:

docker build -t hello-app:v1 .
kind load docker-image hello-app:v1 --name hello-cluster
Enter fullscreen mode Exit fullscreen mode

Skipping kind load is the most common beginner mistake with Kind. Without it, your Pods will get stuck in ImagePullBackOff because Kind can't find the image.

Part 4: Write the Kubernetes YAML

Create deployment.yaml in your project folder:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: hello-deployment
spec:
  replicas: 3
  selector:
    matchLabels:
      app: hello
  template:
    metadata:
      labels:
        app: hello
    spec:
      containers:
        - name: hello
          image: hello-app:v1
          imagePullPolicy: Never   # use local image, don't pull from Docker Hub
          ports:
            - containerPort: 3000
---
apiVersion: v1
kind: Service
metadata:
  name: hello-service
spec:
  type: NodePort
  selector:
    app: hello          # matches the Pod label above this is how Services find Pods
  ports:
    - port: 80
      targetPort: 3000
      nodePort: 30080
Enter fullscreen mode Exit fullscreen mode

What's happening here:

  • The Deployment tells Kubernetes to keep 3 replicas of our Pod running at all times
  • It automatically creates a ReplicaSet to enforce that replica count
  • The Service uses the app: hello label selector to find all matching Pods and route traffic to them
  • imagePullPolicy: Never tells Kubernetes to use the locally available image instead of going to Docker Hub

Part 5: Deploy It 

kubectl apply -f deployment.yaml
Enter fullscreen mode Exit fullscreen mode

You should see:

deployment.apps/hello-deployment created
service/hello-service created
Enter fullscreen mode Exit fullscreen mode

Check your Pods are coming up:

kubectl get pods
Enter fullscreen mode Exit fullscreen mode

Wait until all three show Running:

NAME                                READY   STATUS    RESTARTS   AGE
hello-deployment-57c4d87bf-abc12    1/1     Running   0          15s
hello-deployment-57c4d87bf-def34    1/1     Running   0          15s
hello-deployment-57c4d87bf-ghi56    1/1     Running   0          15s
Enter fullscreen mode Exit fullscreen mode

Check your ReplicaSet and Service too:

kubectl get replicaset
kubectl get service hello-service
Enter fullscreen mode Exit fullscreen mode

Part 6: Open the App in Your Browser

Minikube 

minikube service hello-service
Enter fullscreen mode Exit fullscreen mode

Minikube opens the URL in your browser automatically.

Kind

Kind doesn't expose NodePort services directly, so use port-forwarding:

kubectl port-forward service/hello-service 8080:80
Enter fullscreen mode Exit fullscreen mode

Then open http://localhost:8080.

Hit refresh a few times. You'll see the Pod hostname change the Service is load-balancing across your 3 Pods.

Hello from Pod: hello-deployment-57c4d87bf-abc12
Hello from Pod: hello-deployment-57c4d87bf-ghi56
Hello from Pod: hello-deployment-57c4d87bf-def34
Enter fullscreen mode Exit fullscreen mode

Part 7: Experiments (The Real Learning)

Now that everything is running, try these one by one. Each one demonstrates a core Kubernetes behaviour.

1. Self-healing...delete a Pod manually 

# grab any pod name
kubectl get pods

# delete it
kubectl delete pod hello-deployment-57c4d87bf-abc12

# watch what happens
kubectl get pods -w
Enter fullscreen mode Exit fullscreen mode

Kubernetes detects the replica count dropped to 2 and immediately creates a new Pod. This is the ReplicaSet controller doing its job.

2. Scaling up 

kubectl scale deployment hello-deployment --replicas=5
kubectl get pods
Enter fullscreen mode Exit fullscreen mode

Two new Pods appear almost instantly.

3. Scaling down 

kubectl scale deployment hello-deployment --replicas=1
kubectl get pods
Enter fullscreen mode Exit fullscreen mode

Four Pods terminate gracefully, one remains.

4. Rolling update with zero downtime

Edit app.js to change the response message:

res.end(`Hello from Pod v2: ${os.hostname()}\n`);
Enter fullscreen mode Exit fullscreen mode

Build a new image:

# Minikube
eval $(minikube docker-env)
docker build -t hello-app:v2 .

# Kind
docker build -t hello-app:v2 .
kind load docker-image hello-app:v2 --name hello-cluster
Enter fullscreen mode Exit fullscreen mode

Update the Deployment:

kubectl set image deployment/hello-deployment hello=hello-app:v2
Enter fullscreen mode Exit fullscreen mode

Watch the rolling update:

kubectl rollout status deployment/hello-deployment
Enter fullscreen mode Exit fullscreen mode

Kubernetes replaces Pods one at a time, keeping the app available throughout.

5. Inspect a Pod 

kubectl describe pod <pod-name>
Enter fullscreen mode Exit fullscreen mode

This shows you the Pod's IP, which Node it's on, its labels, and a full event log — useful for debugging.

6. Roll back

If something goes wrong with an update:

kubectl rollout undo deployment/hello-deployment
Enter fullscreen mode Exit fullscreen mode

Kubernetes switches back to the previous ReplicaSet.

Part 8: Clean Up 

kubectl delete -f deployment.yaml
Enter fullscreen mode Exit fullscreen mode

Minikube:

minikube stop
Enter fullscreen mode Exit fullscreen mode

Kind:

kind delete cluster --name hello-cluster
Enter fullscreen mode Exit fullscreen mode

Note for Kind users: Kind clusters don't survive a machine restart. If you reboot and come back to this project, run kind create cluster --name hello-cluster and kind load docker-image hello-app:v1 --name hello-cluster before applying your YAML again.

What You Just Built

Here's what was happening under the hood the whole time:

Your Browser
     ↓
 [Service]             ← watched for Pods with label app: hello
     ↓
 [ReplicaSet]          ← enforced 3 running replicas at all times
  ↓     ↓     ↓
[Pod] [Pod] [Pod]      ← each ran your Node.js container
Enter fullscreen mode Exit fullscreen mode

Every concept from the Kubernetes basics maps to something you just did:

Concept What you observed
Pod The unit running your container, with a unique hostname
ReplicaSet Recreated a Pod immediately after you deleted one
Deployment Managed the rolling update and rollback
Service Load-balanced traffic across all 3 Pods using label selectors

What's Next?

Now that you have the fundamentals working, here are good next topics to explore:

  • Namespaces isolate workloads for different teams or environments
  • ConfigMaps & Secrets externalise config and credentials from your container
  • Ingress a cleaner alternative to NodePort for routing external traffic
  • Persistent Volumes attach storage that survives Pod restarts
  • Liveness & Readiness Probes teach Kubernetes when your Pod is actually healthy

If you ran into issues or have questions, drop them in the comments. The most common problems are forgetting kind load docker-image (Kind) or not running eval $(minikube docker-env) before building (Minikube).

Top comments (0)