kubectl replace --force: Recreate a Resource

By Daniel Zoghalchali·Latchkey

kubectl replace overwrites a resource with a full manifest; with --force it deletes and recreates the object to apply otherwise-immutable changes.

Some fields cannot be patched or applied in place. replace --force is the escape hatch, at the cost of a delete-and-recreate.

What it does

kubectl replace overwrites the live object with the provided manifest in a single update; the manifest must be complete. --force makes it delete the existing object and create it anew, which is how you change fields the API marks immutable (for example a Job template or a Service clusterIP).

Common usage

Terminal

kubectl replace -f deploy.yaml
# delete and recreate to bypass immutable fields
kubectl replace --force -f job.yaml
# recreate immediately, skipping graceful termination
kubectl replace --force --grace-period=0 -f job.yaml

Options

Flag	What it does
-f, --filename	Complete manifest to replace with
--force	Delete then recreate the resource
--grace-period=<s>	Termination grace seconds (0 with --force = immediate)
--cascade=<mode>	How dependents are handled on the delete
--dry-run=server	Validate against the server without persisting

In CI

replace --force is disruptive: it removes the object (and, depending on --cascade, its pods) before recreating, so a Service loses its endpoints and a Deployment restarts. Prefer kubectl apply or kubectl patch first; reach for replace --force only when you hit a genuinely immutable field. Validate with --dry-run=server beforehand.

Common errors in CI

"The <Kind> \"<name>\" is invalid: ... field is immutable" is exactly what drives people to --force. "error: error when replacing ... resourceVersion should not be set" means a plain replace got a manifest missing the live resourceVersion; use apply or add --force. "Error from server (NotFound)" with replace means the object does not exist yet; use create or apply instead.

Using this in CI

A runner has no kubeconfig, no cached context, and no interactive auth. Every kubectl invocation in CI needs the context supplied explicitly, and most confusing CI failures here are the command running against the wrong cluster or no cluster at all.

Terminal

# never rely on the ambient context on a runner
kubectl --context "$KUBE_CONTEXT" -n "$NAMESPACE" get pods

# confirm what you are actually connected to before mutating anything
kubectl config current-context
kubectl cluster-info

# fail fast instead of hanging on an unreachable API server
kubectl --request-timeout=30s get nodes

Frequently asked questions

kubectl replace --force: Recreate a Resource?

Some fields cannot be patched or applied in place. replace --force is the escape hatch, at the cost of a delete-and-recreate.

What it does?

kubectl replace overwrites the live object with the provided manifest in a single update; the manifest must be complete. --force makes it delete the existing object and create it anew, which is how you change fields the API marks immutable (for example a Job template or a Service clusterIP).

In CI?

replace --force is disruptive: it removes the object (and, depending on --cascade, its pods) before recreating, so a Service loses its endpoints and a Deployment restarts. Prefer kubectl apply or kubectl patch first; reach for replace --force only when you hit a genuinely immutable field. Validate with --dry-run=server beforehand.

Common errors in CI?

"The <Kind> \"<name>\" is invalid: ... field is immutable" is exactly what drives people to --force. "error: error when replacing ... resourceVersion should not be set" means a plain replace got a manifest missing the live resourceVersion; use apply or add --force.