Desired replicas vs actual replicas in Kubernetes - CLI Comparison

Introduction

When you run an app on Kubernetes, you tell it how many copies (replicas) you want. Kubernetes then works to make sure the actual number of running copies matches what you asked for. This helps keep your app available and balanced.

When you want to make sure your app always has a certain number of copies running for reliability.

When you update your app and want to increase or decrease the number of running copies smoothly.

When you want to check if Kubernetes is keeping your app healthy by matching the desired number of copies.

When you notice your app is slow or down and want to see if the number of running copies is less than expected.

When you want to scale your app up or down based on user demand.

Config File - deployment.yaml

deployment.yaml

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

This file tells Kubernetes to run 3 copies (replicas) of an Nginx app. The replicas field is the desired number of copies. Kubernetes will try to keep the actual running copies equal to this number.

The selector and template define which pods belong to this deployment and what each pod runs.

Commands

This command creates or updates the deployment with the desired number of replicas defined in the file.

Terminal

kubectl apply -f deployment.yaml

Expected Output

deployment.apps/example-deployment created

This command shows the deployment status, including desired replicas and actual replicas running.

Terminal

kubectl get deployment example-deployment

Expected Output

NAME                 READY   UP-TO-DATE   AVAILABLE   AGE

example-deployment   3/3     3            3           10s

This command gives detailed information about the deployment, including events if replicas are not matching.

Terminal

kubectl describe deployment example-deployment

Expected Output

Name:                   example-deployment

Namespace:              default

CreationTimestamp:      Thu, 01 Jun 2023 12:00:00 +0000

Labels:                 <none>

Annotations:            <none>

Selector:               app=example-app

Replicas:               3 desired | 3 updated | 3 total | 3 available | 0 unavailable

StrategyType:           RollingUpdate

Pods Status:            3 Running / 0 Waiting / 0 Succeeded / 0 Failed

Events:

  Type    Reason             Age   From                   Message

  ----    ------             ----  ----                   -------

  Normal  ScalingReplicaSet  10s   deployment-controller  Scaled up replica set example-deployment-xxxxx to 3

This command lists all pods with the label app=example-app to see the actual running copies.

Terminal

kubectl get pods -l app=example-app

Expected Output

NAME                                   READY   STATUS    RESTARTS   AGE

example-deployment-xxxxx-abcde         1/1     Running   0          15s

example-deployment-xxxxx-fghij         1/1     Running   0          15s

example-deployment-xxxxx-klmno         1/1     Running   0          15s

Key Concept

If you remember nothing else from this pattern, remember: Kubernetes always tries to keep the actual number of running replicas equal to the desired number you set.

Common Mistakes

Not checking the deployment status after applying changes.

You might think your app is running the desired number of copies, but Kubernetes may still be creating or restarting pods.

Always run 'kubectl get deployment' or 'kubectl describe deployment' to verify the actual replicas match the desired replicas.

Setting replicas to zero unintentionally.

This stops all pods, making your app unavailable.

Double-check the replicas field in your deployment file before applying changes.

Ignoring pod labels when checking pods.

You may see pods unrelated to your deployment, causing confusion about actual replicas.

Use label selectors like '-l app=example-app' to list only the pods belonging to your deployment.

Summary

Create or update a deployment with a desired number of replicas using 'kubectl apply -f deployment.yaml'.

Check the deployment status with 'kubectl get deployment' to see desired vs actual replicas.

Use 'kubectl describe deployment' for detailed info and events about replica changes.

List pods with matching labels to see actual running copies.