kubectl-replace

Replace the resource using the resource definition file

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

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

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

kubectl replace -f FILENAME | -k DIRECTORY [options]

-f, --filename=FILENAME
    Path to the file(s) or directory(ies) containing the resource configuration to replace. Can be a single file, a directory, or a URL. Accepts multiple paths separated by commas.

-k, --kustomize=DIRECTORY
    Path to a Kustomize directory. kubectl replace will use the Kustomize output as the new resource configuration.

--force
    If true, delete and then re-create the resource. Default is false (attempts an in-place update).

--cascade=boolean
    If true and --force is used, delete all dependents of the resource. Default is true. Set to false to orphan dependents.

--grace-period=seconds
    Grace period in seconds for deletion when --force is used. Default is -1 (server-defined).

--timeout=duration
    The length of time to wait before giving up on a delete operation when --force is used (e.g., '5s', '1m'). Default is 0 (no timeout).

--dry-run=mode
    If set, only print the object that would be sent without sending it. Valid modes are client, server, and none.

-o, --output=format
    Output format after the command completes (e.g., json, yaml, name, wide).

--recursive
    Process files in subdirectories found in the path specified by --filename or --kustomize. Default is false.

The kubectl replace command updates an existing Kubernetes resource with a new configuration provided from a local file or standard input. It is a direct, imperative operation.

By default, replace attempts an in-place update of the resource. If an in-place update isn't possible (e.g., due to immutable fields) or the --force flag is used, it will first delete the existing resource and then create a new one with the provided configuration. This delete-and-recreate behavior can cause temporary service disruption, especially for workloads.

A key characteristic of replace is that any fields present in the live resource but omitted from the new configuration file will typically be removed from the resource (unless they are immutable or server-managed). This differs significantly from kubectl apply, which performs a three-way merge to reconcile differences and is more suited for declarative management.

It is crucial that the resource already exists in the cluster for replace to succeed; it cannot be used to create new resources.

Resource Must Exist: kubectl replace will fail if the specified resource does not already exist in the cluster.

Potential for Disruption: When using --force, resources are deleted and re-created, which can cause temporary downtime for services or applications.

Field Removal: Any fields present in the existing resource but omitted from the new configuration file will be removed (unless they are immutable or server-managed), unlike kubectl apply which performs a merge.

Immutable Fields: Changing immutable fields (e.g., clusterIP for Services) requires a full deletion and re-creation of the resource, which --force facilitates but is still a disruptive operation.

Piping current configuration:
kubectl get <resource-type>/<resource-name> -o yaml | kubectl replace -f -
This pattern fetches the current live configuration of a resource, allows for modifications (e.g., in a text editor or via sed), and then pipes the modified configuration directly to kubectl replace to update the resource.

Generating configuration with dry-run:
kubectl create <resource-type> <resource-name> --image=<image> --dry-run=client -o yaml | kubectl replace -f -
This creates a new manifest in YAML format without actually creating the resource, which can then be piped to kubectl replace to update an existing one or applied after further modifications. While create might seem counter-intuitive, --dry-run is powerful for generating initial manifests for various resource types.

kubectl replace is an imperative command that aims to make the live resource exactly match the provided configuration file. Its default behavior is an in-place update, but it can resort to a delete-and-recreate. Critically, it removes any fields from the live resource that are not present in the provided file.

kubectl apply, in contrast, is a declarative command that uses a three-way merge strategy. It intelligently merges the new configuration with the existing live resource, preserving fields that are not specified in the input file. This makes apply generally safer and more idempotent for continuous deployment and managing configurations, as it avoids unintended deletions of fields or resources. apply is the recommended tool for managing Kubernetes resources declaratively.

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