Within Server-side apply, document map and list merging behaviors.

[erictune]

This is a Feature Request

What would you like to be added

Add this content to the page https://kubernetes.io/docs/reference/using-api/api-concepts/#server-side-apply

---

For Kubernetes version 1.16, CRDs support the following annotations:

• x-kubernetes-list-map-key
• x-kubernetes-list-map-type
  These tags, and the type of a field in the CRD's validation section (type: object or type: array) affect how Server-Side Apply operates.

Maps and lists are merged differently.

• Type: Map
  1. map key(s) used to consider one item at a time.
  2. applier-owned keys not mentioned in an apply operation are deleted
  3. non-existing keys mentioned in apply operation are inserted
  4. existing not-owned-by-applier keys, not mentioned in the apply operation, are left along.
  5. keys mentioned and not-owned by applier with differing values will trigger conflict.
• Type: lists with the x-kubernetes-list-map-type.
  • Same as Map
  • x-kubernetes-list-map-keys determines the key or key-tuple.
  • otherwise, name used as key if it is a property
  • otherwise (what happens?)
• Normal List a.k.a Atomic List
  1. whole list is owned by one owner.
  2. if not-owned by applier, raise conflict
  3. if owned by applier, replaced with content in apply body.

Why is this needed
Server-Side apply does not explain list or map merging.

Comments

I suggest @apelisse or @jennybuckley as Eng reviewer for the website content resulting form this issue.

[sftim]

It's a valid improvement
/kind feature
/priority backlog

[erictune]

@apelisse @jennybuckley

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[erictune]

/remove-lifecycle stale

…

On Sun, Jan 5, 2020 at 11:09 AM fejta-bot ***@***.***> wrote: Issues go stale after 90d of inactivity. Mark the issue as fresh with /remove-lifecycle stale. Stale issues rot after an additional 30d of inactivity and eventually close. If this issue is safe to close now please do so with /close. Send feedback to sig-testing, kubernetes/test-infra and/or fejta <https://github.com/fejta>. /lifecycle stale — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#16725?email_source=notifications&email_token=AB5245UM7JBLMJ23ZQAU3Y3Q4IV55A5CNFSM4I6HS542YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEID5I5Y#issuecomment-570938487>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AB5245SGF3FPNX52DYLA7CLQ4IV55ANCNFSM4I6HS54Q> .

[kwiesmueller]

/assign @mariantalla

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[fejta-bot]

Stale issues rot after 30d of inactivity.
Mark the issue as fresh with /remove-lifecycle rotten.
Rotten issues close after an additional 30d of inactivity.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle rotten

[apelisse]

/lifecycle frozen

[kwiesmueller]

/wg api-expression

[TBBle]

This does appear to be documented at https://kubernetes.io/docs/reference/using-api/server-side-apply/#merge-strategy now.

[apelisse]

Correct, I think it's done now.

[apelisse]

/close

[k8s-ci-robot]

@apelisse: Closing this issue.

In response to this:

/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[apelisse]

applier-owned keys not mentioned in an apply operation are deleted

I suspect this could be better documented.