📖 doc: add update bootstrap template doc

docs/book/src/SUMMARY.md

@@ -13,7 +13,7 @@
     - [Upgrading Cluster API components](./tasks/upgrading-cluster-api-versions.md)
     - [Configure a MachineHealthCheck](./tasks/healthcheck.md)
     - [Kubeadm based control plane management](./tasks/kubeadm-control-plane.md)
-    - [Changing a Machine Template](./tasks/change-machine-template.md)
+    - [Updating Machine Infrastructure and Bootstrap Templates](tasks/updating-machine-templates.md)
     - [Using the Cluster Autoscaler](./tasks/cluster-autoscaler.md)
     - [Experimental Features](./tasks/experimental-features/experimental-features.md)
         - [MachinePools](./tasks/experimental-features/machine-pools.md)

docs/book/src/tasks/change-machine-template.md → docs/book/src/tasks/updating-machine-templates.md

@@ -1,4 +1,6 @@
-# Changing Infrastructure Machine Templates
+# Updating Machine Infrastructure and Bootstrap Templates
+
+## Updating Infrastructure Machine Templates
 
 Several different components of Cluster API leverage _infrastructure machine templates_,
 including `KubeadmControlPlane`, `MachineDeployment`, and `MachineSet`. These
@@ -38,3 +40,31 @@ modifications of certain infrastructure machine template fields. This may be use
 if an infrastructure provider is able to make changes to running instances/machines,
 such as updating allocated memory or CPU capacity. In such cases, however, Cluster
 API **will not** trigger a rolling update.
+
+## Updating Bootstrap Templates
+
+Several different components of Cluster API leverage _bootstrap templates_,
+including `MachineDeployment`, and `MachineSet`. When used in `MachineDeployment` or 
+`MachineSet` changes to those templates do not trigger rollouts of already existing `Machines`.
+New `Machines` are created based on the current version of the bootstrap template.
+
+The correct process for modifying a bootstrap template is as follows:
+
+1. Duplicate an existing template.
+   Users can use `kubectl get <BootstrapTemplateType> <name> -o yaml > file.yaml`
+   to retrieve a template configuration from a running cluster to serve as a starting
+   point.
+2. Update the desired fields.
+3. Give the newly-modified template a new name by modifying the `metadata.name` field
+   (or by using `metadata.generateName`).
+4. Create the new bootstrap template on the API server using `kubectl`.
+   (If the template was initially created using the command in step 1, be sure to clear
+   out any extraneous metadata, including the `resourceVersion` field, before trying to
+   send it to the API server.)
+
+Once the new bootstrap template has been persisted, users may modify
+the object that was referencing the bootstrap template. For example,
+to modify the bootstrap template for the `MachineDeployment` object,
+users would modify the `spec.template.spec.bootstrap.configRef.name` field.
+The `name` field should be updated to point to the newly-modified
+bootstrap template. This will trigger a rolling update.

docs/book/src/tasks/upgrading-clusters.md

@@ -77,7 +77,7 @@ but is the final step in fully upgrading a Cluster API managed cluster.
 It is recommended to manage machines with one or more `MachineDeployment`s. `MachineDeployment`s will
 transparently manage `MachineSet`s and `Machine`s to allow for a seamless scaling experience. A modification to the
 `MachineDeployment`s spec will begin a rolling update of the machines. Follow
-[these instructions](./change-machine-template.md) for changing the
+[these instructions](updating-machine-templates.md) for changing the
 template for an existing `MachineDeployment`.
 
 `MachineDeployment`s support different strategies for rolling out changes to `Machines`: