kubectl-apply

Apply a configuration to a resource by file name

$ kubectl apply [[-f|--filename]] [path/to/filename]

$ kubectl apply [[-k|--kustomize]] [path/to/directory]

$ [cat pod.json] | kubectl apply [[-f|--filename]] -

$ kubectl apply edit-last-applied [[-f|--filename]] [path/to/filename]

$ kubectl apply set-last-applied [[-f|--filename]] [path/to/filename]

$ kubectl apply view-last-applied [[-f|--filename]] [path/to/filename]

kubectl apply -f FILENAME [options]
kubectl apply -k DIRECTORY [options]

-f, --filename stringArray
    Path to the configuration file(s) (YAML or JSON) or directory containing configuration files to apply. Can be used multiple times.

-k, --kustomize string
    Path to a Kustomization directory to apply. Used for Kustomize-based configurations.

--dry-run string
    If set to 'client', only print the object that would be sent. If 'server', allows server validation without persistence. Valid values: 'client', 'server', 'none'.

--server-side
    If true, apply the configuration on the server. This enables Server-Side Apply (SSA), which tracks field ownership and manages conflicts more effectively.

--prune
    Automatically delete resources that are not defined in the given configuration files. Requires --selector or --all.

--force-conflicts
    If true, server-side apply will force the conflicts to be overwritten. Use with caution.

--field-manager string
    Name of the manager for the fields. Used by Server-Side Apply to track ownership of fields.

-n, --namespace string
    If present, the namespace scope for this CLI request.

kubectl apply is a fundamental command in Kubernetes for declaratively managing cluster resources. Instead of imperative commands, it allows users to define the desired state of their resources in configuration files (YAML or JSON). kubectl apply then intelligently determines the necessary changes to transition the current cluster state to the desired state. It supports both client-side and server-side apply mechanisms. Client-side apply (the historical default) tracks the last applied configuration via an annotation, enabling kubectl to compute diffs and perform merges. Server-side apply (recommended for modern use) shifts the merge logic to the API server, allowing it to track field ownership and manage conflicts more robustly. This command is crucial for idempotent updates, CI/CD pipelines, and GitOps workflows, ensuring consistency and preventing accidental overwrites.

kubectl apply, especially with client-side apply, can sometimes lead to merge conflicts if multiple sources modify the same resource fields without coordination. Server-Side Apply (SSA) largely mitigates this by tracking field ownership, but requires understanding of its behavior. Using --prune without a specific --selector or --all can lead to unintended deletion of resources in the current namespace.

kubectl apply embodies Kubernetes' declarative approach. You define the desired state of your applications and infrastructure in configuration files, and apply ensures the cluster reaches and maintains that state. This is fundamental for GitOps and Infrastructure as Code practices.

Client-Side Apply (default before K8s 1.18): kubectl downloads the object, merges it locally, and sends the updated object. It relies on a last-applied-configuration annotation.
Server-Side Apply (--server-side, stable since K8s 1.18): The merge logic and field ownership tracking occur on the API server. This is the recommended approach for modern Kubernetes workflows as it prevents conflicts by allowing multiple controllers/users to manage different fields of the same resource concurrently.

kubectl apply was introduced early in Kubernetes' development as a core mechanism for declarative resource management. Its initial implementation relied on client-side three-way merge patching, where kubectl would compare the live state, the last-applied configuration (stored as an annotation), and the new desired configuration to compute a patch. To address limitations with conflict resolution and field ownership, Server-Side Apply (SSA) was introduced as alpha in Kubernetes 1.14, beta in 1.16, and stable in 1.18. SSA fundamentally changed how apply works by shifting the merge logic and field ownership tracking to the API server, significantly enhancing its robustness and scalability for complex environments.

kubectl create(1), kubectl replace(1), kubectl diff(1), kubectl get(1), kubectl delete(1), kubectl patch(1)