To understand kubectl apply, we first need to understand a choice every Kubernetes user makes.

The Imperative Way: Do This, Then Do That

In the imperative style, you give the system a direct command for each action. Create this Pod. Scale that Deployment to five copies. Delete that Service. Each command does one thing, right now. This is quick for experiments and one-off tasks, but it leaves no record of what you did, and repeating the same steps later on another cluster means remembering every command.

The Declarative Way: Here Is the Goal

In the declarative style, you write down the end result you want in a file and hand the file to the system. You do not say how to get there. The system works out the steps by comparing what exists with what you described. The file becomes a permanent, shareable, reviewable record of your intent.

Real systems change constantly, and typing commands by hand does not survive contact with reality.

Repeatability

An application in Kubernetes is described by many small objects: Deployments, Services, configuration objects, and more. Rebuilding them by hand on a second cluster, or after a disaster, would be slow and error-prone. If all of them are described in files, one command recreates everything, identically, every time.

History and Teamwork

Files can be stored in a version-control system such as Git. Every change gets a name, a date, and a reviewer. If a change breaks something, you can see exactly what changed and go back to the previous version. That is impossible when changes were made by typing commands into a terminal and forgetting them.

Safe Repetition

Running the same apply command twice should not cause trouble. If nothing has changed, nothing happens. If one small thing changed, only that small thing is updated. This property, where repeating an action gives the same result as doing it once, is called idempotence, and it makes the command safe to run again and again from scripts and automated pipelines.

Eight small terms carry almost the entire story of kubectl apply.

Behind one short command lies a tidy chain of small steps.

The Journey in Plain Words

First, kubectl reads your file and checks that it is properly formed. Next, it works out which object each part describes and where it belongs. Then it sends the description to the API server. The API server compares your description with what is already stored. If the object does not exist, it creates it. If it exists but differs, it updates only what needs changing. If it exists and already matches, it does nothing. Finally, the controllers notice the new or changed description and start working to make reality match it.

flowchart TD
    A["You write a manifest file"] --> B["kubectl apply reads and checks the file"]
    B --> C["Sends the description to the API server"]
    C --> D{"Does the object already exist?"}
    D -->|"No"| E["Create it"]
    D -->|"Yes"| F{"Does it differ?"}
    F -->|"Yes"| G["Update only what changed"]
    F -->|"No"| H["Report unchanged"]
    E --> I["Controllers make reality match"]
    G --> I
        

Every object in your files ends up in exactly one of three states after an apply.

Kubernetes offers several ways to change objects. Knowing the differences prevents confusion.

The classic way apply works involves a clever comparison of three pictures.

Three Pictures

To decide what to change, the classic method compares three things: what you applied last time, what is live in the cluster right now, and what your file says today. It uses these three to work out what you added, what you removed, and what someone else changed on purpose.

flowchart LR
    A["Last applied copy"] --> D["Three-way comparison"]
    B["Live object in cluster"] --> D
    C["New manifest file"] --> D
    D --> E["Remove what you dropped"]
    D --> F["Add or update what you changed"]
    D --> G["Leave alone what others set"]
        

A newer method moves the comparison work into the cluster and tracks ownership of each field.

The Idea of Ownership

In server-side apply, the API server itself keeps track of who set each individual field of an object. Each tool or person that applies changes is called a field manager. When you apply a file, you become the owner of the fields you specified. Another tool, such as an automated controller, may own other fields on the same object.

Conflicts Are Made Visible

If you try to change a field that another manager owns and the value differs, the server reports a conflict instead of silently overwriting. You then decide: adjust your file so you no longer claim that field, or deliberately force your value and take ownership. This prevents two tools from fighting invisibly over the same setting.

Apply is flexible about where your descriptions come from.

Templating Tools Feed Into Apply

Many teams use tools that generate manifests from templates and settings, such as package managers for Kubernetes. At the end of the pipeline, these tools still hand plain manifests to the cluster in the same declarative way. Understanding apply therefore helps you understand almost every deployment tool built on Kubernetes.

The safest apply is the one you previewed first.

Two Kinds of Preview

Apply is very good at creating and updating, but it does not delete just because a file vanished.

An Absent File Says Nothing

If you remove a manifest from your folder and run apply on the folder again, the object it described stays alive in the cluster. Apply only looks at the descriptions you give it. It has no way of knowing that something missing from your folder was meant to be removed, rather than simply not mentioned this time.

How to Remove Things Properly

Some objects need others to exist first, and apply is not a mind reader.

What Depends on What

A namespace must exist before objects can be placed inside it. A custom resource definition, which teaches the cluster about a new kind of object, must be accepted before objects of that new kind can be created. A ConfigMap or Secret should exist before a Pod that uses it can start successfully.

How Apply Handles Order

When applying a folder, files are processed in name order, and within a single file, objects are processed from top to bottom. Kubernetes cannot always guess the right order across unrelated files. Teams often number their files or separate them into stages so that foundations go first and the rest follow.

Some settings are locked once an object is born, and apply cannot unlock them.

Immutable Fields

Certain fields cannot be edited after an object is created. Examples include the label selector of a Deployment, and the internal address given to a Service. If your manifest changes such a field, the API server rejects the apply with an error message that names the field and says it cannot be changed.

What to Do

The usual solution is to delete the object and apply the corrected description again, planning for a short interruption. For workloads, a safer route is often to create a new object side by side, move traffic to it, and only then remove the old one.

Other parts of the cluster change objects too, and apply must share the stage politely.

The Classic Trap

Suppose your Deployment file says three copies, but an autoscaler has raised the live number to twelve because traffic is heavy. If your file keeps saying three and you apply it again, you will push the count back to three at the worst possible moment. The file and the autoscaler are both trying to own the same field.

The Fix

Leave the replica count out of the file when another tool manages it. Because you never mention the field, apply never claims it, and the autoscaler is free to control it. The same principle applies to any field that other controllers or tools set on your behalf.

Let us follow a change to a Deployment from your keyboard to the running application.

sequenceDiagram
    participant Y as You
    participant K as kubectl
    participant A as API Server
    participant D as Deployment Controller
    participant N as Nodes
    Y->>K: Apply the edited manifest
    K->>A: Send the description
    A->>A: Validate and compare with stored object
    A-->>K: Report configured
    K-->>Y: Show the result message
    A->>D: Notify of the changed Deployment
    D->>N: Start new Pods with the new version
    N-->>D: New Pods become ready
    D->>N: Stop old Pods gradually
    Note over D,N: Rolling update keeps the application available
        

Most apply problems fall into a few familiar shapes.

A Calm Debugging Path

Apply can change almost anything in a cluster, so it must be used with respect.

Practical Protections

Read manifests from outside sources before applying them, and prefer sources you trust. Keep secrets out of plain files, using encrypted storage or dedicated secret management instead. Give people and automation only the permissions they truly need, limited to particular namespaces. Use admission rules that block unsafe settings, so risky objects are refused even if someone tries to apply them. Prefer automated delivery from version control with reviews, rather than everyone applying from their own laptops. Clearly label your terminal or tooling with the current cluster name so a wrong target is obvious before you press enter.

If apply can change everything, you should be able to see everything it changed.

What to Watch

Cluster audit logs record who applied what, and when. Events on each object describe what the controllers did in response. Rollout status shows whether an update finished or stalled. Combined, these tell the full story of every change.

Catching Drift

Drift means the live cluster no longer matches your files, usually because someone made a manual change. Running a diff on a schedule, or using tools that continuously compare and correct, keeps the cluster honest and your files trustworthy.

Good habits make apply boring, and boring is exactly what you want.

A short checklist that prevents most apply trouble before it starts.

Here is how apply quietly powers everyday cluster work.

It reads descriptions of objects from files or other sources and makes the cluster match them, creating missing objects and updating changed ones while leaving matching ones alone.

Create is a one-time instruction that fails if the object already exists. Apply is declarative and safe to repeat, creating the object if missing and updating it if present.

Yes. If nothing changed, the second run reports the objects as unchanged. This repeat-safety is one of the main reasons to use it.

No, not by itself. Removing a file only stops you from mentioning the object. To remove it, delete it explicitly, use careful pruning, or rely on a delivery tool that tracks what it created.

A newer method where the cluster tracks which manager owns each field. It reports conflicts instead of silently overwriting, and copes better with very large objects and shared control.

Some fields cannot change once an object exists. You must delete and recreate the object, or create a replacement alongside it and move traffic over.

Use a server dry run to see whether the cluster would accept the change, and the diff feature to see a line-by-line comparison between the live state and your files.

Your file still contained a fixed number, and apply enforced it over the value set by an autoscaler. Remove the field from the file when another tool owns it.

No. It only means your description was accepted. The controllers then need time to start Pods and move traffic, so always check rollout status afterwards.

For learning and test clusters, that is fine. For shared and production clusters, an automated, reviewed pipeline is safer, more consistent, and leaves a clear record of every change.

The command kubectl apply is how most people tell a Kubernetes cluster what they want. Instead of issuing a string of orders, you write the goal in a file and let the cluster compare it with reality and close the gap. It creates what is missing, updates what differs, and leaves alone what already matches, so it is safe to repeat. Behind the scenes it uses either a classic three-way comparison or the newer field-ownership method. With previews, careful targeting, clear ownership of each setting, and a review-and-automate habit, apply becomes a calm, reliable way to run everything from a single test service to a large production platform.