sigs.k8s.io/cluster-api@v1.7.1/docs/book/src/tasks/experimental-features/cluster-class/change-clusterclass.md (about) 1 # Changing a ClusterClass 2 3 ## Selecting a strategy 4 5 When planning a change to a ClusterClass, users should always take into consideration 6 how those changes might impact the existing Clusters already using the ClusterClass, if any. 7 8 There are two strategies for defining how a ClusterClass change rolls out to existing Clusters: 9 10 - Roll out ClusterClass changes to existing Cluster in a controlled/incremental fashion. 11 - Roll out ClusterClass changes to all the existing Cluster immediately. 12 13 The first strategy is the recommended choice for people starting with ClusterClass; it 14 requires the users to create a new ClusterClass with the expected changes, and then 15 [rebase](#rebase) each Cluster to use the newly created ClusterClass. 16 17 By splitting the change to the ClusterClass and its rollout 18 to Clusters into separate steps the user will reduce the risk of introducing unexpected 19 changes on existing Clusters, or at least limit the blast radius of those changes 20 to a small number of Clusters already rebased (in fact it is similar to a canary deployment). 21 22 The second strategy listed above instead requires changing a ClusterClass "in place", which can 23 be simpler and faster than creating a new ClusterClass. However, this approach 24 means that changes are immediately propagated to all the Clusters already using the 25 modified ClusterClass. Any operation involving many Clusters at the same time has intrinsic risks, 26 and it can impact heavily on the underlying infrastructure in case the operation triggers 27 machine rollout across the entire fleet of Clusters. 28 29 However, regardless of which strategy you are choosing to implement your changes to a ClusterClass, 30 please make sure to: 31 32 - [Plan ClusterClass changes](#planning-clusterclass-changes) before applying them. 33 - Understand what [Compatibility Checks](#compatibility-checks) are and how to prevent changes 34 that can lead to non-functional Clusters. 35 36 If instead you are interested in understanding more about which kind of 37 effects you should expect on the Clusters, or if you are interested in additional details 38 about the internals of the topology reconciler you can start reading the notes in the 39 [Plan ClusterClass changes](#planning-clusterclass-changes) documentation or looking at the [reference](#reference) 40 documentation at the end of this page. 41 42 ## Changing ClusterClass templates 43 44 Templates are an integral part of a ClusterClass, and thus the same considerations 45 described in the previous paragraph apply. When changing 46 a template referenced in a ClusterClass users should also always plan for how the 47 change should be propagated to the existing Clusters and choose the strategy that best 48 suits expectations. 49 50 According to the [Cluster API operational practices](../../updating-machine-templates.md), 51 the recommended way for updating templates is by template rotation: 52 - Create a new template 53 - Update the template reference in the ClusterClass 54 - Delete the old template 55 56 <aside class="note"> 57 <h1>In place template mutations</h1> 58 59 In case a provider supports in place template mutations, the Cluster API topology controller 60 will adapt to them during the next reconciliation, but the system is not watching for those changes. 61 Meaning, when the underlying template is updated the changes 62 may not be reflected immediately, however they will be picked up during the next full reconciliation. 63 The maximum time for the next full reconciliation is equal to the CAPI controller 64 sync period (defaults to 10 minutes). 65 66 </aside> 67 68 <aside class="note warning"> 69 <h1>Reusing templates across ClusterClasses</h1> 70 71 As already discussed in [writing a cluster class](write-clusterclass.md), while it is technically possible to 72 re-use a template across ClusterClasses, this practice is not recommended because it makes it difficult 73 to reason about the impact of changing such a template can have on existing Clusters. 74 75 </aside> 76 77 Also in case of changes to the ClusterClass templates, please make sure to: 78 79 - [Plan ClusterClass changes](#planning-clusterclass-changes) before applying them. 80 - Understand what [Compatibility Checks](#compatibility-checks) are and how to prevent changes 81 that can lead to non-functional Clusters. 82 83 You can learn more about this reading the notes in the [Plan ClusterClass changes](#planning-clusterclass-changes) documentation or 84 looking at the [reference](#reference) documentation at the end of this page. 85 86 ## Rebase 87 88 Rebasing is an operational practice for transitioning a Cluster from one ClusterClass to another, 89 and the operation can be triggered by simply changing the value in `Cluster.spec.topology.class`. 90 91 Also in this case, please make sure to: 92 93 - [Plan ClusterClass changes](#planning-clusterclass-changes) before applying them. 94 - Understand what [Compatibility Checks](#compatibility-checks) are and how to prevent changes 95 that can lead to non-functional Clusters. 96 97 You can learn more about this reading the notes in the [Plan ClusterClass changes](#planning-clusterclass-changes) documentation or 98 looking at the [reference](#reference) documentation at the end of this page. 99 100 ## Compatibility Checks 101 102 When changing a ClusterClass, the system validates the required changes according to 103 a set of "compatibility rules" in order to prevent changes which would lead to a non-functional 104 Cluster, e.g. changing the InfrastructureProvider from AWS to Azure. 105 106 If the proposed changes are evaluated as dangerous, the operation is rejected. 107 108 <aside class="note warning"> 109 <h1>Warning</h1> 110 111 In the current implementation there are no compatibility rules for changes to provider 112 templates, so you should refer to the provider documentation to avoid 113 potentially dangerous changes on those objects. 114 115 </aside> 116 117 For additional info see [compatibility rules](https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20210526-cluster-class-and-managed-topologies.md#clusterclass-compatibility) 118 defined in the ClusterClass proposal. 119 120 ## Planning ClusterClass changes 121 122 It is highly recommended to always generate a plan for ClusterClass changes before applying them, 123 no matter if you are creating a new ClusterClass and rebasing Clusters or if you are changing 124 your ClusterClass in place. 125 126 The clusterctl tool provides a new alpha command for this operation, [clusterctl alpha topology plan](../../../clusterctl/commands/alpha-topology-plan.md). 127 128 The output of this command will provide you all the details about how those changes would impact 129 Clusters, but the following notes can help you to understand what you should 130 expect when planning your ClusterClass changes: 131 132 - Users should expect the resources in a Cluster (e.g. MachineDeployments) to behave consistently 133 no matter if a change is applied via a ClusterClass or directly as you do in a Cluster without 134 a ClusterClass. In other words, if someone changes something on a KCP object triggering a 135 control plane Machines rollout, you should expect the same to happen when the same change 136 is applied to the KCP template in ClusterClass. 137 138 - User should expect the Cluster topology to change consistently irrespective of how the change has been 139 implemented inside the ClusterClass or applied to the ClusterClass. In other words, 140 if you change a template field "in place", or if you rotate the template referenced in the 141 ClusterClass by pointing to a new template with the same field changed, or if you change the 142 same field via a patch, the effects on the Cluster are the same. 143 144 See [reference](#reference) for more details. 145 146 ## Reference 147 148 ### Effects on the Clusters 149 150 The following table documents the effects each ClusterClass change can have on a Cluster; 151 Similar considerations apply to changes introduced by changes in `Cluster.Topology` or by 152 changes introduced by patches. 153 154 NOTE: for people used to operating Cluster API without Cluster Class, it could also help to keep in mind that the 155 underlying objects like control plane and MachineDeployment act in the same way with and without a ClusterClass. 156 157 | Changed field | Effects on Clusters | 158 |---------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 159 | infrastructure.ref | Corresponding InfrastructureCluster objects are updated (in place update). | 160 | controlPlane.metadata | If labels/annotations are added, changed or deleted the ControlPlane objects are updated (in place update).<br /><br /> In case of KCP, corresponding controlPlane Machines, KubeadmConfigs and InfrastructureMachines are updated in-place. | 161 | controlPlane.ref | Corresponding ControlPlane objects are updated (in place update). <br /> If updating ControlPlane objects implies changes in the spec, the corresponding ControlPlane Machines are updated accordingly (rollout). | 162 | controlPlane.machineInfrastructure.ref | If the referenced template has changes only in metadata labels or annotations, the corresponding InfrastructureMachineTemplates are updated (in place update). <br /> <br />If the referenced template has changes in the spec:<br /> - Corresponding InfrastructureMachineTemplate are rotated (create new, delete old)<br /> - Corresponding ControlPlane objects are updated with the reference to the newly created template (in place update)<br /> - The corresponding controlPlane Machines are updated accordingly (rollout). | 163 | controlPlane.nodeDrainTimeout | If the value is changed the ControlPlane object is updated in-place.<br/> <br/> In case of KCP, the change is propagated in-place to control plane Machines. | 164 | controlPlane.nodeVolumeDetachTimeout | If the value is changed the ControlPlane object is updated in-place.<br/> <br/> In case of KCP, the change is propagated in-place to control plane Machines. | 165 | controlPlane.nodeDeletionTimeout | If the value is changed the ControlPlane object is updated in-place.<br/> <br/> In case of KCP, the change is propagated in-place to control plane Machines. | 166 | workers.machineDeployments | If a new MachineDeploymentClass is added, no changes are triggered to the Clusters. <br />If an existing MachineDeploymentClass is changed, effect depends on the type of change (see below). | 167 | workers.machineDeployments[].template.metadata | If labels/annotations are added, changed or deleted the MachineDeployment objects are updated (in place update) and corresponding worker Machines are updated (in-place). | 168 | workers.machineDeployments[].template.bootstrap.ref | If the referenced template has changes only in metadata labels or annotations, the corresponding BootstrapTemplates are updated (in place update).<br /> <br />If the referenced template has changes in the spec:<br /> - Corresponding BootstrapTemplate are rotated (create new, delete old). <br /> - Corresponding MachineDeployments objects are updated with the reference to the newly created template (in place update). <br /> - The corresponding worker machines are updated accordingly (rollout) | 169 | workers.machineDeployments[].template.infrastructure.ref | If the referenced template has changes only in metadata labels or annotations, the corresponding InfrastructureMachineTemplates are updated (in place update). <br /> <br />If the referenced template has changes in the spec:<br /> - Corresponding InfrastructureMachineTemplate are rotated (create new, delete old).<br /> - Corresponding MachineDeployments objects are updated with the reference to the newly created template (in place update). <br /> - The corresponding worker Machines are updated accordingly (rollout) | 170 | workers.machineDeployments[].template.nodeDrainTimeout | If the value is changed the MachineDeployment is updated in-place.<br/> <br/> The change is propagated in-place to the MachineDeployment Machine. | 171 | workers.machineDeployments[].template.nodeVolumeDetachTimeout | If the value is changed the MachineDeployment is updated in-place.<br/> <br/> The change is propagated in-place to the MachineDeployment Machine. | 172 | workers.machineDeployments[].template.nodeDeletionTimeout | If the value is changed the MachineDeployment is updated in-place.<br/> <br/> The change is propagated in-place to the MachineDeployment Machine. | 173 | workers.machineDeployments[].template.minReadySeconds | If the value is changed the MachineDeployment is updated in-place. | 174 175 ### How the topology controller reconciles template fields 176 177 The topology reconciler enforces values defined in the ClusterClass templates into the topology 178 owned objects in a Cluster. 179 180 More specifically, the topology controller uses [Server Side Apply](https://kubernetes.io/docs/reference/using-api/server-side-apply/) 181 to write/patch topology owned objects; using SSA allows other controllers to co-author the generated objects, 182 like e.g. adding info for subnets in CAPA. 183 184 <aside class="note"> 185 <h1>What about patches?</h1> 186 187 The considerations above apply also when using patches, the only difference being that the 188 set of fields that are enforced should be determined by applying patches on top of the templates. 189 190 </aside> 191 192 A corollary of the behaviour described above is that it is technically possible to change fields in the object 193 which are not derived from the templates and patches, but we advise against using the possibility 194 or making ad-hoc changes in generated objects unless otherwise needed for a workaround. It is always 195 preferable to improve ClusterClasses by supporting new Cluster variants in a reusable way.