Update in-place update proposal

Author: fabriziopandini

docs/book/src/reference/glossary.md

@@ -1,6 +1,6 @@
 # Table of Contents
 
-[A](#a) | [B](#b) | [C](#c) | [D](#d) | [E](#e) | [H](#h) | [I](#i) | [K](#k) | [L](#l)| [M](#m) | [N](#n) | [O](#o) | [P](#p) | [R](#r) | [S](#s) | [T](#t) | [W](#w)
+[A](#a) | [B](#b) | [C](#c) | [D](#d) | [E](#e) | [H](#h) | [I](#i) | [K](#k) | [L](#l)| [M](#m) | [N](#n) | [O](#o) | [P](#p) | [R](#r) | [S](#s) | [T](#t) | [U](#u) |[W](#w)
 
 # A
 ---
@@ -264,6 +264,12 @@ are propagated in place by CAPI controllers to avoid the more elaborated mechani
 They include metadata, MinReadySeconds, NodeDrainTimeout, NodeVolumeDetachTimeout and NodeDeletionTimeout but are
 not limited to be expanded in the future.
 
+### In-place update
+
+Any change to a Machine spec, that is performed without deleting the machines and creating a new one.
+
+Note: changing [in-place mutable fields](#in-place-mutable-fields) is not considered and in-place upgrade.
+
 ### Instance
 
 see [Server](#server)
@@ -460,6 +466,17 @@ A [Runtime Hook](#runtime-hook) that allows external components to generate [pat
 
 See [Topology Mutation](../tasks/experimental-features/runtime-sdk/implement-topology-mutation-hook.md)
 
+# U
+---
+
+### Update Lifecycle Hooks
+Is a set of Cluster API [Runtime Hooks](#runtime-hook) called when performing the "can update in-place" decision or
+when performing an [in-place update](#in-place-update).
+
+### Update Extension
+
+A [runtime extension provider](#runtime-extension-provider) that implements [Update Lifecycle Hooks](#update-lifecycle-hooks).
+
 # W
 ---
 

docs/book/src/tasks/experimental-features/runtime-sdk/in-place-update-hooks.md

@@ -0,0 +1,46 @@
+# Implementing Lifecycle Hook Runtime Extensions
+
+<aside class="note warning">
+
+<h1>Caution</h1>
+
+Please note Runtime SDK is an advanced feature. If implemented incorrectly, a failing Runtime Extension can severely impact the Cluster API runtime.
+
+</aside>
+
+## 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)
+introduced extensions allowing users to execute changes on existing machines without deleting the machines and creating a new one.
+
+This document defines those extensions and provides recommendation on how to implement them.
+
+<!-- TOC -->
+* [Implementing Upgrade Plan Runtime Extensions](#implementing-upgrade-plan-runtime-extensions)
+    * [Introduction](#introduction)
+    * [Guidelines](#guidelines)
+    * [Definitions](#definitions)
+        * [GenerateUpgradePlan](#generateupgradeplan)
+<!-- TOC -->
+
+## Guidelines
+
+All guidelines defined in [Implementing Runtime Extensions](implement-extensions.md#guidelines) apply to the
+implementation of Runtime Extensions for upgrade plan hooks as well.
+
+In summary, Runtime Extensions are components that should be designed, written and deployed with great caution given
+that they can affect the proper functioning of the Cluster API runtime. A poorly implemented Runtime Extension could
+potentially block upgrade transitions from happening.
+
+Following recommendations are especially relevant:
+
+* [Idempotence](implement-extensions.md#idempotence)
+* [Deterministic result](implement-extensions.md#deterministic-result)
+* [Error messages](implement-extensions.md#error-messages)
+* [Error management](implement-extensions.md#error-management)
+* [Avoid dependencies](implement-extensions.md#avoid-dependencies)
+
+## Definitions
+
+For additional details about the OpenAPI spec of the upgrade plan hooks, please download the [`runtime-sdk-openapi.yaml`]({{#releaselink repo:"https://github.com/kubernetes-sigs/cluster-api" gomodule:"sigs.k8s.io/cluster-api" asset:"runtime-sdk-openapi.yaml" version:"1.11.x"}})
+file and then open it from the [Swagger UI](https://editor.swagger.io/).