Kubernetes Tutorial: From Zero to Deploying Your First App

Learn Kubernetes from scratch with Docker Desktop or Minikube. Deploy Nginx with YAML, expose a Service, test self-healing, scale Pods, and roll back.

Development workstation showing an illustrative Kubernetes orchestration diagram with connected container workloads on a monitor.

You have built a Docker image, run a container, and perhaps used Docker Compose to start several services together. What happens when your application needs to stay available while containers fail, traffic grows, or a new version rolls out?

That is where Kubernetes comes in.

Kubernetes (K8s) is a container orchestration platform that manages where containerized applications run, how many copies should exist, and how they recover when something fails. In this hands-on Kubernetes tutorial for beginners, you will create a local cluster, deploy three copies of an Nginx web server, open it in your browser, delete a Pod to observe self-healing, and practice scaling and updates.

You do not need a paid cloud account. The tutorial uses Docker Desktop or Minikube on your own computer.

If container images, Dockerfiles, or Compose are still unfamiliar, start with our Docker tutorial for beginners and return here when you are comfortable running a container.

What is Kubernetes, and when do you need it?

Docker helps you package an application into an image and run that image as a container. Kubernetes focuses on managing containerized workloads across a cluster. The cluster might be a single laptop for learning or several machines in a production environment.

Imagine a small online store. Running its website in one container may be perfectly adequate at first. But if the container stops, the website becomes unavailable until something restarts it. If you run several copies across different machines, you now need a way to coordinate them.

Kubernetes helps with that coordination:

  • Self-healing: Controllers replace missing Pods, and failed containers may be restarted according to their restart policy. Kubernetes cannot fix a bug inside your application.
  • Scaling: You can manually change the number of replicas. Automatic scaling is available through separately configured features such as the HorizontalPodAutoscaler (HPA), which requires suitable metrics.
  • Rolling updates and rollbacks: Deployments can replace Pods gradually and return to an earlier revision. Continuous availability still depends on application health, capacity, and correct configuration.
  • Service discovery: Services provide a stable way to reach a changing set of Pods, and Kubernetes provides DNS-based service discovery inside a cluster.

Do you need Kubernetes for every Docker project? No. A single application or a modest set of services may be easier to operate with Docker Compose. Kubernetes becomes useful when the benefits of scheduling, replication, recovery, and standardized deployment outweigh the cost of learning and managing the platform.

Kubernetes architecture explained without the jargon

A Kubernetes cluster contains a control plane that coordinates the system and one or more Nodes that run your workloads. The basic building blocks are:

ComponentWhat it doesHow to think about it
ClusterThe complete Kubernetes environmentA team of machines managed together
Control planeSchedules workloads and maintains desired stateThe coordinator of the team
NodeA physical or virtual machine that runs PodsOne worker machine
PodThe smallest deployable unit; usually runs one containerA wrapper around one or more tightly coupled containers
DeploymentDeclares and maintains a set of interchangeable PodsThe desired replica count and update plan
ServiceGives selected Pods a stable network endpointA consistent address in front of changing Pods

These comparisons are mental models, not exact one-to-one Docker equivalents. For example, a Kubernetes Pod is not identical to a container, and modern Kubernetes does not require Docker Engine on its Nodes.

Here is the relationship you will build:

Kubernetes cluster
|
+-- Control plane
|   +-- Maintains the desired state
|
+-- Node (local machine or VM)
    +-- Pod: nginx container
    +-- Pod: nginx container
    +-- Pod: nginx container

Service: glimpz-web-service
    +-- Routes requests to ready Pods

A Deployment asks for three Pods. The Kubernetes controllers work to maintain that number. A Service selects those Pods using labels, so clients do not need to track individual Pod IP addresses.

Diagram of a Kubernetes cluster with a control plane, a worker Node running three ready Nginx Pods, and a Service connecting to those Pods.
A Deployment maintains the desired Pods, while a Service gives clients a stable endpoint.

One important limitation: a single-node local cluster is excellent for learning Pod replacement, but it cannot demonstrate surviving the loss of the only Node. Actual node-failure resilience requires multiple suitable Nodes and application design that supports recovery.

Before you start: tools and local cluster setup

You need a terminal, a text editor, an internet connection for downloading container images, and enough free resources to run a local cluster. The exact memory and CPU requirements depend on your operating system and cluster configuration.

Choose one of the following paths:

Option A: Docker Desktop

If you already use Docker Desktop, its built-in Kubernetes integration may be the easiest option.

  1. Open the Docker Desktop dashboard.
  2. Open the Kubernetes view and choose Create cluster. On some older versions, Kubernetes is enabled under Settings > Kubernetes.
  3. Choose the default single-node setup for this beginner tutorial. Newer Docker Desktop versions may also offer a multi-node option based on kind.
  4. Create the cluster and allow its components to start.

The exact labels can differ by Docker Desktop version. Refer to the current Docker Desktop Kubernetes guide (opens in a new tab) if your screen differs.

Option B: Minikube

Minikube (opens in a new tab) runs a local Kubernetes cluster on Windows, macOS, or Linux. Install Minikube and a supported virtualization or container driver, then run:

minikube start

If you already have Docker running and want to use it as the driver, Minikube also supports:

minikube start --driver=docker

Install kubectl separately if your environment does not provide it. The official kubectl installation guide (opens in a new tab) covers supported operating systems. Use a kubectl release within one minor version of your cluster’s API server.

Verify that kubectl reaches the cluster

Run:

kubectl version --client
kubectl config current-context
kubectl cluster-info
kubectl get nodes

kubectl version --client checks the tool on your computer. The other commands check which cluster you are using and whether it responds.

For the default local setups, you will typically see a Node named docker-desktop or minikube with STATUS set to Ready. A multi-node setup will show more than one Node.

If kubectl points to the wrong cluster, first inspect your available contexts:

kubectl config get-contexts

Do not blindly switch contexts on a computer that also has access to production infrastructure.

Hands-on: deploy your first Kubernetes application

We will use the official Nginx container image as a simple web-server example. It is a real containerized workload, but not a custom application we have built. Starting with a known image keeps the Kubernetes concepts easier to see.

Step 1: Create the Deployment YAML

Make a new folder named glimpz-kubernetes-demo. Inside it, create a file called deployment.yaml containing:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: glimpz-web-deployment
  labels:
    app: glimpz-web
spec:
  replicas: 3
  selector:
    matchLabels:
      app: glimpz-web
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxUnavailable: 0
      maxSurge: 1
  template:
    metadata:
      labels:
        app: glimpz-web
    spec:
      containers:
        - name: nginx-container
          image: nginx:stable-alpine
          ports:
            - containerPort: 80
          readinessProbe:
            httpGet:
              path: /
              port: 80
            initialDelaySeconds: 2
            periodSeconds: 5
          resources:
            requests:
              cpu: "50m"
              memory: "64Mi"
            limits:
              cpu: "250m"
              memory: "128Mi"

The important lines are:

  • kind: Deployment creates a Deployment rather than an unmanaged Pod.
  • replicas: 3 requests three Pods.
  • selector.matchLabels connects the Deployment to Pods carrying the app: glimpz-web label.
  • image specifies the container image to run.
  • readinessProbe checks whether Nginx is responding before a Pod is considered ready to receive Service traffic.
  • maxUnavailable: 0 and maxSurge: 1 aim to keep the existing replicas available during an update while permitting one extra Pod temporarily. They require sufficient spare cluster capacity.

The image tag is convenient for a learning environment. For production releases, use a version or digest that you have validated so the image cannot change unexpectedly when a tag moves.

Illustrative Deployment YAML excerpt leading to three ready Kubernetes Pods running Nginx.
You describe the desired state in YAML, and Kubernetes creates and maintains the requested replicas.

Step 2: Apply the Deployment and inspect your Pods

Open a terminal in the folder containing the YAML file:

kubectl apply -f deployment.yaml
kubectl rollout status deployment/glimpz-web-deployment
kubectl get deployments
kubectl get pods -l app=glimpz-web

The first command sends your desired state to the Kubernetes API. The rollout command waits for the Deployment to make progress. The last command lists only Pods carrying our demo label.

Once the images have downloaded and the Pods are ready, expect the Deployment to report 3/3 ready replicas. Pod names are generated and will not match one fixed example.

If a Pod is still Pending or ContainerCreating, give it a moment, then use the troubleshooting section below if it remains stuck.

Step 3: See self-healing in action

List the Pods first:

kubectl get pods -l app=glimpz-web

Copy one real Pod name from your output, then delete it. Replace YOUR_POD_NAME with that name; do not type the angle-bracket placeholder from a tutorial as a literal command.

kubectl delete pod YOUR_POD_NAME
kubectl get pods -l app=glimpz-web -w

Use Ctrl+C to stop the live watch.

You should observe the deleted Pod terminating and another Pod being created so the Deployment can return to three desired replicas. The exact timing varies with your laptop, image cache, and cluster state.

Why does this happen? The Deployment and ReplicaSet controllers continually reconcile what exists with what you asked for. Deleting a managed Pod does not change the replicas: 3 setting, so Kubernetes creates a replacement. This is one form of self-healing, not a guarantee that every software failure is automatically resolved.

Before-and-after Kubernetes diagram showing a deleted Pod replaced by a new ready Pod to restore three desired replicas.
When one managed Pod is deleted, the ReplicaSet works to restore the desired replica count.

Step 4: Create a Service so the app has a stable address

Pods are replaceable. Their individual IP addresses are not a reliable public entry point for your app.

In the same folder, create service.yaml:

apiVersion: v1
kind: Service
metadata:
  name: glimpz-web-service
spec:
  type: NodePort
  selector:
    app: glimpz-web
  ports:
    - name: http
      protocol: TCP
      port: 80
      targetPort: 80
      nodePort: 30080

The Service’s selector must match the labels on your Pods. Here, it selects all three replicas. port: 80 is the Service port, targetPort: 80 is the container’s listening port, and nodePort: 30080 requests a port on the cluster Nodes.

Apply it:

kubectl apply -f service.yaml
kubectl get services
kubectl get endpointslices -l kubernetes.io/service-name=glimpz-web-service

For the most predictable local browser test, run:

kubectl port-forward service/glimpz-web-service 8080:80

Keep that terminal open and visit http://localhost:8080 (opens in a new tab) in your browser. You should see the default Nginx welcome page. The port forwarding ends when you stop the command.

If you specifically want to try NodePort access:

  • On some Docker Desktop local cluster configurations, http://localhost:30080 works directly.
  • With Minikube, run minikube service glimpz-web-service and open the address it provides. On Docker-driver setups for Windows or macOS, Minikube may create a temporary tunnel that must remain open.

If port 30080 is already allocated or your cluster has a different allowed NodePort range, remove the nodePort line, apply the Service again, and use kubectl port-forward. NodePort is fine for a local exercise, but it is not a complete public production ingress setup.

Step 5: Scale from three Pods to five

Kubernetes separates the desired number of replicas from the physical containers that happen to be running.

Try manual scaling:

kubectl scale deployment/glimpz-web-deployment --replicas=5
kubectl rollout status deployment/glimpz-web-deployment
kubectl get pods -l app=glimpz-web

When sufficient resources are available, you should see five ready Pods. They all remain behind the same Service.

Important: Your saved deployment.yaml still says replicas: 3. Change that line to replicas: 5 if you want your file to represent the current desired state. Otherwise, a later kubectl apply -f deployment.yaml can reset the count to three.

This is manual scaling, not automatic scaling. An HPA can adjust replicas based on configured metrics, but you have not installed or configured one in this tutorial.

Step 6: Roll out an image update and know how to undo it

A Deployment supports gradual updates by creating replacement Pods from a new Pod template.

In deployment.yaml, keep your chosen replica count and change the image from:

image: nginx:stable-alpine

to:

image: nginx:mainline-alpine

These are maintained Nginx release-channel tags, so this exercise demonstrates a change in image reference. It is not a recommendation to update production software without reviewing compatibility and pinning a tested release.

Apply your edited file and monitor the rollout:

kubectl apply -f deployment.yaml
kubectl rollout status deployment/glimpz-web-deployment
kubectl rollout history deployment/glimpz-web-deployment
kubectl get pods -l app=glimpz-web

If you need to return to the previous Deployment revision:

kubectl rollout undo deployment/glimpz-web-deployment
kubectl rollout status deployment/glimpz-web-deployment

A rollback changes the live Deployment, but it does not edit your local YAML file. Change the file back too if you want later applies to preserve the rollback.

Rolling updates can minimize interruptions. They do not guarantee zero downtime for every application. Readiness checks, enough healthy replicas, rollout settings, and the application’s own behavior all matter.

Step 7: Clean up after the tutorial

When you are finished, delete the Kubernetes objects created by these two files:

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

Check that they are gone:

kubectl get deployments
kubectl get services

This removes the example resources, not your entire Kubernetes cluster. If you used Minikube and no longer need the cluster, minikube stop stops it without deleting it.

Everyday kubectl commands worth keeping

What you want to doCommand
See your current clusterkubectl config current-context
List Nodeskubectl get nodes
List Podskubectl get pods
List Deploymentskubectl get deployments
List Serviceskubectl get services
Watch Pods changekubectl get pods -w
Inspect why a Pod is failingkubectl describe pod POD_NAME
View container logskubectl logs POD_NAME
Open a shell in an Nginx Podkubectl exec -it POD_NAME -- /bin/sh
Check rollout progresskubectl rollout status deployment/glimpz-web-deployment
See recent namespace eventskubectl get events --sort-by=.metadata.creationTimestamp
List common workload resourceskubectl get all

kubectl get all does not literally show every resource type in the cluster. Most commands above operate in the current namespace unless you add a namespace flag.

Troubleshooting: what if the tutorial does not work?

SymptomWhat it may meanWhat to try
kubectl get nodes cannot connectNo cluster is running, or the wrong context is activeStart your cluster and inspect kubectl config get-contexts
Pod stays in PendingInsufficient CPU or memory, or a scheduling issueRun kubectl describe pod POD_NAME and read the Events section
ImagePullBackOffThe image cannot be downloadedCheck the image name, internet access, and Pod Events
CrashLoopBackOffA container repeatedly starts and failsCheck kubectl logs POD_NAME --previous and kubectl describe pod POD_NAME
Service exists but browser shows nothingWrong port, selector, or no ready PodsCompare Pod labels and Service selectors; try kubectl port-forward
An update will not finishNew Pods are not ready or cannot be scheduledCheck kubectl get pods, kubectl describe deployment, and resource capacity

A useful debugging habit is to read Events before changing random settings. Kubernetes often reports why it could not pull an image, schedule a Pod, or pass a readiness check.

Kubernetes questions beginners often ask

Is Kubernetes a replacement for Docker?

No. Docker is commonly used to build container images. Kubernetes runs containerized applications and manages their lifecycle across Nodes using compatible container runtimes, such as containerd. You can use Docker in your development workflow and Kubernetes for deployment.

Does Kubernetes automatically scale when traffic increases?

Not just because you created a Deployment. Your five-Pod example used manual scaling. To automate replica counts, configure an HPA with supported resource or custom metrics and make sure the necessary metrics components are available.

Is a three-Pod Deployment highly available on a laptop?

Not in the sense of surviving a laptop or single-Node failure. Running three Pods on one Node can demonstrate replacement and replica management, but all three depend on that Node. Production resilience needs more than a replica number.

Why use a Service instead of connecting directly to a Pod?

Pods can be deleted, replaced, or assigned new IP addresses. A Service gives you a stable name and networking abstraction that selects the current matching Pods, so clients do not need to know each Pod’s identity.

What to learn after this Kubernetes tutorial

You now have the foundations of a Kubernetes workflow: define a desired state in YAML, apply it, inspect the result, expose a Service, observe recovery, change replicas, and perform a rolling update.

From here, the most useful next topics are ConfigMaps and Secrets for configuration, PersistentVolumes for data that must survive Pod replacement, Ingress or Gateway API for HTTP routing, health probes, resource requests and limits, and HorizontalPodAutoscaler for metrics-based scaling. For production environments, compare managed Kubernetes services such as Amazon EKS, Google Kubernetes Engine, and Azure Kubernetes Service with simpler hosting options before deciding that Kubernetes is necessary.

Try one small improvement yourself: replace the Nginx demo image with a container image you built in Docker, publish it to a registry your cluster can access, and update the Deployment’s image and port settings. That connects this tutorial to the container skills you already learned.

References and further reading

Glimpz AI Editorial Team

Sharing helpful ideas and clear explanations from the Glimpz AI team.

About our editorial team →

Join the conversation

Keep comments respectful and relevant. Please don't share private or sensitive information.

Discussion (0)

Join the conversation