sigs.k8s.io/cluster-api@v1.7.1/docs/book/src/tasks/updating-machine-templates.md (about)

     1  # Updating Machine Infrastructure and Bootstrap Templates
     2  
     3  ## Updating Infrastructure Machine Templates
     4  
     5  Several different components of Cluster API leverage _infrastructure machine templates_,
     6  including `KubeadmControlPlane`, `MachineDeployment`, and `MachineSet`. These
     7  `MachineTemplate` resources should be immutable, unless the infrastructure provider
     8  documentation indicates otherwise for certain fields (see below for more details).
     9  
    10  The correct process for modifying an infrastructure machine template is as follows:
    11  
    12  1. Duplicate an existing template.
    13      Users can use `kubectl get <MachineTemplateType> <name> -o yaml > file.yaml`
    14      to retrieve a template configuration from a running cluster to serve as a starting
    15      point.
    16  2. Update the desired fields.
    17      Fields that might need to be modified could include the SSH key, the AWS instance
    18      type, or the Azure VM size. Refer to the provider-specific documentation
    19      for more details on the specific fields that each provider requires or accepts.
    20  3. Give the newly-modified template a new name by modifying the `metadata.name` field
    21      (or by using `metadata.generateName`).
    22  4. Create the new infrastructure machine template on the API server using `kubectl`.
    23      (If the template was initially created using the command in step 1, be sure to clear
    24      out any extraneous metadata, including the `resourceVersion` field, before trying to
    25      send it to the API server.)
    26  
    27  Once the new infrastructure machine template has been persisted, users may modify
    28  the object that was referencing the infrastructure machine template. For example,
    29  to modify the infrastructure machine template for the `KubeadmControlPlane` object,
    30  users would modify the `spec.infrastructureTemplate.name` field. For a `MachineDeployment`, users would need to modify the `spec.template.spec.infrastructureRef.name`
    31  field and the controller would orchestrate the upgrade by managing `MachineSets` pointing to the new and old references. In the case of a `MachineSet` with no `MachineDeployment` owner, if its template reference is changed, it will only affect upcoming Machines.
    32  
    33  In all cases, the `name` field should be updated to point to the newly-modified
    34  infrastructure machine template. This will trigger a rolling update. (This same process
    35  is described in the documentation for [upgrading the underlying machine image for
    36  KubeadmControlPlane](./control-plane/kubeadm-control-plane.md) in the "How to upgrade the underlying
    37  machine image" section.)
    38  
    39  Some infrastructure providers _may_, at their discretion, choose to support in-place
    40  modifications of certain infrastructure machine template fields. This may be useful
    41  if an infrastructure provider is able to make changes to running instances/machines,
    42  such as updating allocated memory or CPU capacity. In such cases, however, Cluster
    43  API **will not** trigger a rolling update.
    44  
    45  ## Updating Bootstrap Templates
    46  
    47  Several different components of Cluster API leverage _bootstrap templates_,
    48  including `MachineDeployment`, and `MachineSet`. When used in `MachineDeployment` or 
    49  `MachineSet` changes to those templates do not trigger rollouts of already existing `Machines`.
    50  New `Machines` are created based on the current version of the bootstrap template.
    51  
    52  The correct process for modifying a bootstrap template is as follows:
    53  
    54  1. Duplicate an existing template.
    55     Users can use `kubectl get <BootstrapTemplateType> <name> -o yaml > file.yaml`
    56     to retrieve a template configuration from a running cluster to serve as a starting
    57     point.
    58  2. Update the desired fields.
    59  3. Give the newly-modified template a new name by modifying the `metadata.name` field
    60     (or by using `metadata.generateName`).
    61  4. Create the new bootstrap template on the API server using `kubectl`.
    62     (If the template was initially created using the command in step 1, be sure to clear
    63     out any extraneous metadata, including the `resourceVersion` field, before trying to
    64     send it to the API server.)
    65  
    66  Once the new bootstrap template has been persisted, users may modify
    67  the object that was referencing the bootstrap template. For example,
    68  to modify the bootstrap template for the `MachineDeployment` object,
    69  users would modify the `spec.template.spec.bootstrap.configRef.name` field.
    70  The `name` field should be updated to point to the newly-modified
    71  bootstrap template. This will trigger a rolling update.