kubectl-replace

Replace the resource using the resource definition file

$ kubectl replace [[-f|--filename]] [path/to/file.yml]

$ kubectl replace [[-f|--filename]] -

$ kubectl replace [[-f|--filename]] [path/to/file.yml] --force

kubectl replace (-f FILENAME | -R DIRECTORY | stdin) [options]

-f, --filename=[]
    Filename, directory, or URL to file(s) containing resource definitions to replace

-R, --recursive
    Process directory specified by --filename recursively

--allow-missing-template-keys=false
    Allow missing template keys; adds them as null if true

--cascade=background
    Deletion cascade policy: background, foreground, orphan (default background)

--dry-run=client
    Dry run mode: client, server, none

-l, --selector=string
    Selector (label query) to filter resources

--force
    Force immediate replacement by evicting pods (deletes and recreates)

--grace-period=30
    Period (seconds) to wait for pod termination before force delete

--timeout=0
    Timeout for deletion/replacement operations

--output=YAML
    Output format: json, yaml, name, wide, etc.

-o, --output=
    Output format (shorthand for --output)

kubectl replace updates a Kubernetes resource by completely overwriting its configuration with the provided file or stdin content. Unlike kubectl apply, which performs strategic merge patches to reconcile changes declaratively, replace substitutes the entire object spec, potentially removing unspecified fields and causing service disruptions or data loss.

It accepts JSON or YAML input, processing files with .yaml, .yml, or .json extensions. Use -f for single files, -R for recursive directories, or pipe from stdin. The command triggers a server-side replace operation, which fails if the resource's UID mismatches unless --force is used for eviction-based replacement.

Ideal for imperative updates or resetting resources to a known state, but risky for production workloads due to non-graceful field overwrites. Always verify input manifests match the resource's API version and schema to avoid validation errors.

kubectl replace overwrites entire spec; omitted fields are deleted. Avoid in production—use kubectl apply instead. --force risks downtime by force-evicting workloads.

# Replace from file:
kubectl replace -f pod.yaml

# Force replace pod:
kubectl replace --force -f pod.json

# From stdin:
cat config.yaml | kubectl replace -f -

0: Success
1: Error (invalid args, API failure, etc.)

Part of kubectl since Kubernetes v1.0 (2014). Evolved with API versioning; --force added later for eviction support. Maintained by Kubernetes SIG-CLI under CNCF.

kubectl-apply(1), kubectl-patch(1), kubectl-edit(1), kubectl-delete(1)