Proposal: preserving order in strategic merge patch #537

mengqiy · 2017-04-14T20:41:51Z

Move from #467, since we want to move strategic merge patch doc out of the api-convention doc. WIP PR

Addressed comments in #467.

cc: @pwittrock @lavalamp @liggitt @apelisse

mengqiy · 2017-04-24T19:20:30Z

Anyone help to review this?

pwittrock · 2017-04-28T22:14:11Z

contributors/design-proposals/preserve-order-in-strategic-merge-patch.md

+
+## Motivation
+
+The order of lists with a merge strategy is important, because an item in the list may depends on an item before it.


The Kubernetes API may apply semantic meaning to the ordering of items within a list, however the strategic merge patch does not keeping the ordering of elements. Ordering has semantic meaning for Environment variables, as later environment variables may reference earlier environment variables, but not the other way around.

For example ordering has semantic meaning for environment variables.

I would like to change to this, semantic meaning is not very common.

pwittrock · 2017-04-28T22:15:28Z

contributors/design-proposals/preserve-order-in-strategic-merge-patch.md

+## Proposed Change
+
+Changes are all in strategic merge patch package.
+It will be similar to how we solve the problem of deleting items from a list of primitives.


It will be similar to how we solve the problem of deleting items from a list of primitives.

The proposed solution is similar to the solution used for deleting elements from lists of primitives.

pwittrock · 2017-04-28T22:17:54Z

contributors/design-proposals/preserve-order-in-strategic-merge-patch.md

+Changes are all in strategic merge patch package.
+It will be similar to how we solve the problem of deleting items from a list of primitives.
+
+Always send a parallel list along with the patch for list:


Add to the current patch, a directive containing a list of element keys - either the patch merge key, or for primitives the value. When applying the patch, the server we ensure that the relative ordering of elements matches the directive.

pwittrock · 2017-04-28T22:20:34Z

contributors/design-proposals/preserve-order-in-strategic-merge-patch.md

+- otherItemN /
+```
+
+## Version Skew


Version Skew and Backwards Compatibility

pwittrock · 2017-04-28T22:21:56Z

contributors/design-proposals/preserve-order-in-strategic-merge-patch.md

+
+Suppose we define a list of environment variables and we call them
+the original environment variables:
+```yaml


add space before '`'

pwittrock · 2017-04-28T22:27:23Z

contributors/design-proposals/preserve-order-in-strategic-merge-patch.md

+- When patching a list of maps, the parallel list contains a list of items. Each item contains only the merge key.
+- When patching a list of primitives, the parallel list contains a full list from user's config file.
+
+All the items in the server's live list but not in the parallel list will be append to the end of the parallel list.


Before this give a simple example

pwittrock · 2017-04-28T22:29:27Z

contributors/design-proposals/preserve-order-in-strategic-merge-patch.md

+- When patching a list of primitives, the parallel list contains a full list from user's config file.
+
+All the items in the server's live list but not in the parallel list will be append to the end of the parallel list.
+The relative order between these appended items are kept.


Add these as separate sections:

$setElementOrder may contain elements not present in the patch list

The $setElementOrder value may contain elements that are not present in the patch but present in the list to be merge to reorder the elements as part of the merge. Example where A & B have not changed:

Patch:

$setElementOrder/list: - A - B

Live:

list: - B - A

Result:

list: - A - B

When the list to be merged contains elements not found in $setElementOrder

If the list to be merged contains elements not found in $setElementOrder, they will come after all elements defined in $setElementOrder, but keep their relative ordering.

Example where A & B have been changed:

$setElementOrder/list: - A - B list: - A - B

list: - C - A - D - B - E

Result:

list: - A - B - C - D - E

Explain why this would happen. Explain what happens. Give an example.

When $setElementOrder contains elements not found in the list to be merged

Patch:

$setElementOrder/list: - C - A - B list: - A - B

Live:

list: - A - B

Result:

list: - A - B

Explain why this would happen. Explain what happens. Given an example

pwittrock · 2017-04-28T23:53:17Z

contributors/design-proposals/preserve-order-in-strategic-merge-patch.md

+
+The patch will looks like:
+```yaml
+$preserveOrderList/env:


$setElementOrder

pwittrock · 2017-05-01T15:35:36Z

contributors/design-proposals/preserve-order-in-strategic-merge-patch.md

+as later environment variables may reference earlier environment variables,
+but not the other way around.
+
+An use case is the environment variables. We don't preserve the order which causes


An use case

One use case

pwittrock · 2017-05-01T15:36:02Z

contributors/design-proposals/preserve-order-in-strategic-merge-patch.md

+
+Add to the current patch, a directive containing a list of element keys -
+either the patch merge key, or for primitives the value. When applying the patch,
+the server we ensure that the relative ordering of elements matches the directive.


the server we ensure

the server ensures

pwittrock · 2017-05-01T15:36:42Z

contributors/design-proposals/preserve-order-in-strategic-merge-patch.md

+
+All the items in the server's live list but not in the parallel list will be append to the end of the parallel list.
+The relative order between these appended items are kept.
+If the relative order of live config in the server is different from the order of the parallel list,


If the relative order of live config

If the relative order of the live config

pwittrock · 2017-05-01T15:37:03Z

contributors/design-proposals/preserve-order-in-strategic-merge-patch.md

+All the items in the server's live list but not in the parallel list will be append to the end of the parallel list.
+The relative order between these appended items are kept.
+If the relative order of live config in the server is different from the order of the parallel list,
+user's patch will always override the order in the server.


user's patch will al

the user's patch will al

pwittrock · 2017-05-01T15:41:03Z

contributors/design-proposals/preserve-order-in-strategic-merge-patch.md

+The new patch has one additional parallel list which will be dropped by the old server.
+
+The logic for old version patch is still kept,
+so the patch from any arbitrary old clients used to work before will continue to function.


so the patch from any arbitrary old clients used to work before will continue to function.

The new directive is optional. Patch requests without the directive will retain the behavior from previous releases. This will ensure backward compatibility with old clients.

pwittrock · 2017-05-01T15:43:38Z

contributors/design-proposals/preserve-order-in-strategic-merge-patch.md

+Then the server appends two finalizers and reorder the list:
+
+```yaml
+finalizers:


This is a really helpful example. Good job.

pwittrock · 2017-05-01T15:44:00Z

Minor nits on wording. Otherwise LGTM.

mengqiy · 2017-05-01T17:25:38Z

Updated.

pwittrock · 2017-05-01T17:28:43Z

This looks good to me.

mengqiy · 2017-05-01T17:32:36Z

Squashed commits.

pwittrock · 2017-05-01T18:11:04Z

contributors/design-proposals/preserve-order-in-strategic-merge-patch.md

+The new patch has one additional parallel list which will be dropped by the old server.
+
+The new directive is optional.
+Patch requests without the directive will retain the behavior from previous releases.


We should do something better

pwittrock · 2017-05-01T18:11:27Z

contributors/design-proposals/preserve-order-in-strategic-merge-patch.md

+- E
+```
+
+### When `$setElementOrder` contains elements not found in the list to be merged


Add a section for

When $setElementOrder is not present and patching a list.

pwittrock · 2017-05-01T20:36:44Z

contributors/design-proposals/preserve-order-in-strategic-merge-patch.md

+```
+
+
+# Alternative Considered


Another alternative, is to send the mergeKeys as empty elements in the list, and have the server maintain the order of the provided items. In this case, we don't need to introduce any new directives, and the patch should be totally compatible. The patch list would always be reordered to come before all elements missing from the patch.

Thinking on this more, if we did that, we might end up creating elements that we just want to order - e.g. if we want to modify "A", and send "A, B, C" as the main list to keep ordering, "C" would get recreated if it was deleted or missing, which we would not want.

mengqiy · 2017-05-02T01:32:21Z

Updated. PTAL.

adohe-zz · 2017-05-02T14:55:17Z

contributors/design-proposals/preserve-order-in-strategic-merge-patch.md

+Changes are all in strategic merge patch package.
+The proposed solution is similar to the solution used for deleting elements from lists of primitives.
+
+Add to the current patch, a directive ($setElementOrder) containing a list of element keys -


not every list wants to keep ordering, whether we will consider add a directive to type definition?

add a directive to type definition

I don't understand what you mean here. Can you give me an example?

@adohe I think you mean that the ordering is not semantically important for every list, and should we add a comment tag to the field definition indicating whether order has semantic meaning. (e.g. The containers list in a PodTemplate does not have semantically meaningful order).

I think this would be be interesting to do in a follow up. Since this is totally optional and sent by the client, the client should decide whether it wants to control the order or not for a given patch (yes it should want to do so)

@pwittrock yep, that's exactly what I mean. We could do this in a follow up and I am just wondering how the client can decide whether or not to keep list order.

adohe-zz · 2017-05-02T15:09:32Z

contributors/design-proposals/preserve-order-in-strategic-merge-patch.md

+The proposed solution is similar to the solution used for deleting elements from lists of primitives.
+
+Add to the current patch, a directive ($setElementOrder) containing a list of element keys -
+either the patch merge key, or for primitives the value. When applying the patch,


any consideration about multiple key as merge key?

The mergeKey is a key-value pair in the map. If we are not using any special format, I think new additional merge keys will simply be new key-value pair in the map.

pwittrock · 2017-05-04T15:49:52Z

@fabianofranz @liggitt I will be merging this today if there are no other comments.

liggitt · 2017-05-04T19:23:27Z

contributors/design-proposals/preserve-order-in-strategic-merge-patch.md

+For changes and deletions, the server will just merge the change without sorting them.
+So the items in the list will retain the order.
+
+For additions, the items will be appended to the end of the list.


If the server has [A,B,C]
and the client sends [X,A,B,C]
always appending to the end has this counter-intuitive result: [A,B,C,X]

Are old clients known to scramble the order when computing the patch, or was the scrambling happening server-side?

I would have expected the order of two items to be determined by something like the following:

relative order in the $setElementOrder if both items are present

else relative order in the patch if both items are present

else relative order in the server-side list if both items are present

else append to the end

Are old clients known to scramble the order when computing the patch, or was the scrambling happening server-side?

Both. We sort the list by mergeKey when diffing and merging in current strategic merge patch implementation.

@liggitt What should the result be when applying patch [c,b,a] to server's list [a,x,b,y,c]?

I cannot find a way to keep relative order of (a,x) and (x,b) at the same time.

@liggitt Your later comment addresses this I think - all items in the list must appear in the orderList

I was expecting something like https://play.golang.org/p/tJLW1Zj0h7 where the directive is used if present, otherwise the relative order in the patch list is honored for item pairs which are both present, and finally the relative server-side order is honored.

that is less compelling if old clients sent randomly ordered lists

Thanks a lot. This is super helpful.

liggitt · 2017-05-04T19:24:34Z

contributors/design-proposals/preserve-order-in-strategic-merge-patch.md

+### When the list to be merged contains elements not found in `$setElementOrder`
+
+If the list to be merged contains elements not found in $setElementOrder,
+they will come after all elements defined in $setElementOrder, but keep their relative ordering.


if the patch contains $setElementOrder, it seems like an error for $setElementOrder to be missing items that are present in the list (or to have items in a different order than the list)

it seems like an error for $setElementOrder to be missing items that are present in the list

I'm OK to fail the operation. I will update it soon.

or to have items in a different order than the list

Do you mean we should always verify the order in patch list and the order in $setElementOrder match before merging?

I think @liggitt was suggesting both are required. I think that is probably fine.

liggitt · 2017-05-04T19:28:50Z

contributors/design-proposals/preserve-order-in-strategic-merge-patch.md

+but still be fully backward compatible.
+
+### kubectl
+If an old kubectl sends a old patch to a new server, the server will not preserve the order which behave as an old server.


can we not do better here by honoring relative order of items in the patch?

As mentioned above #537 (comment), a patch sent by old kubectl doesn't has any useful order in it. Because it has been sorted by mergeKey.
What should we do in this case?

@liggitt I was thinking about this as well.

I think you are saying, can you just use the ordering in the patch list instead of sending another directive.

The issue here is: If you have a list of [a,b,c] and want to patch b you would either send a patch [b] or send a patch [a,b,c]. The former lacks the ordering, and the latter will recreate [a,c] if they were deleted from the server.

I don't think it removes the need for the separate order-indicating directive, but it seems really counter-intuitive to ignore relative order in the list

@liggitt Now sure how much of an issue you think this is. I think it is an edge case, but one that be annoying to track down if it is encountered.

mengqiy · 2017-05-04T20:41:13Z

This change is

mengqiy · 2017-05-06T00:21:52Z

PTAL

mengqiy · 2017-05-12T22:47:26Z

Squashed commits.

pwittrock · 2017-05-12T22:57:55Z

@LiGgit merging this since it looks like you comments have been addressed

mengqiy mentioned this pull request Apr 14, 2017

preserve order of list in strategicMergePatch #467

Closed

k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label Apr 24, 2017

pwittrock assigned liggitt, monopole, pwittrock and fabianofranz Apr 28, 2017

mengqiy force-pushed the preserve_order_proposal branch from 6de8ca2 to 0547f63 Compare April 28, 2017 21:37

pwittrock reviewed Apr 28, 2017

View reviewed changes

mengqiy force-pushed the preserve_order_proposal branch from 0547f63 to cdeca8b Compare April 28, 2017 22:17

pwittrock reviewed Apr 28, 2017

View reviewed changes

mengqiy force-pushed the preserve_order_proposal branch from cdeca8b to 843e051 Compare April 29, 2017 01:14

pwittrock reviewed May 1, 2017

View reviewed changes

mengqiy force-pushed the preserve_order_proposal branch from 7380028 to 23721e4 Compare May 1, 2017 17:32

pwittrock reviewed May 1, 2017

View reviewed changes

mengqiy force-pushed the preserve_order_proposal branch from d42784d to 0861047 Compare May 2, 2017 01:30

adohe-zz reviewed May 2, 2017

View reviewed changes

mengqiy mentioned this pull request May 3, 2017

support replaceKeys patch strategy kubernetes/kubernetes#44597

Merged

liggitt reviewed May 4, 2017

View reviewed changes

mengqiy force-pushed the preserve_order_proposal branch from 0861047 to 060b30b Compare May 5, 2017 18:57

proposal of preserving order

ec0d060

mengqiy force-pushed the preserve_order_proposal branch from 060b30b to ec0d060 Compare May 12, 2017 22:46

pwittrock merged commit ab60a1d into kubernetes:master May 12, 2017

mengqiy deleted the preserve_order_proposal branch May 22, 2017 17:31

mengqiy mentioned this pull request May 22, 2017

support setElementOrder kubernetes/kubernetes#45980

Merged

danehans pushed a commit to danehans/community that referenced this pull request Jul 18, 2023

add myself to developer list (kubernetes#537)

90aa987


		## Motivation

		The order of lists with a merge strategy is important, because an item in the list may depends on an item before it.

Proposal: preserving order in strategic merge patch #537

Proposal: preserving order in strategic merge patch #537

Conversation

mengqiy commented Apr 14, 2017

mengqiy commented Apr 24, 2017

pwittrock Apr 28, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pwittrock Apr 28, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pwittrock Apr 28, 2017 • edited Loading

Choose a reason for hiding this comment

$setElementOrder may contain elements not present in the patch list

When the list to be merged contains elements not found in $setElementOrder

When $setElementOrder contains elements not found in the list to be merged

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pwittrock commented May 1, 2017

mengqiy commented May 1, 2017

pwittrock commented May 1, 2017

mengqiy commented May 1, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

When $setElementOrder is not present and patching a list.

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mengqiy commented May 2, 2017

Choose a reason for hiding this comment

mengqiy May 3, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pwittrock commented May 4, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

liggitt May 4, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mengqiy commented May 4, 2017

mengqiy commented May 6, 2017

mengqiy commented May 12, 2017

pwittrock commented May 12, 2017

pwittrock Apr 28, 2017 •

edited

Loading

pwittrock Apr 28, 2017 •

edited

Loading

pwittrock Apr 28, 2017 •

edited

Loading

`$setElementOrder` may contain elements not present in the patch list

When the list to be merged contains elements not found in `$setElementOrder`

When `$setElementOrder` contains elements not found in the list to be merged

When `$setElementOrder` is not present and patching a list.

mengqiy May 3, 2017 •

edited

Loading

liggitt May 4, 2017 •

edited

Loading