Introduction

The API equivalent of kubectl apply is not a plain POST or PUT. If you want the same declarative behavior, the closest direct API call is a PATCH request using server-side apply. That tells the API server to create or update the object while also tracking field ownership.

What kubectl apply is trying to do

kubectl apply means "make the live object look like this manifest." That is different from imperative commands that say "set replicas to 3" or "update this one field."

Historically, kubectl apply had a client-side mode that calculated diffs locally and stored the last-applied configuration in an annotation. The modern API-native form is server-side apply, where the API server performs the merge and conflict detection.

So if you are calling the API directly, think in terms of:

• HTTP method: PATCH
• patch type: apply patch
• field manager: identify the actor making the change

The direct HTTP request

For a deployment named demo in the default namespace, a server-side apply request looks like this:

1curl --cacert ca.crt \
2  -H "Authorization: Bearer $TOKEN" \
3  -H "Content-Type: application/apply-patch+yaml" \
4  -X PATCH \
5  "https://$APISERVER/apis/apps/v1/namespaces/default/deployments/demo?fieldManager=article-example&force=true" \
6  --data-binary @deployment.yaml

The request body is the manifest you want applied, for example:

1apiVersion: apps/v1
2kind: Deployment
3metadata:
4  name: demo
5  namespace: default
6spec:
7  replicas: 2
8  selector:
9    matchLabels:
10      app: demo
11  template:
12    metadata:
13      labels:
14        app: demo
15    spec:
16      containers:
17        - name: demo
18          image: nginx:1.27
19          ports:
20            - containerPort: 80

If the deployment does not exist, the API server can create it. If it does exist, the API server merges the manifest according to apply semantics.

Why this is different from other patch types

Kubernetes supports several patch styles, including JSON Patch and Merge Patch. Those are useful, but they are not the same as apply.

Server-side apply adds two important behaviors:

• it tracks which actor owns which fields
• it detects conflicts when another actor owns a field you are trying to change

That ownership model is why fieldManager matters. It gives the API server a stable name for the caller so later applies can be merged or rejected consistently.

The optional force=true query parameter tells the API server to take ownership of conflicting fields. Use it carefully, because it can overwrite values set by another controller or operator.

The client-go version

If you are writing Go rather than shelling out to curl, the same operation uses types.ApplyPatchType:

1data := []byte(`
2apiVersion: apps/v1
3kind: Deployment
4metadata:
5  name: demo
6  namespace: default
7spec:
8  replicas: 2
9`)
10
11result, err := clientset.AppsV1().
12    Deployments("default").
13    Patch(
14        ctx,
15        "demo",
16        types.ApplyPatchType,
17        data,
18        metav1.PatchOptions{
19            FieldManager: "article-example",
20            Force:        ptr.To(true),
21        },
22    )
23if err != nil {
24    panic(err)
25}
26_ = result

That is the programmatic equivalent most people want when they ask for the API call behind kubectl apply.

When a plain create or update is enough

If you fully control the object and do not need declarative merge behavior, a normal POST, PUT, or non-apply PATCH may be simpler. But that is not the same contract as apply, especially when multiple actors manage the same resource.

Use apply when you want Kubernetes to reconcile a declarative desired state and track field ownership. Use imperative updates when you are intentionally changing a specific field in a specific object.

Common Pitfalls

The most common mistake is using Content-Type: application/merge-patch+json and expecting kubectl apply behavior. That is a different patch strategy.

Another mistake is omitting fieldManager. Server-side apply depends on field ownership metadata, so the manager name should be stable and explicit.

People also misuse force=true. It resolves conflicts by taking ownership, which is sometimes correct but can also stomp fields owned by another controller.

Finally, do not forget that the applied manifest still needs required fields such as metadata.name and, for namespaced resources, the correct namespace.

Summary

• The closest API equivalent to kubectl apply is a PATCH request using server-side apply.
• Use Content-Type: application/apply-patch+yaml or the JSON apply variant.
• Set a stable fieldManager so Kubernetes can track field ownership.
• Use force=true only when you intentionally want to take over conflicting fields.
• Plain create and update calls are useful, but they are not the same as declarative apply semantics.