diff --git a/contributors/devel/sig-architecture/api-conventions.md b/contributors/devel/sig-architecture/api-conventions.md index 57fbfaade06..cfbd3620cc3 100644 --- a/contributors/devel/sig-architecture/api-conventions.md +++ b/contributors/devel/sig-architecture/api-conventions.md @@ -591,6 +591,23 @@ saved. For more details on how to use Merge Patch, see the RFC. detailed explanation of how it works and why it needed to be introduced, see [here](/contributors/devel/sig-api-machinery/strategic-merge-patch.md). +#### Declaring Patch Strategy and Object Topology +In the context of [strategic merge patch](/contributors/devel/sig-api-machinery/strategic-merge-patch.md), a set of go markers can be used by API authors to declare the patch strategy of lists, maps and structs (`//+patchStrategy` and `//+patchMergeKey`). Work to move the `apply` functionality to the control plane ([KEP](https://github.com/kubernetes/enhancements/blob/master/keps/sig-api-machinery/0006-apply.md)) has also introduced markers to describe the topology of lists, maps and structs (`//+listType`, `//+listMapKeys`, `//+mapType`, `//+structType`). + +| Marker | Definition | +|--------|------------| +| `//+patchStrategy=merge` | Defines that the merge strategy will be to merge elements of the two lists into one. | +| `//+patchStrategy=replace` (default)| Defines that the merge strategy will be to use the list provided in the patch literally rather than merging. | +| `// +patchMergeKey=` | Applicable in the context where lists are used as maps/dictionaries, i.e. where each list entry is a key-value pair. `patchMergeKey` defines which field should be seen as the key. Combined with `patchStrategy`, this describes what changes should take place on specific elements of a list as part of a patch operation. | +| `//+listType=atomic` | Applicable to objects that are of type list. A single actor owns and can replace the entire list, but cannot change individual elements of it. | +| `//+listType=set` | Applicable to objects that are of type list, and the elements are unique and scalar. Different actors can update individual elements in the list. | +| `//+listType=map` | Applicable to objects that are of type list, and elements are map-like, i.e. lists that are used as dictionaries. Different actors can update individual elements in the list. | +| `//+listMapKeys=` | Applicable in the context where `listType=map`. `listMapKeys` is a list of strings, that defines which combination of keys should be used as the identifier of each element. Combinations of `listMapKeys` must be unique. Values of keys may be of any scalar type. | +| `//+mapType=atomic` | A single actor can only replace the map entirely. | +| `//+mapType=granular` (default) | Multiple actors can update individual map entries separately. | +| `//+structType=atomic` | A single actor can only replace the struct entirely. | +| `//+structType=granular` (default) | Multiple actors can update individual struct fields separately. | + ## Idempotency All compatible Kubernetes APIs MUST support "name idempotency" and respond with