Introduction

Kubernetes does not have a native restart button for a Deployment object. What actually causes a rolling restart is a change to the Pod template inside the Deployment spec, which makes the Deployment controller create a new ReplicaSet and replace the old Pods.

Restarting Means Patching the Pod Template

When you run kubectl rollout restart deployment/my-app, kubectl is really sending a patch through the API server. The common patch updates the kubectl.kubernetes.io/restartedAt annotation under spec.template.metadata.annotations.

That location matters. If you patch the top-level Deployment metadata instead, Kubernetes updates the object but does not restart the Pods because the Pod template hash does not change.

Use the API Server Through kubectl proxy

One easy way to call the API server directly is to start a local proxy and send an HTTP patch request to it.

kubectl proxy --port=8001

In another terminal, patch the Deployment:

1curl -X PATCH \
2  -H "Content-Type: application/strategic-merge-patch+json" \
3  http://127.0.0.1:8001/apis/apps/v1/namespaces/default/deployments/my-app \
4  -d '{
5    "spec": {
6      "template": {
7        "metadata": {
8          "annotations": {
9            "kubectl.kubernetes.io/restartedAt": "2026-03-07T12:00:00Z"
10          }
11        }
12      }
13    }
14  }'

Once that patch is accepted, the Deployment controller notices that the Pod template changed and begins a rolling update.

Verify That the Restart Actually Happened

After sending the patch, check rollout status and inspect the Pods:

kubectl rollout status deployment/my-app -n default
kubectl get pods -n default -l app=my-app
kubectl describe deployment my-app -n default

You should see new Pods being created and old Pods terminating according to the Deployment strategy. In kubectl describe deployment, the annotation change should also be visible.

If you prefer a direct API check, request the Deployment object from the proxy:

curl http://127.0.0.1:8001/apis/apps/v1/namespaces/default/deployments/my-app

That lets you confirm the annotation value and verify that the change reached the API server.

Direct API Calls Without kubectl proxy

You can also call the API server directly with a bearer token and the cluster CA certificate. That is common inside automation or from code running in the cluster, but it adds more setup because you need authentication and TLS details.

The patch body is the same either way. The important part is still updating spec.template, not just touching top-level metadata.

For scripted automation, the direct call path is often:

• read a service account token
• send an authenticated PATCH request to the API server
• use a patch type that Kubernetes accepts for Deployment updates

The mechanism is the same as the proxy example, only the transport details differ.

Common Pitfalls

• Patching metadata.annotations on the Deployment instead of spec.template.metadata.annotations. The Deployment changes, but no rollout happens.
• Reusing the same annotation value every time. If the Pod template does not actually change, Kubernetes has nothing to roll out.
• Using the wrong Content-Type for the patch request. Kubernetes may reject the patch or interpret it differently than expected.
• Forgetting the namespace in the API path. A valid Deployment name in the wrong namespace looks like a missing resource.
• Sending the patch without sufficient RBAC permissions. Access to read Deployments does not always include permission to patch them.

Summary

• A Deployment restart is triggered by changing the Pod template, not by a special restart API.
• The usual restart patch updates spec.template.metadata.annotations.
• 'kubectl proxy is a convenient way to send the patch through the API server with local credentials.'
• Always verify the rollout with kubectl rollout status or by inspecting the Deployment and Pods directly.
• If the Pods do not restart, check the patch path, annotation value, namespace, and permissions first.