Address feedback

fabriziopandini · fabriziopandini · commit f577682e6fdf · 2025-12-03T12:57:17.000+01:00
diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md
@@ -39,7 +39,7 @@
             - [Implementing Runtime Extensions](./tasks/experimental-features/runtime-sdk/implement-extensions.md)
             - [Implementing Lifecycle Hook Extensions](./tasks/experimental-features/runtime-sdk/implement-lifecycle-hooks.md)
             - [Implementing Topology Mutation Hook Extensions](./tasks/experimental-features/runtime-sdk/implement-topology-mutation-hook.md)
-            - [Implementing In-Place Update Hooks Extensions](./tasks/experimental-features/runtime-sdk/implement-in-place-update-hooks.md)
+            - [Implementing In-place Update Hooks Extensions](./tasks/experimental-features/runtime-sdk/implement-in-place-update-hooks.md)
             - [Deploying Runtime Extensions](./tasks/experimental-features/runtime-sdk/deploy-runtime-extension.md)
         - [Ignition Bootstrap configuration](./tasks/experimental-features/ignition.md)
     - [Running multiple providers](./tasks/multiple-providers.md)
diff --git a/docs/book/src/reference/glossary.md b/docs/book/src/reference/glossary.md
@@ -278,6 +278,8 @@ see [Server](#server)
 
 A resource that does not mutate.  In Kubernetes we often state the instance of a running pod is immutable or does not change once it is run.  In order to make a change, a new pod is run.  In the context of [Cluster API](#cluster-api) we often refer to a running instance of a [Machine](#machine) as being immutable, from a [Cluster API](#cluster-api) perspective.
 
+Note: Cluster API also have extensibility points that make it possible to perform [in-place updates](#in-place-update) of machines.
+
 ### IPAM provider
 
 Refers to a [provider](#provider) that allows Cluster API to interact with IPAM solutions.
diff --git a/docs/book/src/tasks/experimental-features/experimental-features.md b/docs/book/src/tasks/experimental-features/experimental-features.md
@@ -5,6 +5,9 @@ temporary location for features which will be moved to their permanent locations
 
 Currently Cluster API has the following experimental features:
 * `ClusterTopology` (env var: `CLUSTER_TOPOLOGY`): [ClusterClass](./cluster-class/index.md)
+* `InPlaceUpdates` (env var: `EXP_IN_PLACE_UPDATES`):
+  * Allows users to execute changes on existing machines without deleting the machines and creating a new one.
+  * See the [proposal](https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/20240807-in-place-updates.md) for more details.
 * `KubeadmBootstrapFormatIgnition` (env var: `EXP_KUBEADM_BOOTSTRAP_FORMAT_IGNITION`): [Ignition](./ignition.md)
 * `MachinePool` (env var: `EXP_MACHINE_POOL`): [MachinePools](./machine-pools.md)
 * `MachineSetPreflightChecks` (env var: `EXP_MACHINE_SET_PREFLIGHT_CHECKS`): [MachineSetPreflightChecks](./machineset-preflight-checks.md)
diff --git a/docs/book/src/tasks/experimental-features/runtime-sdk/implement-in-place-update-hooks.md b/docs/book/src/tasks/experimental-features/runtime-sdk/implement-in-place-update-hooks.md
@@ -10,7 +10,7 @@ Please note Runtime SDK is an advanced feature. If implemented incorrectly, a fa
 
 ## Introduction
 
-The proposal for [n-place updates in Cluster API](https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/20240807-in-place-updates.md)
+The proposal for [in-place updates in Cluster API](https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/20240807-in-place-updates.md)
 introduced extensions allowing users to execute changes on existing machines without deleting the machines and creating a new one.
 
 Notably, the Cluster API user experience remain the same as of today no matter of the in-place update feature is enabled 
@@ -19,7 +19,7 @@ or not e.g. in order to trigger a MachineDeployment rollout, you have to rotate
 Users should care ONLY about the desired state (as of today).
 
 Cluster API is responsible to choose the best strategy to achieve desired state, and with the introduction of 
-update extensions, Cluster API is expanding the set of tools Cluster API can use to achieve the desired state.
+update extensions, Cluster API is expanding the set of tools that can be used to achieve the desired state.
 
 If external update extensions can not cover the totality of the desired changes, CAPI will fall back to Cluster API’s default, 
 immutable rollouts.
@@ -35,7 +35,17 @@ options like MaxSurge/MaxUnavailable. With this regard:
     is “buffer” for in-place, in-place update can proceed.
     - When in-place is possible, the system should try to in-place update as many machines as possible.
       In practice, this means that maxSurge might be not fully used (it is used only for scale up by one if maxUnavailable=0).
-  - No in-place updates are performed for workers machines when using rollout strategy on delete.
+  - No in-place updates are performed for workers machines when using rollout strategy `OnDelete`.
+
+<aside class="note warning">
+
+<h1>Important!</h1>
+
+Cluster API will call the in-place extensions only if the `InPlaceUpdates` feature flag is enabled.
+
+Also, please note that the current implementation of the [in-place updates proposal](https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/20240807-in-place-updates.md) only allows registering one extension for the `CanUpdateMachine`, `CanUpdateMachineSet` and `UpdateMachine` hooks.
+
+</aside>
 
 <!-- TOC -->
 * [Implementing in-place update hooks](#implementing-in-place-update-hooks)
@@ -74,7 +84,7 @@ file and then open it from the [Swagger UI](https://editor.swagger.io/).
 
 This hook is called by KCP when performing the "can update in-place" for a control plane machine.
 
-Example request
+Example request:
 
 ```yaml
 apiVersion: hooks.runtime.cluster.x-k8s.io/v1alpha1
@@ -117,9 +127,9 @@ desired:
 Note:
 - All the objects will have the latest API version known by Cluster API.
 - Only spec is provided, status fields are not included
-- When more than one extension will be supported, the current state will already include changes that can handle in-place by other runtime extensions.
+- In a future release, when registering more than one extension for the `CanUpdateMachine` will be supported, the current state will already include changes that can be handled in-place by other runtime extensions.
 
-Example Response
+Example Response:
 
 ```yaml
 apiVersion: hooks.runtime.cluster.x-k8s.io/v1alpha1
@@ -188,7 +198,7 @@ desired:
 Note:
 - All the objects will have the latest API version known by Cluster API.
 - Only spec is provided, status fields are not included
-- When more than one extension will be supported, the current state will already include changes that can handle in-place by other runtime extensions.
+- In a future release, when registering more than one extension for the `CanUpdateMachineSet` will be supported, the current state will already include changes that can be handled in-place by other runtime extensions.
 
 Example Response
 
diff --git a/docs/book/src/tasks/experimental-features/runtime-sdk/index.md b/docs/book/src/tasks/experimental-features/runtime-sdk/index.md
@@ -31,6 +31,6 @@ Additional documentation:
     * [Implementing Runtime Extensions](./implement-extensions.md)
     * [Implementing Lifecycle Hook Extensions](./implement-lifecycle-hooks.md)
     * [Implementing Topology Mutation Hook Extensions](./implement-topology-mutation-hook.md)
-    * [Implementing In-Place Update Hooks Extensions](./implement-in-place-update-hooks.md)
+    * [Implementing In-place Update Hooks Extensions](./implement-in-place-update-hooks.md)
 * For Cluster operators:
     * [Deploying Runtime Extensions](./deploy-runtime-extension.md)
diff --git a/docs/book/src/user/concepts.md b/docs/book/src/user/concepts.md
@@ -49,12 +49,24 @@ A "Machine" is the declarative spec for an infrastructure component hosting a Ku
 
 Common fields such as Kubernetes version are modeled as fields on the Machine's spec. Any information that is provider-specific is part of the `InfrastructureRef` and is not portable between different providers.
 
-#### Machine Immutability (In-place Update vs. Replace)
+#### Machine Immutability (In-place update vs. Replace)
 
 From the perspective of Cluster API, all Machines are immutable: once they are created, they are never updated (except for labels, annotations and status), only deleted.
 
 For this reason, MachineDeployments are preferable. MachineDeployments handle changes to machines by replacing them, in the same way core Deployments handle changes to Pod specifications.
 
+Over time several improvement have been applied to Cluster API in oder to perform machine rollout only when necessary and
+for minimizing risks and impacts of this operation on users workloads.
+
+Starting from Cluster API v1.12, users can intentionally trade off some of the benefits that they get of Machine immutability by 
+using Cluster API extensions points to add the capability to perform in-place updates under well-defined circumstances.
+
+Notably, the Cluster API user experience will remain the same no matter of the in-place update feature is enabled
+or not, because ultimately users should care ONLY about the desired state.
+
+Cluster API is responsible to choose the best strategy to achieve desired state, and with the introduction of
+update extensions, Cluster API is expanding the set of tools that can be used to achieve the desired state.
+
 ### MachineDeployment
 
 A MachineDeployment provides declarative updates for Machines and MachineSets.
diff --git a/docs/proposals/20240807-in-place-updates.md b/docs/proposals/20240807-in-place-updates.md
@@ -165,7 +165,7 @@ The responsibility to determine which Machine/MachineSet should be updated, the
 
 We propose to extend KCP and MachineDeployment rollout workflows to call External Update Extensions, if defined.
 
-Initially, this feature will be implemented without making API changes in the current core Cluster API objects. It will follow Kubernetes' feature gate mechanism. All functionality related to In-Place Updates will be available only if the `InPlaceUpdates` feature flag is set to true. It is disabled unless explicitly configured.
+Initially, this feature will be implemented without making API changes in the current core Cluster API objects. It will follow Kubernetes' feature gate mechanism. All functionality related to in-place Updates will be available only if the `InPlaceUpdates` feature flag is set to true. It is disabled unless explicitly configured.
 
 This proposal introduces three new Lifecycle Hooks named `CanUpdateMachine`, `CanUpdateMachineSet` and `UpdateMachine` for communication between CAPI and external update implementers. 
 
@@ -431,11 +431,11 @@ However, in-place updates might cause Nodes to become unhealthy while the update
 
 ### Examples
 
-This section aims to showcase our vision for the In-Places Updates end state. It shows a high level picture of a few common use cases, specially around how the different components interact through the API.
+This section aims to showcase our vision for the in-place update end state. It shows a high level picture of a few common use cases, specially around how the different components interact through the API.
 
 Note that these examples don't show all the low level details, the examples here are just to help communicate the vision.
 
-Let's imagine a vSphere cluster with a KCP control plane that has two fictional In-Place update extensions already deployed and registered through their respective `ExtensionConfig`.
+Let's imagine a vSphere cluster with a KCP control plane that has two fictional in-place update extensions already deployed and registered through their respective `ExtensionConfig`.
 1. `vsphere-vm-memory-update`: The extension uses vSphere APIs to hot-add memory to VMs if "Memory Hot Add" is enabled or through a power cycle.
 2. `kcp-version-update`: Updates the kubernetes version of KCP machines by using an agent that first updates the kubernetes related packages (`kubeadm`, `kubectl`, etc.) and then runs the `kubeadm upgrade` command. The In-place Update extension communicates with this agent, sending instructions with the kubernetes version a machine needs to be updated to.
 
