Deploy and Scale a Web App on Kubernetes

Deploy, scale, and update an nginx app on a local Kubernetes cluster.

Introduction

30 Second Summary

Imagine running an app that needs to stay online no matter what. A server crashes, traffic spikes, or you need to update without any downtime. Handling all of this manually would be a full-time job.

In this project, you will deploy a web application to a local Kubernetes cluster, scale it up and down, watch it self-heal when things break, and perform a zero-downtime rolling update.

What You'll Build

A fully functional Kubernetes deployment of an nginx web server running on your local machine, managed entirely through declarative YAML manifests.

By the end of this project, you'll have:

A Kubernetes Deployment and Service written from scratch in YAML, deploying a live web app accessible in your browser.
Hands-on experience with scaling, self-healing, and rolling updates on a real cluster using kubectl commands.
A working mental model of how Pods, Deployments, and Services fit together to keep your app running.
Secret Mission: Add health checks and resource limits to make your deployment production-ready.

Are there any prerequisites?

You should have basic familiarity with Docker containers. If you know what an image and a container are, you have everything you need.

Enable Kubernetes and Verify Your Cluster

Kubernetes manages containers across a group of machines called a cluster. For local development, Docker Desktop can spin up a single-node cluster right on your machine.

In this step, you'll enable Kubernetes inside Docker Desktop, confirm the cluster is healthy using kubectl, and create a project folder to hold your manifest files.

In this step, get ready to:

Enable Kubernetes in Docker Desktop.
Verify kubectl and the single-node cluster.
Create your project folder and open it in VS Code.

Enable Kubernetes in Docker Desktop

Docker Desktop includes a built-in Kubernetes cluster that you can enable with a single setting. Once enabled, it pulls the required container images and starts a local cluster automatically.

Press the Windows key to open your search bar.
Type Docker Desktop and press Enter to open it.
Click the gear icon in the top-right corner to open Settings.
Select Kubernetes in the left sidebar.
Check the box labelled Enable Kubernetes.
Click Apply & Restart.
Wait for the green Kubernetes running indicator to appear in the bottom-left of Docker Desktop.

Why does this take a few minutes?

The first time you enable Kubernetes, Docker Desktop downloads several container images that make up the cluster's control plane. This typically takes 2-5 minutes depending on your internet speed.

Docker Desktop also installs kubectl automatically on Windows, so you don't need to install it separately.

Don't see the Kubernetes option?

Docker Desktop must be in Linux containers mode for Kubernetes to appear. Right-click the Docker icon in your system tray and check if you see Switch to Linux containers. If you see Switch to Windows containers instead, you're already on Linux containers and the issue is elsewhere.

If the green indicator doesn't appear after 5 minutes, try clicking Apply & Restart again. Help me troubleshoot Kubernetes not starting in Docker Desktop

Verify your cluster is running

With Kubernetes enabled, you can use kubectl (the Kubernetes command-line tool) to talk to your cluster. Let's confirm everything is connected.

Press the Windows key to open your search bar.
Type PowerShell and press Enter to open it.

Confirm kubectl is installed by running this command:

kubectl version --client

You should see version information for the kubectl client, including a version number.

Check that your cluster node is running by running this command:

kubectl get nodes

You should see one node named docker-desktop with STATUS Ready.

Confirm you are connected to the correct context by running this command:

kubectl config current-context

The output should be docker-desktop.

Seeing 'command not found' or connection errors?

If kubectl is not recognized, close and reopen PowerShell so it picks up the updated PATH from Docker Desktop.

If kubectl get nodes shows NotReady instead of Ready, wait another minute for the cluster to fully start. Then run the command again.

If the context is not docker-desktop, switch to it by running:

kubectl config use-context docker-desktop

Help me troubleshoot kubectl not connecting to my Docker Desktop cluster

Create your project folder

You need a dedicated folder to hold the Kubernetes manifest files you'll write in the next steps.

Create your project folder and move into it by running these commands:

mkdir ~/k8s-project
cd ~/k8s-project

Confirm the folder was created by running:

ls

The folder will be empty, but the command should run without errors.

Press the Windows key to open your search bar.
Type Visual Studio Code and press Enter to open it.
In VS Code, click File in the top menu bar.
Click Open Folder.
Navigate to your user folder, select the k8s-project folder, and click Select Folder.

Where is k8s-project?

The ~ shortcut in PowerShell resolves to your user folder (usually C:\Users\YourName). Look for k8s-project at the top level of that folder in the Open Folder dialog.

Can't find the folder?

In the Open Folder dialog, type %USERPROFILE%\k8s-project into the path bar at the top and press Enter. This takes you directly to the folder.

Help me find my k8s-project folder in VS Code

Your environment is ready. Next up, you'll write your first Kubernetes Deployment manifest and get an app running on the cluster.

Deploy Your First Application

Your Kubernetes cluster is up and running. Now it's time to put it to work by deploying your first application.

With plain Docker, there's no built-in way to say 'keep exactly 2 copies of this container running at all times.' Kubernetes Deployments solve this by letting you declare your desired state in a YAML file, and Kubernetes continuously works to make reality match.

In this step, get ready to:

Write a Deployment manifest that defines your desired application state.
Apply the manifest to deploy nginx to your cluster.
Inspect Pods, Deployments, and ReplicaSets with kubectl commands.

Write the Deployment manifest

A Deployment is a Kubernetes resource that manages a set of identical Pods. You describe what you want (which container image, how many copies) and Kubernetes handles creating, monitoring, and restarting them.

In VS Code, create a new file called deployment.yaml inside your k8s-project folder.
Paste the following YAML into deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  labels:
    app: nginx
spec:
  # How many pod copies to maintain
  replicas: 2
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.14.2
        ports:
        - containerPort: 80

What does this manifest do?

apiVersion: apps/v1 and kind: Deployment tell Kubernetes you are defining a Deployment resource.
replicas: 2 means Kubernetes will always maintain exactly 2 copies of your container.
selector.matchLabels connects the Deployment to any Pod with the label app: nginx.
image: nginx:1.14.2 specifies the exact nginx container image to run in each Pod.
containerPort: 80 declares the port the container listens on.

Save deployment.yaml.

You won't see a change yet. The next substep applies this manifest to your cluster.

YAML not saving correctly?

Make sure you created the file with the .yaml extension, not .txt or .yml.
Confirm the file is inside your k8s-project folder by checking the VS Code Explorer sidebar.

Help me troubleshoot my deployment.yaml file setup.

Apply the manifest and inspect your deployment

With your manifest written, you can now tell Kubernetes to create the resources it describes. The kubectl apply command reads your YAML file and sends the desired state to the cluster.

Deploy your manifest to the cluster by running this command:

kubectl apply -f deployment.yaml

You should see deployment.apps/nginx-deployment created in the output.

Seeing a YAML parsing error?

YAML is sensitive to indentation. Every nested level must use exactly 2 spaces, not tabs.
Check that spec, template, and containers are each indented by 2 more spaces than their parent.
Make sure you are running the command from inside the k8s-project folder where deployment.yaml lives.

Help me fix my kubectl apply YAML error.

Check your deployment status by running:

kubectl get deployments

You should see nginx-deployment with 2/2 in the READY column.

View the individual Pods that Kubernetes created by running:

kubectl get pods

You should see 2 pods with STATUS Running and READY 1/1. Each pod has an auto-generated name like nginx-deployment-xxxxx-xxxxx.

Get detailed information about your deployment by running:

kubectl describe deployment nginx-deployment

What does describe show you?

The describe command gives you a full breakdown of the resource. Look for the Replicas field confirming 2 desired and 2 available.

You will also see a NewReplicaSet field. This is the ReplicaSet that your Deployment created behind the scenes to manage the Pods.

Understand what happened behind the scenes

Your single kubectl apply command triggered a chain of events. The Deployment created a ReplicaSet, and the ReplicaSet created the Pods.

View the ReplicaSet that your Deployment created by running:

kubectl get rs

You should see one ReplicaSet with 2 in both the DESIRED and READY columns.

What is a ReplicaSet?

A ReplicaSet is the layer between a Deployment and its Pods. Its job is to maintain the correct number of Pod replicas at all times.

You rarely interact with ReplicaSets directly. The Deployment manages them for you and creates new ones during rolling updates.

Pick one of your pod names from the kubectl get pods output, then inspect it by running:

kubectl describe pod [[PODNAME="your pod name from kubectl get pods"]]

What does pod describe show you?

The pod details include its IP address on the cluster network, the node it runs on (docker-desktop), and the Events section showing when it was scheduled, pulled the image, and started the container.

This is useful for debugging when pods fail to start. The Events section tells you exactly where things went wrong.

✔️ Awesome, I've got everything!

Great. Double check you have saved deployment.yaml and that both pods show STATUS Running in your terminal.

ⓧ I'd like to double check the full code

Here is the complete deployment.yaml you should have at this point:

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

Your nginx application is deployed and running on two Pods. Next up, you will expose it to the outside world so you can access it in your browser.

Expose Your App with a Service

Your nginx pods are running, but they're completely isolated inside the cluster. No one can reach them from outside.

In this step, you'll create a Service that acts as a stable front door for your pods. The Service routes external traffic to your running containers so you can access your app in the browser.

In this step, get ready to:

Write a Service manifest that maps external traffic to your pods.
Apply the manifest and access your running app in the browser.
Explore service endpoints and pod logs.

Write the Service manifest

A NodePort Service exposes your app on a fixed port across the cluster's node. On Docker Desktop, that means you can hit localhost:<nodePort> in your browser to reach any pod the Service selects.

In VS Code, create a new file called service.yaml inside your k8s-project folder.
Paste the following YAML into service.yaml:

apiVersion: v1
kind: Service
metadata:
  name: nginx-service
spec:
  type: NodePort
  selector:
    app: nginx
  ports:
  - port: 80
    targetPort: 80
    nodePort: 30080

What does this manifest do?

type: NodePort tells Kubernetes to open a port on the node itself, making the app reachable from outside the cluster.
selector: app: nginx connects this Service to any pod carrying the label app: nginx. That matches your Deployment's pods.
port: 80 is the Service's internal port. targetPort: 80 is the port on the container. nodePort: 30080 is what you'll type in the browser.

Save service.yaml.

Why NodePort instead of LoadBalancer?

NodePort is the simplest way to expose a service on a local cluster. LoadBalancer would request a cloud load balancer, which doesn't exist on your local machine.

The valid NodePort range is 30000-32767. Port 30080 is easy to remember because it maps to nginx's default port 80.

✔️ Awesome, I've got everything!

Great. Double check you've saved your file, then continue below.

ⓧ I'd like to double check the full code

apiVersion: v1
kind: Service
metadata:
  name: nginx-service
spec:
  type: NodePort
  selector:
    app: nginx
  ports:
  - port: 80
    targetPort: 80
    nodePort: 30080

Apply and access your running app

With the manifest saved, you can apply it to your cluster and immediately see results in the browser.

Apply the Service manifest by running this command:

kubectl apply -f service.yaml

Confirm the Service is running by listing all services:

kubectl get services

You should see nginx-service listed with TYPE NodePort and PORT(S) showing 80:30080/TCP.

Don't see nginx-service?

Make sure you saved service.yaml before running the apply command.
Check that your YAML indentation is correct. YAML is whitespace-sensitive, and a single misplaced space can break the file.
Confirm you're in the k8s-project folder by running pwd in PowerShell.

Why isn't my Kubernetes Service showing up after applying the manifest?

Open your browser and navigate to:

http://localhost:30080

You should see the "Welcome to nginx!" default page. This confirms traffic is flowing from your browser, through the NodePort Service, and into one of your pods.

Page not loading in the browser?

Make sure you're using http:// and not https:// in the URL.
Verify your pods are still running with kubectl get pods. Both should show STATUS Running.
Confirm Docker Desktop is in Linux containers mode. The Kubernetes tab is not available in Windows container mode.

Why can't I access my nginx app at localhost:30080 on Docker Desktop?

Explore your service and pods

Now that traffic is flowing, you can inspect how the Service connects to your pods behind the scenes.

See the pod IPs your Service routes traffic to by running:

kubectl describe service nginx-service

Look for the Endpoints field in the output. It lists the IP addresses of the pods currently receiving traffic from this Service.

Refresh your browser at http://localhost:30080 a few times to generate some traffic.
View the nginx access logs from one of your pods by running:

kubectl logs <pod-name>

How do I find my pod name?

Run kubectl get pods and copy one of the pod names from the NAME column. Pod names look like nginx-deployment-xxxxx-xxxxx with random suffixes.

The logs show HTTP GET requests hitting the nginx container. Each browser refresh generates a new log entry.

See the full network details of your pods by running:

kubectl get pods -o wide

The -o wide flag reveals each pod's internal IP address and which node it runs on. Both pods run on the docker-desktop node since you have a single-node cluster.

How does a Service find the right pods?

The Service uses the selector field to find pods with matching labels. Your Service selects app: nginx, and your Deployment stamps that same label on every pod it creates.

If you scale your Deployment later, new pods automatically get the label and the Service starts routing traffic to them with no extra configuration.

Your app is live and reachable through a stable Service. Next up, you'll push Kubernetes to its limits by scaling your Deployment and watching it self-heal.

Scale and Observe Self-Healing

Your app is live and accessible in the browser through a Service. But right now, you only have 2 copies of your container running. What happens if traffic spikes or a container crashes?

Kubernetes manages this for you automatically. In this step, you will scale your deployment up, deliberately break it by killing a pod, and watch Kubernetes fix itself in real time.

In this step, get ready to:

Scale your deployment from 2 to 4 replicas.
Delete a running pod and watch Kubernetes replace it automatically.
Scale back down to 2 replicas and confirm your app stays accessible.

Scale your deployment up

Your Deployment currently runs 2 pods. You can change this number at any time without rewriting your YAML file.

Scale your deployment to 4 replicas by running this command in PowerShell:

kubectl scale deployment/nginx-deployment --replicas=4

You should see deployment.apps/nginx-deployment scaled in the output.

Confirm 4 pods are now running by running:

kubectl get pods

You should see 4 pods listed, all with STATUS Running and READY 1/1.

Check the deployment summary by running:

kubectl get deployment nginx-deployment

The READY column shows 4/4.

What just happened?

You told Kubernetes your desired state is 4 replicas. Kubernetes compared this to the actual state (2 pods), saw the gap, and created 2 new pods to close it.

This is the core loop of Kubernetes: you declare what you want, and the system makes it real. The ReplicaSet behind your Deployment is what actually creates and manages the individual pods.

Still seeing fewer than 4 pods?

Make sure the deployment name in your command matches exactly: nginx-deployment. Run kubectl get deployments to check the name.

If pods show STATUS Pending, your machine may be low on resources. Close other applications and wait 30 seconds for the pods to start.

Why are my pods stuck in Pending status?

Watch Kubernetes self-heal

Kubernetes constantly monitors your cluster. If the actual state ever drifts from your desired state, it takes action to fix it. You are about to see this in action by deliberately deleting a pod.

List your pods and pick one of the pod names by running:

kubectl get pods

Each pod has an auto-generated name like nginx-deployment-xxxxx-yyyyy. Copy one of these names.

Delete that pod by running this command (paste your copied pod name in place of the placeholder):

kubectl delete pod [[POD_NAME="one of your pod names from the list above"]]

Immediately check your pods again by running:

kubectl get pods

You should see a brand new pod with an AGE of just a few seconds. The total count is still 4.

What is self-healing?

Kubernetes detected that the actual state (3 pods) no longer matched the desired state (4 pods). The ReplicaSet immediately created a replacement pod to close the gap.

This happens automatically, with no manual intervention. In production, this means crashed containers get replaced before users even notice.

Don't see a replacement pod?

Run kubectl get pods again after 5-10 seconds. The replacement pod may still be in ContainerCreating status.

If you see only 3 pods and no new one appearing, run kubectl get deployment nginx-deployment to confirm the desired replica count is still 4.

Why isn't Kubernetes replacing my deleted pod?

Scale back down

Scaling down works the same way. You declare a new desired state, and Kubernetes gracefully terminates the extra pods.

Scale back to 2 replicas by running:

kubectl scale deployment/nginx-deployment --replicas=2

You should see deployment.apps/nginx-deployment scaled again.

Confirm the scale-down by running:

kubectl get pods

You should see 2 pods with STATUS Running. The terminated pods disappear from the list within a few seconds.

Open your browser and refresh http://localhost:30080.

The "Welcome to nginx!" page still loads. Your app stayed accessible throughout the entire scaling process.

Why did the app stay up during scaling?

Your Service routes traffic to any pod with the label app: nginx. As long as at least one pod with that label is running, the Service has somewhere to send requests.

Kubernetes terminates pods gracefully during scale-down. It waits for in-flight requests to finish before shutting a pod down, so users experience zero interruption.

Page not loading after scaling down?

Make sure at least one pod shows STATUS Running when you run kubectl get pods. If all pods are in Terminating state, wait a few seconds and try refreshing again.

My app stopped working after scaling down.

You have just experienced the two superpowers of Kubernetes: elastic scaling and automatic self-healing. Next up, you will perform a rolling update to change your app's version with zero downtime.

Perform a Rolling Update

Your deployment can scale up, scale down, and heal itself automatically. But what happens when you need to ship a new version of your app?

In production, you cannot take your app offline to swap containers. Kubernetes solves this with rolling updates, which replace your pods one-by-one so at least some pods are always serving traffic. In this step, you will update your nginx version, watch Kubernetes perform the swap with zero downtime, and practice reverting to a previous version.

In this step, get ready to:

Update your deployment to a new container image version.
Verify the update and inspect rollout history.
Practice a rollback to a previous version.

Update your deployment to a new version

The production workflow for updating a Kubernetes app is to edit your YAML manifest and re-apply it. Kubernetes detects the change and orchestrates the transition without dropping traffic.

In VS Code, open deployment.yaml.
Find the image line inside the containers section:

        image: nginx:1.14.2

Change nginx:1.14.2 to nginx:1.16.1, so the line now reads:

        image: nginx:1.16.1

Save deployment.yaml.

✔️ Awesome, I've got everything!

Great. Double check you have saved the file before applying it.

ⓧ I'd like to double check the full code

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

Apply the updated manifest by running this command in PowerShell:

kubectl apply -f deployment.yaml

Immediately watch the rollout progress by running:

kubectl rollout status deployment/nginx-deployment

What is happening during the rolling update?

Kubernetes creates new pods running nginx:1.16.1 one at a time. As each new pod becomes ready, an old pod running nginx:1.14.2 is terminated.

At every point during this process, at least one pod is serving traffic. This is how Kubernetes achieves zero-downtime deployments.

You should see the message deployment "nginx-deployment" successfully rolled out when the update is complete.

Open your browser and refresh http://localhost:30080.

The "Welcome to nginx!" page still loads. Your app stayed accessible the entire time.

Rollout stuck or timing out?

Make sure you saved deployment.yaml before running kubectl apply. Unsaved changes mean the old image is re-applied.
Check that the image value is exactly nginx:1.16.1 with no extra spaces or typos.
Run kubectl get pods to see if any pods are in ImagePullBackOff status, which means the image name is misspelled.

Why is my rolling update stuck or failing?

Verify the update and check history

Check your pods by running:

kubectl get pods

Notice the pod names are different from before, and their AGE column shows they were created seconds or minutes ago. These are the new pods that replaced the old ones.

Inspect the deployment details by running:

kubectl describe deployment nginx-deployment

Look for the Image field in the output. It now shows nginx:1.16.1.

View your rollout history by running:

kubectl rollout history deployment/nginx-deployment

What does rollout history show?

Each row is a revision. Revision 1 is your original deployment with nginx:1.14.2. Revision 2 is the update to nginx:1.16.1.

Kubernetes keeps this history so you can roll back to any previous revision at any time.

Practice a rollback

Sometimes an update introduces a bug and you need to revert quickly. Kubernetes makes this a single command.

Roll back to the previous version by running:

kubectl rollout undo deployment/nginx-deployment

Watch the rollback complete by running:

kubectl rollout status deployment/nginx-deployment

You should see deployment "nginx-deployment" successfully rolled out once the rollback finishes.

Confirm you are back on the old version by running:

kubectl describe deployment nginx-deployment

The Image field should show nginx:1.14.2 again.

What happened during the rollback?

Kubernetes performed another rolling update, but in reverse. It replaced the nginx:1.16.1 pods with nginx:1.14.2 pods one-by-one, keeping the app available throughout.

A rollback is just a rolling update to a previously known-good state. Your app at http://localhost:30080 stayed accessible the entire time.

Re-apply your updated deployment.yaml to go back to nginx:1.16.1 by running:

kubectl apply -f deployment.yaml

Confirm the final state by running:

kubectl rollout status deployment/nginx-deployment

Your deployment is now running nginx:1.16.1 with 2 replicas. You have successfully performed a rolling update, a rollback, and a re-deploy.

Describe still showing the old image?

Make sure deployment.yaml on disk still contains nginx:1.16.1. The rollback command changed the live cluster, not your file.
Run kubectl describe deployment nginx-deployment again after the rollout status reports success.

Why is my deployment showing the wrong image version after re-applying?

Secret mission

Add Health Checks and Resource Limits

Your deployment works, but it's not production-ready. Real-world clusters need health checks so Kubernetes knows when a container is broken, and resource limits so one app can't starve the others. Can you harden your deployment?

Clean Up Your Resources

This project runs entirely on your local machine using Docker Desktop's built-in Kubernetes. There are no cloud costs or ongoing charges.

Decide whether to keep your resources running, pause them to come back later, or delete them entirely.

Resources you used:

A local Kubernetes cluster running inside Docker Desktop.
Deployment and Service objects in the default namespace.
Project folder ~/k8s-project with deployment.yaml and service.yaml.

Keep everything running

No action needed. Choose this if you're still actively building or experimenting with Kubernetes.

The Kubernetes cluster uses some RAM and CPU while Docker Desktop is running. The impact is minimal on modern machines.
Your Deployment and Service remain active. You can access your app at http://localhost:30080 whenever Docker Desktop is running.
Your project files stay in ~/k8s-project.

Pause - I'll come back to this later

Shut down the Kubernetes cluster to free up memory and CPU, but keep your project files for later.

Open Docker Desktop.
Click the gear icon to open Settings.
Select Kubernetes from the left sidebar.
Uncheck Enable Kubernetes.
Click Apply & Restart.

This stops the cluster but keeps your configuration. Your project files in ~/k8s-project remain untouched. To resume, re-enable Kubernetes in the same settings page.

Delete - I don't want to use this again

Remove all project resources and start fresh.

Delete the Kubernetes Service and Deployment by running these commands in PowerShell from your ~/k8s-project folder:

kubectl delete -f service.yaml
kubectl delete -f deployment.yaml

Disable the Kubernetes cluster:

Open Docker Desktop.
Click the gear icon to open Settings.
Select Kubernetes from the left sidebar.
Uncheck Enable Kubernetes.
Click Apply & Restart.

Delete the project folder by running:

cd ~
Remove-Item -Recurse -Force ~/k8s-project

Confirm the folder is gone by running:

ls ~/k8s-project

You should see an error indicating the path does not exist. That confirms the folder has been removed.

Nice Work!

You just deployed, scaled, and updated a containerized web app on a real Kubernetes cluster. These are the same workflows teams use to manage production workloads at scale.

You've learned how to:

Write Deployment and Service manifests from scratch and deploy them to a local Kubernetes cluster using declarative YAML.
Scale a deployment up and down, and witness Kubernetes self-healing recreate deleted pods automatically.
Perform a zero-downtime rolling update and practice a rollback to a previous version.
Secret Mission: Hardened your deployment with liveness/readiness probes and resource limits to make it production-ready.

Ready to quiz yourself?