Desired state vs actual state reconciliation in Kubernetes - CLI Comparison

Introduction

When you tell Kubernetes how you want your app to run, it keeps checking if the real situation matches your instructions. If something changes or breaks, Kubernetes fixes it automatically to match what you asked for.

When you want your app to always run with a certain number of copies, even if some copies crash.

When you update your app and want Kubernetes to replace old versions with new ones smoothly.

When you want to recover automatically if a server or container stops working.

When you want to make sure your app configuration stays the same even if someone changes it by mistake.

When you want to scale your app up or down and have Kubernetes handle the changes.

Config File - deployment.yaml

deployment.yaml

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

This file tells Kubernetes you want 3 copies of an Nginx app running. Kubernetes will keep checking and fixing the number of copies to always be 3.

replicas: number of copies you want.

selector: how Kubernetes finds the pods it manages.

template: the pod setup including container image and ports.

Commands

This command tells Kubernetes to create or update the deployment based on the file. Kubernetes will start 3 pods as requested.

Terminal

kubectl apply -f deployment.yaml

Expected Output

deployment.apps/example-deployment created

This command lists all pods with the label app=example-app to check if 3 pods are running as desired.

Terminal

kubectl get pods -l app=example-app

Expected Output

NAME                                  READY   STATUS    RESTARTS   AGE

example-deployment-6f7c9d7f5f-abc12   1/1     Running   0          10s

example-deployment-6f7c9d7f5f-def34   1/1     Running   0          10s

example-deployment-6f7c9d7f5f-ghi56   1/1     Running   0          10s

→

-l - Filter pods by label

This command deletes one pod manually to simulate a failure. Kubernetes will notice and create a new pod to keep 3 running.

Terminal

kubectl delete pod example-deployment-6f7c9d7f5f-abc12

Expected Output

pod "example-deployment-6f7c9d7f5f-abc12" deleted

Check again to see Kubernetes created a new pod to replace the deleted one, keeping the desired state.

Terminal

kubectl get pods -l app=example-app

Expected Output

NAME                                  READY   STATUS    RESTARTS   AGE

example-deployment-6f7c9d7f5f-def34   1/1     Running   0          30s

example-deployment-6f7c9d7f5f-ghi56   1/1     Running   0          30s

example-deployment-6f7c9d7f5f-jkl78   1/1     Running   0          10s

→

-l - Filter pods by label

Key Concept

Kubernetes constantly compares the desired state you set with the actual state and fixes differences automatically.

Common Mistakes

Not using labels correctly in the deployment selector and pod template.

Kubernetes cannot match pods to the deployment, so it won't manage them properly.

Ensure the selector labels exactly match the pod template labels.

Manually deleting pods and expecting the deployment to stop creating new ones.

Kubernetes will recreate pods to maintain the desired number, so manual deletion only causes temporary removal.

Scale down the deployment replicas if you want fewer pods.

Summary

Use a deployment YAML file to tell Kubernetes how many copies of your app you want.

Apply the deployment with kubectl apply to create or update the app pods.

Kubernetes watches the actual pods and fixes any difference from the desired state automatically.