Merge pull request #13297 from fabriziopandini/document-in-place-contract

📖 Document in place contract

Author: k8s-ci-robot

docs/book/src/developer/providers/contracts/bootstrap-config.md

@@ -53,6 +53,7 @@ repo or add an item to the agenda in the [Cluster API community meeting](https:/
 | [BootstrapConfig: initialization completed]                                | Yes       |                                      |
 | [BootstrapConfig: conditions]                                              | No        |                                      |
 | [BootstrapConfig: terminal failures]                                       | No        |                                      |
+| [BootstrapConfig: support for in-place changes]                            | No        |                                      |
 | [BootstrapConfigTemplate, BootstrapConfigTemplateList resource definition] | Yes       |                                      |
 | [BootstrapConfigTemplate: support for SSA dry run]                         | No        | Mandatory for ClusterClasses support |
 | [Sentinel file]                                                            | No        |                                      |
@@ -354,6 +355,22 @@ fields in the BootstrapConfig resource will be ignored and Machine's `status.dep
 
 </aside>
 
+### BootstrapConfig: support for in-place changes
+
+In case you are developing an bootstrap config provider with support for in-place updates of the Machine configuration,
+you should consider following recommendations during implementation.
+
+- The `Update Extension` is the component responsible for orchestrating in-place changes on Machines.
+  Accordingly, the BootstrapConfig controller should ignore in-place changes and do not re-generate the bootstrap config.
+- It might be useful to start thinking about the BootstrapConfig API surface as a set of fields with one of the following behaviors:
+    - "Immutable" fields that can only be changed by performing a rollout.
+    - "Mutable" fields that will be “reconciled” by the `Update Extension`.
+- The validation webhook for the BootstrapConfig CR should allow changes to "mutable" fields; in case a bootstrap config provider
+  wants to allow this change selectively, e.g. only when applied by core CAPI, please reach out to maintainers to discuss options.
+- Please note that the above field classification do not apply to the BootstrapConfigTemplate object.
+
+See [Proposal](https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240807-in-place-updates.md).
+
 ### BootstrapConfigTemplate, BootstrapConfigTemplateList resource definition
 
 For a given BootstrapConfig resource, you MUST also add a corresponding BootstrapConfigTemplate resources in order to use it

docs/book/src/developer/providers/contracts/infra-machine.md

@@ -55,6 +55,7 @@ repo or add an item to the agenda in the [Cluster API community meeting](https:/
 | [InfraMachine: initialization completed]                             | Yes       |                                      |
 | [InfraMachine: conditions]                                           | No        |                                      |
 | [InfraMachine: terminal failures]                                    | No        |                                      |
+| [InfraMachine: support for in-place changes]                         | No        |                                      |
 | [InfraMachineTemplate, InfraMachineTemplateList resource definition] | Yes       |                                      |
 | [InfraMachineTemplate: support for SSA dry run]                      | No        | Mandatory for ClusterClasses support |
 | [Multi tenancy]                                                      | No        | Mandatory for clusterctl CLI support |
@@ -414,6 +415,24 @@ fields in the InfraMachine resource will be ignored and Machine's `status.deprec
 
 </aside>
 
+### InfraMachine: support for in-place changes
+
+In case you are developing an infrastructure provider with support for in-place updates of the Machine infrastructure,
+you should consider following recommendations during implementation.
+
+- The `Update Extension` is the component responsible for orchestrating in-place changes on Machines.
+  Accordingly, the InfraMachine controller should ignore in-place changes. As alternative the InfraMachine controller
+  must orchestrate those changes with the `Update Extension` (e.g. the `Update Extension` must report change progress).
+- It might be useful to start thinking about the InfraMachine API surface as a set of fields with one of the following behaviors:
+    - "Immutable" fields that can only be changed by performing a rollout.
+    - "Mutable" fields that will be “reconciled” by the `Update Extension`.
+    - Fields written back to spec by the infra provider (e.g. ProviderID).
+- The validation webhook for the InfraMachine CR should allow changes to "mutable" fields; in case an infra provider
+  wants to allow this change selectively, e.g. only when applied by core CAPI, please reach out to maintainers to discuss options.
+- Please note that the above field classification do not apply to the InfraMachineTemplate object.
+
+See [Proposal](https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240807-in-place-updates.md).
+
 ### InfraMachineTemplate, InfraMachineTemplateList resource definition
 
 For a given InfraMachine resource, you MUST also add a corresponding InfraMachineTemplate resources in order to use it