Introduction

Updating a Dockerfile does not change anything in Kubernetes by itself. The cluster only reacts when a new image exists in a registry and a workload is updated to use that image, so the real deployment workflow is build, push, update the workload, and verify the rollout.

Build and Push a New Image

Kubernetes cannot deploy an image that only exists on your laptop. After editing the Dockerfile, build a fresh image and push it to the registry your cluster can reach.

Use an immutable tag whenever possible:

1IMAGE=registry.example.com/myapp
2TAG=$(git rev-parse --short HEAD)
3
4docker build -t ${IMAGE}:${TAG} .
5docker push ${IMAGE}:${TAG}

An immutable tag such as a commit SHA makes it clear exactly what is running. Mutable tags such as latest make deployments harder to reason about and harder to roll back safely.

Update the Kubernetes Workload

Pushing a new image is not enough. You still need to update the Deployment, StatefulSet, or other controller so Kubernetes knows a new rollout is required.

Imperative example:

kubectl -n app set image deployment/myapp myapp=${IMAGE}:${TAG}
kubectl -n app rollout status deployment/myapp

Declarative example:

kubectl apply -f k8s/deployment.yaml
kubectl -n app rollout status deployment/myapp

In GitOps systems, the same idea applies except the image reference is changed in Git and then reconciled by the controller.

Verify What the Cluster Is Actually Running

A completed rollout status is necessary, but it is not enough by itself. Confirm that the pods actually reference the image you intended:

kubectl -n app get pods -l app=myapp \
  -o jsonpath='{range .items[*]}{.metadata.name}{" -> "}{.spec.containers[0].image}{"\n"}{end}'

If you need the resolved image ID:

kubectl -n app get pod POD_NAME \
  -o jsonpath='{.status.containerStatuses[0].imageID}'

Then run smoke tests against the service. A rollout that completes successfully but serves broken traffic is still a failed deployment.

“Redeploy Everything” Is Usually the Wrong Default

Most Dockerfile changes affect one workload, not the whole cluster. Restarting or redeploying everything is usually more risk than benefit.

Broad redeploys make sense when:

• a shared base image has a critical security update
• a runtime or sidecar pattern changed across many services
• a cluster-wide incident requires broad restarts

Even then, staged rollouts are usually safer than restarting the entire environment blindly.

Understand rollout restart

kubectl rollout restart restarts pods, but it does not change the image reference in the spec:

kubectl -n app rollout restart deployment/myapp

This is useful when the manifest already points at the desired image tag and you simply need fresh pods. It is not a substitute for updating to a newly built immutable image tag.

Plan Rollback Before Deployment

Every rollout should have a rollback path:

kubectl -n app rollout history deployment/myapp
kubectl -n app rollout undo deployment/myapp

If the rollout behaves badly, gather details quickly:

kubectl -n app describe deployment/myapp
kubectl -n app get events --sort-by=.metadata.creationTimestamp | tail -n 30

The goal is not only to revert but also to confirm the previous version is healthy again after the rollback.

Common Pitfalls

The biggest mistake is rebuilding the image locally and forgetting to push it to the registry.

Another issue is relying on mutable tags and assuming every node pulled the newest content. That makes it hard to know what is really running.

People also say "redeploy everything" when the correct operational move is to update only the workload affected by the Dockerfile change.

Finally, a restart is not the same as an image update. If the workload spec never changed, Kubernetes may simply restart pods on the same old image.

Summary

• After changing a Dockerfile, build and push a new image first.
• Update the Kubernetes workload explicitly so the cluster uses that image.
• Prefer immutable image tags for traceable and safe rollouts.
• Verify the running image and smoke-test the service after rollout.
• Redeploy only what changed unless you have a clear cluster-wide reason to do more.