Kubernetes Tutorial for Beginners: Deploy, Scale and Update Your First App

Kubernetes has a reputation for being hard, largely because tutorials throw twenty new terms at you before anything runs. This Kubernetes tutorial for beginners takes the opposite approach. You learn the handful of ideas that matter, and then you use each one on a real cluster running on your own laptop.

You should already know what a container is. If not, work through our Docker Compose tutorial first. Commands here are the standard ones from the Kubernetes documentation, but output and flags can vary a little between versions.

What is Kubernetes?

Kubernetes, often written K8s, is an open-source platform for running containers across a group of machines. Google originally developed it, and the Cloud Native Computing Foundation now maintains it.

Its central idea is desired state. You do not tell it “start three containers”. You declare “there should always be three copies of this app”. Kubernetes compares that statement with reality and keeps fixing any difference. If a container crashes or a machine dies, it starts a replacement without anyone being paged.

Do you need Kubernetes?

Often, you do not, at least not yet. Be honest about this before you take on the complexity.

Learning it is still valuable, because it has become a common skill in DevOps and platform roles. In production, most teams use a managed service such as Amazon EKS, Google GKE or Azure AKS, rather than running the control plane themselves.

How Kubernetes works

A cluster has two parts: a control plane that makes decisions, and worker nodes that run your applications.

When you apply a manifest, kubectl sends it to the API server, which stores it in etcd. Controllers notice the change and create Pods, the scheduler assigns them to nodes, and each node’s kubelet starts the containers. You do not need to memorise this today, but it explains why things happen in the order they do.

Core objects you need first

• Pod: the smallest deployable unit, made up of one or more containers that share a network address. Pods are disposable, and you rarely create them directly.
• Deployment: describes how many copies of a Pod to run and which image to use. It handles replacement and updates.
• Service: gives a changing group of Pods one stable name and address, and balances traffic across them.
• Namespace: a way to divide one cluster into logical groups, such as by team or environment.
• ConfigMap and Secret: hold configuration and sensitive values outside the image.

Start a local cluster

You need three things: a container runtime such as Docker Desktop, kubectl (the command-line client) and minikube (which runs a small cluster on your machine). Follow the official install steps for your operating system, and then run:

minikube start
kubectl get nodes

You should see one node with the status Ready. That single node plays both roles here, which is fine for learning. Alternatives such as kind and k3d work similarly.

Deploy an app

Create a file called deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 2
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: nginx
          image: nginx:1.27
          ports:
            - containerPort: 80
          resources:
            requests:
              cpu: 100m
              memory: 64Mi
            limits:
              memory: 128Mi

Every manifest has the same four top-level fields: apiVersion, kind, metadata and spec. The part to study is the connection between selector.matchLabels and template.metadata.labels. Labels are how Kubernetes objects find each other, so a mismatch here is an error. The resource requests tell the scheduler how much room the Pod needs.

Apply it and watch what happens:

kubectl apply -f deployment.yaml
kubectl get deployments
kubectl get pods -l app=web

Two Pods should reach Running status within a minute or so, after the image has downloaded.

Expose it with a Service

Each Pod has its own IP address, but that address disappears along with the Pod. A Service solves this. Create service.yaml:

apiVersion: v1
kind: Service
metadata:
  name: web
spec:
  type: NodePort
  selector:
    app: web
  ports:
    - port: 80
      targetPort: 80

kubectl apply -f service.yaml
minikube service web --url

The second command prints a local URL. Open it, and you should see the nginx welcome page. Here are the main Service types:

For websites with many routes and domains, you would also add an Ingress or the newer Gateway API, which routes HTTP traffic to Services.

Scale and watch it self-heal

This is where Kubernetes starts to feel useful. Scale up with a single command:

kubectl scale deployment web --replicas=4
kubectl get pods -l app=web

Now test self-healing. Delete a Pod, using a name from the list above:

kubectl delete pod <pod-name>
kubectl get pods -l app=web

A replacement appears almost at once, because the Deployment still wants four copies. Note that the scale command changed the live cluster but not your file. Update replicas in the YAML as well, or your next apply will set it back to two.

Roll out an update

Change the image to nginx:1.28 in deployment.yaml and apply it again. Kubernetes performs a rolling update, starting new Pods and removing old ones gradually, so the app stays available.

kubectl apply -f deployment.yaml
kubectl rollout status deployment/web
kubectl rollout history deployment/web

If the new version is bad, go back to the previous one:

kubectl rollout undo deployment/web

Teams usually automate this from a pipeline, where a merge builds an image and updates the manifest. Our guides on what is CI/CD and GitHub Actions explain how that works.

Configuration and health probes

Keep settings outside your image, so one image can run in every environment. Add environment variables from a ConfigMap, and health checks that tell Kubernetes when a container is working:

        - name: nginx
          image: nginx:1.28
          envFrom:
            - configMapRef:
                name: web-config
          readinessProbe:
            httpGet:
              path: /
              port: 80
          livenessProbe:
            httpGet:
              path: /
              port: 80

A failing readiness probe stops traffic reaching the Pod until it recovers. A failing liveness probe restarts the container. Create the ConfigMap with kubectl create configmap web-config --from-literal=LOG_LEVEL=info before you apply this change. For passwords, use a Secret, and remember that Secrets are only base64-encoded by default, so restrict access to them and consider encryption at rest.

Debug common errors

Almost every beginner problem starts with the same three commands:

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

Read the Events section at the bottom of the describe output, because it usually names the cause. Use --previous to see logs from a container that has already crashed.

When you finish, clean up with kubectl delete -f deployment.yaml -f service.yaml, and then minikube stop.

Final thoughts

You have now used the core Kubernetes loop: declare a state, apply it and let the cluster keep it true. Everything else builds on that. As your next step, deploy one of your own containers, add a real readiness endpoint, and connect it to a database through a ClusterIP Service. After that, look at Helm, Ingress and autoscaling.

Frequently asked questions

Keep learning