You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/book/src/reference/glossary.md
+2Lines changed: 2 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -278,6 +278,8 @@ see [Server](#server)
278
278
279
279
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.
280
280
281
+
Note: Cluster API also have extensibility points that make it possible to perform [in-place updates](#in-place-update) of machines.
282
+
281
283
### IPAM provider
282
284
283
285
Refers to a [provider](#provider) that allows Cluster API to interact with IPAM solutions.
Copy file name to clipboardExpand all lines: docs/book/src/tasks/experimental-features/runtime-sdk/implement-in-place-update-hooks.md
+21-11Lines changed: 21 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,7 +10,7 @@ Please note Runtime SDK is an advanced feature. If implemented incorrectly, a fa
10
10
11
11
## Introduction
12
12
13
-
The proposal for [n-place updates in Cluster API](https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/20240807-in-place-updates.md)
13
+
The proposal for [in-place updates in Cluster API](https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/20240807-in-place-updates.md)
14
14
introduced extensions allowing users to execute changes on existing machines without deleting the machines and creating a new one.
15
15
16
16
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
19
19
Users should care ONLY about the desired state (as of today).
20
20
21
21
Cluster API is responsible to choose the best strategy to achieve desired state, and with the introduction of
22
-
update extensions, Cluster API is expanding the set of tools Cluster API can use to achieve the desired state.
22
+
update extensions, Cluster API is expanding the set of tools that can be used to achieve the desired state.
23
23
24
24
If external update extensions can not cover the totality of the desired changes, CAPI will fall back to Cluster API’s default,
25
25
immutable rollouts.
@@ -35,7 +35,17 @@ options like MaxSurge/MaxUnavailable. With this regard:
35
35
is “buffer” for in-place, in-place update can proceed.
36
36
- When in-place is possible, the system should try to in-place update as many machines as possible.
37
37
In practice, this means that maxSurge might be not fully used (it is used only for scale up by one if maxUnavailable=0).
38
-
- No in-place updates are performed for workers machines when using rollout strategy on delete.
38
+
- No in-place updates are performed for workers machines when using rollout strategy `OnDelete`.
39
+
40
+
<asideclass="note warning">
41
+
42
+
<h1>Important!</h1>
43
+
44
+
Cluster API will call the in-place extensions only if the `InPlaceUpdates` feature flag is enabled.
45
+
46
+
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.
- All the objects will have the latest API version known by Cluster API.
119
129
- Only spec is provided, status fields are not included
120
-
- When more than one extension will be supported, the current state will already include changes that can handle in-place by other runtime extensions.
130
+
- 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.
- All the objects will have the latest API version known by Cluster API.
190
200
- Only spec is provided, status fields are not included
191
-
- When more than one extension will be supported, the current state will already include changes that can handle in-place by other runtime extensions.
201
+
- 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.
Copy file name to clipboardExpand all lines: docs/book/src/user/concepts.md
+13-1Lines changed: 13 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -49,12 +49,24 @@ A "Machine" is the declarative spec for an infrastructure component hosting a Ku
49
49
50
50
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.
51
51
52
-
#### Machine Immutability (In-place Update vs. Replace)
52
+
#### Machine Immutability (In-place update vs. Replace)
53
53
54
54
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.
55
55
56
56
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.
57
57
58
+
Over time several improvement have been applied to Cluster API in oder to perform machine rollout only when necessary and
59
+
for minimizing risks and impacts of this operation on users workloads.
60
+
61
+
Starting from Cluster API v1.12, users can intentionally trade off some of the benefits that they get of Machine immutability by
62
+
using Cluster API extensions points to add the capability to perform in-place updates under well-defined circumstances.
63
+
64
+
Notably, the Cluster API user experience will remain the same no matter of the in-place update feature is enabled
65
+
or not, because ultimately users should care ONLY about the desired state.
66
+
67
+
Cluster API is responsible to choose the best strategy to achieve desired state, and with the introduction of
68
+
update extensions, Cluster API is expanding the set of tools that can be used to achieve the desired state.
69
+
58
70
### MachineDeployment
59
71
60
72
A MachineDeployment provides declarative updates for Machines and MachineSets.
Copy file name to clipboardExpand all lines: docs/proposals/20240807-in-place-updates.md
+4-4Lines changed: 4 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -165,7 +165,7 @@ The responsibility to determine which Machine/MachineSet should be updated, the
165
165
166
166
We propose to extend KCP and MachineDeployment rollout workflows to call External Update Extensions, if defined.
167
167
168
-
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.
168
+
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.
169
169
170
170
This proposal introduces three new Lifecycle Hooks named `CanUpdateMachine`, `CanUpdateMachineSet` and `UpdateMachine` for communication between CAPI and external update implementers.
171
171
@@ -269,7 +269,7 @@ With `InPlaceUpdates` feature gate enabled, CAPI controllers will go through the
269
269
270
270
As a first step, CAPI controllers will compute the set of desired changes (current and desired state).
271
271
272
-
Then CAPI controllers will then iterate over the registered external updaters, requesting to each updater if it can handle required changes through the `CanUpdateMachineSet` (MachineDeployment) and `CanUpdateMachine` (KCP).
272
+
Then CAPI controllers will iterate over the registered external updaters, requesting each updater if it can handle required changes through the `CanUpdateMachineSet` (MachineDeployment) and `CanUpdateMachine` (KCP).
273
273
274
274
The changes supported by an updater can be the complete set of desired changes, a subset of them or an empty set, signaling it cannot handle any of the desired changes.
275
275
@@ -431,11 +431,11 @@ However, in-place updates might cause Nodes to become unhealthy while the update
431
431
432
432
### Examples
433
433
434
-
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.
434
+
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.
435
435
436
436
Note that these examples don't show all the low level details, the examples here are just to help communicate the vision.
437
437
438
-
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`.
438
+
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`.
439
439
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.
440
440
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.
0 commit comments