Check Kubernetes list semantics before using kubectl patch

Bottom line: State whether a list change should add, remove or replace entries before choosing the patch. Review the specific field and operation rather than treating a short patch file as evidence that unrelated entries will remain.

Source fact: documented behavior

The Update API Objects in Place Using kubectl patch documentation is the primary reference.

The strategic patch example merges containers using name, while its tolerations example replaces that list because it lacks a merge strategy. A JSON merge patch replaces an existing list with the complete new list supplied in the patch. The tutorial says strategic merge patch is not supported for custom resources.

What the source does not establish

This article covers the documented built-in Deployment examples. It does not approve a production mutation, select a scheduling policy or establish application availability after a change. Review those consequences separately. Keep the source object, proposed patch and intended final list together before authorizing execution.

Applicability questions

• Is the intended change an addition, removal or complete replacement?
• Which field and API resource are being changed?
• Which patch type and field strategy apply?
• What unrelated entries must remain in the accepted after-state?

DSE recommendation: write the intended after-list first

DSE recommends writing the complete expected list before constructing a patch. Identify every existing entry that should remain and the one change being requested. This makes an omitted entry visible during review rather than after an application or scheduling change.

Read the relevant field strategy for the actual API type. For the tutorial’s two examples, review containers and tolerations independently even though they sit in the same Pod specification. Keep the selected --type value with the patch file so a reviewer does not infer the operation from its contents alone.

Use the documented --patch-file approach for a reproducible lab exercise when appropriate. Preserve the exact file and target identity. Review any shell quoting separately if the same change is later written inline; keep one clearly identified authoritative representation instead of several almost identical command fragments.

Compare the entire affected list after the exercise. Check the retained entries as deliberately as the new entry. If the actual result differs from the expected after-list, resolve the operation or expectation before repeating it against a wider population. Keep the application rollout check separate from the evidence that the API object contains the intended fields.

Verification and evidence

Proposed verification, not performed: prepare a disposable Deployment with two harmless named container entries and a separately recorded toleration list. Rehearse a strategic patch that adds a container, then a separate strategic toleration-list change. Compare each result with its written expected list rather than assuming both fields use the same behavior.

In another isolated case, supply a complete replacement list through the documented JSON merge type. Retain the original object, patch type, patch file and full resulting list for every case. Have a second operator identify which entries should survive before viewing the result. Record actual workload observations separately, and do not treat a correctly changed list as proof that the application rollout was accepted.

Official references

• Update API Objects in Place Using kubectl patch — Kubernetes.

Source review completed October 28, 2026. Recheck the official documentation and deployment-specific applicability before a production change.