kubectl replace --force: Recreate a Resource
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
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.yamlOptions
| 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.