k8s-playground

A beginner-friendly Kubernetes learning playground built with Node.js, Express, Docker, Docker Hub, Minikube, and Kubernetes.

This project contains a small Express API that is packaged into a Docker image and deployed to a local Kubernetes cluster. It is meant for learning the full flow:

1. Write a simple web API.
2. Containerize it with Docker.
3. Push the image to Docker Hub.
4. Run it on Kubernetes with Minikube.
5. Observe Deployments, Pods, ReplicaSets, Services, probes, scaling, and self-healing.

Quick Start

Use this shortest working flow when you already have Docker Desktop, Minikube, and kubectl installed.

minikube start --driver=docker
minikube status
kubectl get nodes
kubectl apply -f k8s/
kubectl get pods -w
kubectl port-forward service/k8s-playground-api-service 3000:3000

What these commands do:

• minikube start --driver=docker starts a local Kubernetes cluster using Docker Desktop.
• minikube status checks that the cluster is running.
• kubectl get nodes checks that kubectl can talk to Minikube.
• kubectl apply -f k8s/ creates the Deployment and Service.
• kubectl get pods -w watches the Pods until they are running.
• kubectl port-forward service/k8s-playground-api-service 3000:3000 exposes the Service on your local machine.

When the Pods are running, keep the port-forward terminal open and open:

http://localhost:3000

Press Ctrl+C to stop watching Pods or to stop port-forwarding.

Windows / Docker Desktop Minikube Fallback Command

The normal Minikube start command for this project is:

minikube start --driver=docker

If Minikube gets stuck downloading images, has preload issues, or runs into cache/network problems on Windows with Docker Desktop, this fallback command worked successfully in this setup:

minikube start --driver=docker --kubernetes-version=v1.33.3 --preload=false --cache-images=false --memory=6144 --cpus=4 --base-image=docker.io/kicbase/stable:v0.0.48

What the flags mean:

• --kubernetes-version=v1.33.3 uses a specific Kubernetes version instead of letting Minikube choose one automatically.
• --preload=false avoids the large Minikube preload download.
• --cache-images=false avoids problems caused by Minikube's local image cache.
• --memory=6144 gives the Minikube cluster about 6 GB of memory.
• --cpus=4 gives the Minikube cluster four CPU cores.
• --base-image=docker.io/kicbase/stable:v0.0.48 uses the fallback Minikube base image that Docker can pull.

If Docker can pull the fallback base image, it can help confirm that Docker networking is working:

docker pull docker.io/kicbase/stable:v0.0.48

Docker Desktop vs Minikube

This project uses Minikube with the Docker driver.

That means Docker Desktop runs the container runtime for Minikube. In Docker Desktop, you may see a container named:

minikube

That container is the local Kubernetes node.

Docker Desktop also has its own Kubernetes feature in the Docker Desktop settings. That is separate from Minikube. If you are following this README, focus on the Minikube cluster and make sure your kubectl context is set to Minikube.

Check the current context:

kubectl config current-context

If needed, switch to Minikube:

kubectl config use-context minikube

The Minikube cluster is easiest to view with:

minikube dashboard

This opens a Kubernetes dashboard for the Minikube cluster, where you can see Deployments, Pods, ReplicaSets, Services, and events.

What Successful Output Looks Like

After Minikube starts successfully, kubectl get nodes should show a ready Minikube node:

kubectl get nodes

Expected:

NAME       STATUS   ROLES           AGE   VERSION
minikube   Ready    control-plane   ...   v1.33.3

After applying the manifests, kubectl get pods should show two running Pods:

kubectl get pods

Expected:

NAME                                READY   STATUS    RESTARTS   AGE
k8s-playground-api-xxxxx            1/1     Running   0          ...
k8s-playground-api-yyyyy            1/1     Running   0          ...

When you open http://localhost:3000, the browser should show JSON like this:

{
  "message": "Hello from a container!",
  "service": "hello-node",
  "pod": "k8s-playground-api-c7cfb69c7-j9nrd",
  "time": "2026-06-16T10:37:33.818Z"
}

The exact Pod name and time will be different on your machine.

What This Project Teaches

Containerizing a Node.js API with Docker

The Express app runs normally with Node.js, but Kubernetes runs containers. The Dockerfile describes how to build a container image for the app. That image includes Node.js, installs the project dependencies, copies the app files, exposes port 3000, and starts the server with npm start.

Pushing and Pulling an Image from Docker Hub

Docker Hub is a container image registry. You can build an image on your machine and push it to Docker Hub. Kubernetes can then pull that image when it creates Pods.

In this project, the Kubernetes Deployment uses:

image: shihamahamed/k8s-playground-api

That means Kubernetes will try to pull the shihamahamed/k8s-playground-api image from Docker Hub.

Running a Local Kubernetes Cluster with Minikube

Minikube runs a small Kubernetes cluster on your computer. It is useful for learning because you can practice Kubernetes concepts locally before using a cloud provider.

This project uses Minikube with the Docker driver:

minikube start --driver=docker

Deployments

A Deployment tells Kubernetes how to run your application. It defines the container image, how many replicas should run, which ports the container exposes, environment variables, resource requests and limits, and health checks.

This project has a Deployment named:

k8s-playground-api

The Deployment is defined in:

k8s/deployment.yaml

Pods

A Pod is the smallest deployable unit in Kubernetes. In this project, each Pod runs one container with the Express API.

The Deployment creates Pods for you. You usually do not create these Pods manually. Instead, you tell the Deployment how many replicas you want.

ReplicaSets

A ReplicaSet makes sure the requested number of Pods are running. Deployments manage ReplicaSets automatically.

For example, this project starts with:

replicas: 2

That means Kubernetes should keep two API Pods running.

Services

Pods can be replaced at any time, so their IP addresses are not stable. A Service gives your Pods a stable network endpoint.

This project has a Service named:

k8s-playground-api-service

The Service is defined in:

k8s/service.yaml

NodePort

The Service uses NodePort. A NodePort Service exposes the app on a port on the Kubernetes node. In Minikube, you can ask Minikube for the service URL.

minikube service k8s-playground-api-service --url

For simple local testing, this README also uses kubectl port-forward, which maps the Kubernetes Service to localhost:3000.

Readiness Probes

A readiness probe tells Kubernetes whether the app is ready to receive traffic.

This project uses:

/readyz

If the readiness check fails, Kubernetes keeps the Pod running but stops sending traffic to it through the Service.

Liveness Probes

A liveness probe tells Kubernetes whether the app is still alive.

This project uses:

/healthz

If the liveness check fails repeatedly, Kubernetes restarts the container.

Environment Variables from Pod Metadata

The Deployment passes the Pod name into the app using the POD_NAME environment variable:

- name: POD_NAME
  valueFrom:
    fieldRef:
      fieldPath: metadata.name

The / endpoint returns this value, which helps you see which Pod handled a request.

Scaling Replicas

Scaling means changing how many copies of the app are running. For example, you can scale from two Pods to four Pods:

kubectl scale deployment k8s-playground-api --replicas=4

Self-Healing

Kubernetes tries to keep the desired state running. If you delete one Pod from a Deployment, Kubernetes creates another Pod to replace it.

Service Routing and Load Balancing

The Service sends traffic to healthy, ready Pods that match its selector. Because this project has multiple replicas, the Service can route requests to different Pods.

Debugging with kubectl

You will use kubectl to inspect the cluster. The most useful commands while learning are:

kubectl get pods
kubectl describe pod <pod-name>
kubectl logs <pod-name>
kubectl get events --sort-by=.lastTimestamp

These commands help you understand what Kubernetes is doing and why something may not be working.

Project Structure

k8s-playground/
|-- index.js
|-- package.json
|-- package-lock.json
|-- Dockerfile
|-- docker-compose.yaml
|-- deploy.sh
|-- k8s/
|   |-- deployment.yaml
|   `-- service.yaml
|-- .dockerignore
|-- .gitignore
`-- README.md

index.js

The main Express API file. It creates the server, defines the routes, and listens on port 3000 by default.

Important routes:

• GET /
• GET /readyz
• GET /healthz

package.json

Defines the Node.js project metadata, dependencies, and scripts.

Important scripts:

{
  "dev": "node --watch index.js",
  "start": "node index.js",
  "deploy": "sh deploy.sh"
}

Dockerfile

Defines how to build the Docker image for the Express API. It uses node:18-alpine, installs dependencies with npm ci --omit=dev, copies the app files, exposes port 3000, and runs npm start.

docker-compose.yaml

Runs the API with Docker Compose. It builds the image from the local Dockerfile, maps port 3000, mounts the current folder into the container, and runs the dev script.

deploy.sh

Builds the Docker image, pushes it to Docker Hub, applies the Kubernetes manifests, and prints useful cluster information.

The script uses:

shihamahamed/k8s-playground-api:latest

k8s/deployment.yaml

Creates the Kubernetes Deployment. It defines:

• Deployment name: k8s-playground-api
• Replica count: 2
• Docker Hub image: shihamahamed/k8s-playground-api
• Container port: 3000
• NODE_ENV environment variable
• POD_NAME environment variable from Kubernetes metadata
• CPU and memory requests and limits
• Readiness probe at /readyz
• Liveness probe at /healthz

k8s/service.yaml

Creates the Kubernetes Service. It defines:

• Service name: k8s-playground-api-service
• Service type: NodePort
• Service port: 3000
• Target container port: 3000
• Selector: app: k8s-playground-api

.dockerignore

Tells Docker which files and folders to leave out of the build context. This keeps the Docker build cleaner and avoids copying unnecessary files such as node_modules.

.gitignore

Tells Git which files and folders should not be committed. This project ignores node_modules.

API Endpoints

GET /

Returns a JSON response with a message, service name, Pod name, and timestamp.

Example response when running in Kubernetes:

{
  "message": "Hello from a container!",
  "service": "hello-node",
  "pod": "k8s-playground-api-6f8c9d7d6b-abc12",
  "time": "2026-06-16T10:30:00.000Z"
}

When running locally without Kubernetes, pod will usually be:

"unknown"

That happens because POD_NAME is provided by Kubernetes only when the app is running inside a Pod.

GET /readyz

Readiness endpoint used by Kubernetes.

Expected response:

ready

GET /healthz

Liveness endpoint used by Kubernetes.

Expected response:

ok

Prerequisites

Install these tools before running the project:

• Node.js
• npm
• Docker Desktop
• Docker Hub account
• Minikube
• kubectl
• PowerShell or another terminal

Check the main tools:

node --version
npm --version
docker --version
minikube version
kubectl version --client

Make sure Docker Desktop is running before starting Minikube with the Docker driver.

Running Locally Without Kubernetes

Use this when you want to test only the Express app.

1. Install dependencies

npm install

This installs the Express dependency listed in package.json.

2. Run in development mode

npm run dev

This starts the app with Node.js watch mode. The server restarts when files change.

Open:

http://localhost:3000

Test the health endpoints:

http://localhost:3000/readyz
http://localhost:3000/healthz

3. Run in normal start mode

npm start

This runs:

node index.js

Use this when you want to run the app the same way the Docker container runs it.

Running with Docker

Use this when you want to test the container before using Kubernetes.

1. Build the image locally

docker build -t k8s-playground-api .

This creates a local Docker image named k8s-playground-api.

2. Run the container locally

docker run --rm -p 3000:3000 --name k8s-playground-api k8s-playground-api

This maps your computer's port 3000 to the container's port 3000.

Open:

http://localhost:3000

Stop the container with Ctrl+C.

3. Run with Docker Compose

docker compose up --build

This builds the image and starts the service defined in docker-compose.yaml.

Open:

http://localhost:3000

4. Stop Docker Compose

docker compose down

This stops and removes the Compose container.

Running with Kubernetes Using Minikube

Use this when you want to practice Kubernetes Deployments, Pods, Services, probes, scaling, and debugging.

1. Start Minikube

minikube start --driver=docker

This starts a local Kubernetes cluster using Docker Desktop.

2. Verify Minikube status

minikube status

This confirms that Minikube is running.

3. Verify kubectl can see the node

kubectl get nodes

You should see a Minikube node with status Ready.

4. Apply the Kubernetes manifests

kubectl apply -f k8s/

This creates or updates the Deployment and Service from the k8s/ folder.

5. Check the Pods

kubectl get pods

You should eventually see two Pods with status Running.

For more detail:

kubectl get pods -o wide

6. Check the Service

kubectl get svc

Look for:

k8s-playground-api-service

7. Port-forward the Service

kubectl port-forward service/k8s-playground-api-service 3000:3000

This forwards traffic from your computer to the Kubernetes Service.

Keep this terminal open while testing. In another terminal, open:

http://localhost:3000

You can also test with curl:

curl.exe http://localhost:3000
curl.exe http://localhost:3000/readyz
curl.exe http://localhost:3000/healthz

Docker Hub Image Flow

There are three separate ideas to understand.

Building an image locally

docker build -t shihamahamed/k8s-playground-api:latest .

This creates the image on your own computer.

Pushing an image to Docker Hub

docker login
docker push shihamahamed/k8s-playground-api:latest

This uploads the image to Docker Hub so other systems can pull it.

Kubernetes pulling the image

The Deployment contains:

image: shihamahamed/k8s-playground-api

When Kubernetes creates a Pod, it asks the container runtime to pull that image. If no tag is provided, Docker/Kubernetes treat it like latest.

So this:

image: shihamahamed/k8s-playground-api

is effectively:

image: shihamahamed/k8s-playground-api:latest

If the image does not exist on Docker Hub, or if it is private and Kubernetes does not have permission, the Pod may show ImagePullBackOff or ErrImagePull.

Using the deploy script

The project includes:

npm run deploy

This runs:

sh deploy.sh

On Windows, this requires a shell that can run .sh files, such as Git Bash or WSL. If you are using plain PowerShell and sh is not available, run the Docker and Kubernetes commands manually from this README.

Useful Kubernetes Commands

Show all common resources:

kubectl get all

Show Pods:

kubectl get pods

Show Pods with node and IP information:

kubectl get pods -o wide

Describe a specific Pod:

kubectl describe pod <pod-name>

Read logs from a Pod:

kubectl logs <pod-name>

Show recent cluster events:

kubectl get events --sort-by=.lastTimestamp

Describe the Deployment:

kubectl describe deployment k8s-playground-api

Describe the Service:

kubectl describe svc k8s-playground-api-service

Scaling Test

Start with the current Deployment:

kubectl get pods

Scale the app to four replicas:

kubectl scale deployment k8s-playground-api --replicas=4

Check the new Pods:

kubectl get pods

Scale back to two replicas:

kubectl scale deployment k8s-playground-api --replicas=2

Check again:

kubectl get pods

Kubernetes will create or remove Pods until the actual state matches the requested replica count.

Self-Healing Test

Get the current Pods:

kubectl get pods

Delete one Pod:

kubectl delete pod <pod-name>

Watch Kubernetes recreate it:

kubectl get pods -w

Because the Deployment wants two replicas, Kubernetes creates a replacement Pod automatically.

Press Ctrl+C to stop watching.

Testing Service Routing and Load Balancing

Because the Deployment runs two replicas, the Service can send requests to different Pods.

Browser refresh may keep showing the same Pod because browsers often reuse connections. Also, kubectl port-forward service/k8s-playground-api-service 3000:3000 may select one backend Pod for the forwarded connection, so it is not always the best way to prove load balancing.

To better test Service routing, get a Minikube Service URL:

minikube service k8s-playground-api-service --url

Minikube may print a URL like:

http://127.0.0.1:<PORT>

On some Windows Docker-driver setups, Minikube may keep that terminal open while it creates a tunnel. If that happens, leave it running and use a second terminal for the curl test.

In another terminal, use that URL for repeated requests:

1..20 | ForEach-Object { curl.exe http://127.0.0.1:<PORT> }

Replace <PORT> with the port from the minikube service output.

You can also store the URL in a variable:

$url = minikube service k8s-playground-api-service --url
1..20 | ForEach-Object { curl.exe $url }

Look at the pod value in the JSON response. Seeing different Pod names proves that the Service is routing traffic to multiple Pods.

Minikube Dashboard

Open the Kubernetes dashboard:

minikube dashboard

This opens a visual UI for exploring:

• Deployments
• Pods
• ReplicaSets
• Services
• Events

The dashboard is helpful while learning because you can connect the YAML files to the resources Kubernetes creates.

Cleanup

Delete the Kubernetes resources created from the manifests:

kubectl delete -f k8s/

This removes the Deployment and Service from the cluster.

Stop Minikube:

minikube stop

Stopping Minikube turns off the local cluster but keeps its data. You can start it again later.

Delete Minikube:

minikube delete

Deleting Minikube removes the local cluster completely. Use this when you want a fresh start or no longer need the local cluster.

Troubleshooting

Docker Desktop is not running

If Minikube uses the Docker driver, Docker Desktop must be running first.

Check Docker:

docker version

Then start Minikube again:

minikube start --driver=docker

Minikube is stuck downloading

Sometimes Minikube needs time to download images or cluster components.

Check status:

minikube status

If it keeps failing, restart Docker Desktop and try again:

minikube stop
minikube start --driver=docker

If the normal start command still gets stuck, try the fallback command in the "Windows / Docker Desktop Minikube Fallback Command" section.

Proxy, DNS, and Minikube cache cleanup on Windows

Proxy environment variables can break Minikube or Docker image pulls if they point to a proxy that does not really exist.

Do not set this unless it is a real valid proxy for your host:

HTTP_PROXY=http://http.docker.internal:3128

To clear proxy variables from the current PowerShell session, run:

Remove-Item Env:HTTP_PROXY -ErrorAction SilentlyContinue
Remove-Item Env:HTTPS_PROXY -ErrorAction SilentlyContinue
Remove-Item Env:NO_PROXY -ErrorAction SilentlyContinue
Remove-Item Env:http_proxy -ErrorAction SilentlyContinue
Remove-Item Env:https_proxy -ErrorAction SilentlyContinue
Remove-Item Env:no_proxy -ErrorAction SilentlyContinue

Get-ChildItem Env:*proxy*

Get-ChildItem Env:*proxy* should show no unexpected proxy variables.

If Minikube's local state is badly stuck, you can fully remove Minikube state and flush DNS:

minikube delete --all --purge
ipconfig /flushdns

minikube delete --all --purge removes Minikube clusters, profiles, and cached state. Use it when you want a clean Minikube start.

If Docker can pull the fallback Minikube base image, that is a good sign that Docker can reach Docker Hub:

docker pull docker.io/kicbase/stable:v0.0.48

Pod is stuck in ContainerCreating

This can happen while Kubernetes is pulling the image or setting up the container.

Inspect the Pod:

kubectl describe pod <pod-name>

Check events:

kubectl get events --sort-by=.lastTimestamp

Pod shows ImagePullBackOff or ErrImagePull

This usually means Kubernetes cannot pull the Docker image.

Common causes:

• The image name is wrong.
• The image has not been pushed to Docker Hub.
• The image is private and Kubernetes does not have credentials.
• Docker Hub is temporarily unreachable.

Inspect the Pod:

kubectl describe pod <pod-name>

Verify the image exists on Docker Hub:

docker pull shihamahamed/k8s-playground-api:latest

kubectl port-forward says the Pod is not running

The Service forwards to Pods that must exist and be ready.

Check Pod status:

kubectl get pods

Inspect a failing Pod:

kubectl describe pod <pod-name>

Read logs:

kubectl logs <pod-name>

kubectl context is not pointing to Minikube

Check the current context:

kubectl config current-context

Switch to Minikube:

kubectl config use-context minikube

Update the Minikube context:

minikube update-context

Check nodes again:

kubectl get nodes

Minikube DNS or network issues

Check Minikube:

minikube status

Check cluster events:

kubectl get events --sort-by=.lastTimestamp

Restarting Minikube can help during local learning:

minikube stop
minikube start --driver=docker

The app starts locally but not in Kubernetes

Compare local logs and Kubernetes logs.

Local:

npm start

Kubernetes:

kubectl get pods
kubectl logs <pod-name>
kubectl describe pod <pod-name>

If the Pod is running but traffic does not work, check the Service:

kubectl describe svc k8s-playground-api-service

Learning Summary

• The Express app runs inside a Docker container.
• Docker Hub stores the container image so Kubernetes can pull it.
• The Kubernetes Deployment keeps the desired number of Pods running.
• Each Pod runs the API container.
• The ReplicaSet, managed by the Deployment, keeps the replica count correct.
• The Service gives the Pods a stable endpoint.
• The NodePort Service makes the app reachable from the Minikube node.
• Readiness probes tell Kubernetes when the app can receive traffic.
• Liveness probes tell Kubernetes when the app should be restarted.
• The POD_NAME environment variable shows which Pod handled a request.
• Scaling changes how many app replicas are running.
• Self-healing replaces failed or deleted Pods.
• Minikube lets you practice Kubernetes locally before using a real cloud cluster.

This project is intentionally small, which makes it useful for university review, demos, and future Kubernetes practice.