kubectl docs: explanation json patch, strategic merge $patch directives

[ringerc]

Description

When learning k8s I found myself confused by the difference between json and merge patch types, usage of $patch strategic merge directives.

It's very confusing for new (and not so new) users that merge is the name for the RFC7386 JSON merge patch ("dumb" structural merge), json is the name for the RFC6902 json patch patch (array of operations), and strategic is the name for the strategic merge patch. And all of them can be in yaml...

Then there's server-side apply, which may act like a patch rather than replace in the presence of multiple resource managers.

Draft to expand the kubectl patch (and soon, apply) guidance a bit to:

• Link to the specification of strategic merge patches (obsoleted by server-side apply?)
• mention $patch directives for overriding the merge strategy in strategic merge patches
• More clearly explain the difference between a json (json patch) and merge (json merge) patch
• add an example of a json patch, including selection of a container in an array and a test for the container name
• add an example of using a json patch to append to volumes and volumemounts

This is draft, because I'm still not 100% sure myself of the rules surrounding server-side vs client-side patching and strategic merge patches so I have some more tests to write before proposing for merge. The current documentation is very confusing - server-side-apply is actually used for both patch and apply --server-side operations, but patch can accept json / merge / strategic formats, etc. I will seek to further refine my changes until they clearly explain how exactly k8s applies changes in different modes, and update further.

TODO

• clarify if $patch directives delete, replace, merge, $retainKeys directive, $deleteFromPrimitiveList directive, $setElementOrder directive still relevant for kubectl patch --type strategic and if not, are there equivalent ways to specify with the input patch
• clarify role of https://sigs.k8s.io/structured-merge-diff in kubectl patch and kubectl apply
• determine kustomize use of strategic merge directives, see:
  • [Question] Status of $patch (Strategic Merge Patch) support for Custom Resources kubernetes-sigs/kustomize#3694
  • Document strategic merge patch with examples kubernetes-sigs/kustomize#306

Issue

[linux-foundation-easycla]

• ❌ - login: @ringerc / name: Craig Ringer . The commit (f4670a5) is not authorized under a signed CLA. Please click here to be authorized. For further assistance with EasyCLA, please submit a support request ticket.

[netlify]

✅ Pull request preview available for checking

Built without sensitive environment variables

Name	Link
🔨 Latest commit	f4670a5
🔍 Latest deploy log	https://app.netlify.com/sites/kubernetes-io-main-staging/deploys/66c6983a41c7240008b1e822
😎 Deploy Preview	https://deploy-preview-47624--kubernetes-io-main-staging.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[k8s-triage-robot]

Unknown CLA label state. Rechecking for CLA labels.

Send feedback to sig-contributor-experience at kubernetes/community.

/check-cla
/easycla

[sftim]

You'll need to sign the CLA before we can review your changes, but you might like to check out https://kubernetes.io/docs/reference/using-api/api-concepts/#patch-and-apply and see if you want to also update that page, or maybe to direct readers to look there.

[ringerc]

@sftim Thanks very much. The more I got into this the worse it got - I don't think I can do justice to untangling all the confusion and outdated or incomplete info in the relevant docs regarding the patch types, server-side apply, etc.

I can't clearly figure out for example if strategic merge patch directives are still supported with --server-side apply, and I don't expect to have time to do sufficiently in-depth study and test writing for it. I'm happy to do some further docs work if I can get some guidance understanding the problem space better, but I realised when I started looking into server-side apply that it's way more different than I thought.

I'll look at the ref you provided, and see if I can tidy this docs change up to be a minimal update that doesn't go too deep into the weeds.

I'm currently stuck waiting for my org to eventually appoint a CLA manager so I can sign the CLA, which is taking forever.

[k8s-triage-robot]

The Kubernetes project currently lacks enough contributors to adequately respond to all PRs.

This bot triages PRs according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the PR is closed

You can:

• Mark this PR as fresh with /remove-lifecycle stale
• Close this PR with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

[ringerc]

abandoning