Revisit resourceVersion and locking behavior

[shawkins]

Is your task related to a problem? Please describe

There are several paradigms that the fabric8 client uses wrt to resourceVersions - which are not all entirely consistent.

• kubectl does not have the same concept of replacement - only if the user leaves the item resourceVersion unset does it make a single attempt to get the freshest resourceVersion and make the put call.
• kubectl does not have the same concept of locking, which is basically only necessary for the fabric8 client due to offering a replace operation that by default will try to use a fresher resourceVersion. Our notion of locking doesn't extend to other operations such as patching.
• json patch (edit method) always removes the resourceVersion - as mentioned above given the limited scope of locking, there's no way to then lock an edit.
• the other patches are handled in the same way as kubectl - that is if the resourceVersion is included it will be considered for optimistic locking.

Describe the solution you'd like

We should try to make things as consistent as possible, and/or follow the behavior of kubectl. That could mean either expanding / formalizing the notion of locking, or removing it - with documentation on what leaving the resourceVersion populated on an item does.

Describe alternatives you've considered

No response

Additional context

No response

[shawkins]

Discussed on a call. The most straight-forward action would be to deprecate the current replace and createOrReplace methods and the usage of lock related to replace.

This will also help move away from the situations where a put / json patch leads to invalid states that we current compensate for - modifyItemForReplaceOrPatch which is used for Services, Jobs, and RoleBindings - as users will be directed towards logic that doesn't need to compensate.

Beyond the deprecations we would do:

• introduce an update operation with the default resourceVersion handling - if it's present then it will be "locked", if it's not there then we'll get the latest version from the server. There will also be no forcing / retry behavior. This will be a safer out-of-the-box call as users will be more aware of concurrent modifications.
• change the json patch loic to not clear the resource version field, but instead send it with the patch if it has been left populated on the edited item. This will preserve similar locking semantics as all the other calls.
• Direct users to user serverSideApply and consider adding a createOrPatch style method to compensate for kube versions that lack server side apply.