Inspecting Deployment Status

When a rolling update is triggered or a new Deployment is created in Kubernetes, verifying that the process unfolds as intended is a primary management task. Kubernetes provides several kubectl commands to inspect the state of Deployments, monitor the progress of rollouts, and view revision history. Understanding these commands is essential for managing application lifecycles and troubleshooting issues.

High-Level Status Check with kubectl get

The quickest way to check the status of your Deployments is with the kubectl get deployments command. This gives you a high-level summary of all Deployments in the current namespace.

$ kubectl get deployments
NAME               READY   UP-TO-DATE   AVAILABLE   AGE
nginx-deployment   3/3     3            3           15m

Let's break down the columns in this output:

• NAME: The name of the Deployment object.
• READY: Shows the ratio of current replicas to desired replicas that are in a ready state. In this example, 3/3 indicates that all three desired replicas are running and have passed their readiness probes.
• UP-TO-DATE: The number of replicas that have been updated to the latest version defined in the Deployment's template. During a rolling update, this number will increment as new Pods are created.
• AVAILABLE: The number of replicas that are available to serve traffic. An available replica is one that is running and has been ready for at least minReadySeconds (if specified).
• AGE: The total time elapsed since the Deployment was created.

If you initiate a rolling update, you can use the -w or --watch flag to see these values change in real time.

$ kubectl get deployment nginx-deployment --watch
NAME               READY   UP-TO-DATE   AVAILABLE   AGE
nginx-deployment   3/3     3            3           15m
nginx-deployment   2/3     3            2           16m
nginx-deployment   3/4     3            3           16m
nginx-deployment   4/4     4            4           16m
nginx-deployment   3/3     3            3           17m

Detailed Inspection with kubectl describe

For a much more detailed view of a Deployment's state, use the kubectl describe deployment command. This command provides comprehensive information, including labels, annotations, replica counts, rolling update strategy, and a log of recent events.

$ kubectl describe deployment nginx-deployment

The output is verbose, but a few sections are particularly important for inspection:

Name:                   nginx-deployment
Namespace:              default
CreationTimestamp:      ...
Labels:                 app=nginx
Annotations:            deployment.kubernetes.io/revision: '2'
Selector:               app=nginx
Replicas:               3 desired | 3 updated | 3 total | 3 available | 0 unavailable
StrategyType:           RollingUpdate
MinReadySeconds:        0
RollingUpdateStrategy:  25% max unavailable, 25% max surge
...
Events:
  Type    Reason             Age    From                   Message
  ----    ------             ----   ----                   -------
  Normal  ScalingReplicaSet  5m3s   deployment-controller  Scaled up replica set nginx-deployment-7b8d4f5c6f to 3
  Normal  ScalingReplicaSet  1m20s  deployment-controller  Scaled up replica set nginx-deployment-6c7b5d6f8g to 1
  Normal  ScalingReplicaSet  1m18s  deployment-controller  Scaled down replica set nginx-deployment-7b8d4f5c6f to 2
  Normal  ScalingReplicaSet  1m18s  deployment-controller  Scaled up replica set nginx-deployment-6c7b5d6f8g to 2
  Normal  ScalingReplicaSet  1m16s  deployment-controller  Scaled down replica set nginx-deployment-7b8d4f5c6f to 1
  Normal  ScalingReplicaSet  1m16s  deployment-controller  Scaled up replica set nginx-deployment-6c7b5d6f8g to 3
  Normal  ScalingReplicaSet  1m14s  deployment-controller  Scaled down replica set nginx-deployment-7b8d4f5c6f to 0

Important areas to examine in the output include:

• Replicas: This line provides a detailed breakdown of the Pod states. It shows the desired count alongside the number of updated, total, available, and unavailable Pods. During a rollout, these numbers will fluctuate until the desired state is reached.
• StrategyType: Confirms the update strategy being used, which is RollingUpdate by default.
• Events: This is often the most useful section for troubleshooting. It provides a chronological log of actions taken by the Deployment controller. In the example above, you can see the controller scaling down the old ReplicaSet (nginx-deployment-7b8d4f5c6f) while simultaneously scaling up the new one (nginx-deployment-6c7b5d6f8g) until the transition is complete.

A Deployment manages multiple ReplicaSets during a rolling update. Here, a new ReplicaSet controls Pods with an updated image, while the old ReplicaSet is scaled down as its Pods are terminated.

Monitoring a Live Rollout

While kubectl get --watch shows state changes, the kubectl rollout status command is designed specifically to monitor a Deployment update until it completes. The command blocks and provides real-time progress updates, making it ideal for use in automated scripts or CI/CD pipelines.

$ kubectl rollout status deployment/nginx-deployment
Waiting for deployment "nginx-deployment" rollout to finish: 2 out of 3 new replicas have been updated...
Waiting for deployment "nginx-deployment" rollout to finish: 2 out of 3 new replicas have been updated...
Waiting for deployment "nginx-deployment" rollout to finish: 1 old replicas are pending termination...
Waiting for deployment "nginx-deployment" rollout to finish: 1 old replicas are pending termination...
deployment "nginx-deployment" successfully rolled out

If the rollout succeeds, the command exits with a status code of 0. If the rollout fails or times out (defaulting to 10 minutes), it will exit with a non-zero status code, signaling a problem.

Viewing Deployment History

Deployments maintain a revision history of changes, which is what enables you to roll back to a previous version. You can view this history with the kubectl rollout history command.

$ kubectl rollout history deployment/nginx-deployment
deployment.apps/nginx-deployment 
REVISION  CHANGE-CAUSE
1         <none>
2         kubectl set image deployment/nginx-deployment nginx=nginx:1.17.1 --record=true

Each time a Deployment's Pod template (the .spec.template field) is updated, a new revision is created.

The CHANGE-CAUSE column is particularly helpful for understanding why each revision was created. By default, it is <none>. To populate it automatically, you can add the kubernetes.io/change-cause annotation to your Deployment manifest when applying changes.

For example, you could apply a manifest update with kubectl apply and then immediately annotate it:

# Apply the updated YAML file
$ kubectl apply -f nginx-deployment-v3.yaml

# Annotate the deployment with a descriptive message
$ kubectl annotate deployment/nginx-deployment kubernetes.io/change-cause="Update to nginx 1.19.0"

This practice makes your deployment history much more meaningful and simplifies identifying which revision to roll back to if an issue occurs.

To get more details about a specific revision, add the --revision flag:

$ kubectl rollout history deployment/nginx-deployment --revision=2

This command will show you the Pod template and other details associated with that particular version of your application configuration.