From e5f05ce90a67df9ac3eac4ff5c9fab6ccd3540df Mon Sep 17 00:00:00 2001 From: Scott Lowe Date: Fri, 29 May 2020 11:42:05 -0600 Subject: [PATCH] Document the immutability of machine templates Add documentation regarding the immutability of machine templates. Add new document to book summary. Create link from existing KCP page. Signed-off-by: Scott Lowe --- docs/book/src/SUMMARY.md | 1 + .../book/src/tasks/change-machine-template.md | 40 +++++++++++++++++++ docs/book/src/tasks/kubeadm-control-plane.md | 4 +- 3 files changed, 44 insertions(+), 1 deletion(-) create mode 100644 docs/book/src/tasks/change-machine-template.md diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md index c6bf7bba8c4e..b2a6729502bd 100644 --- a/docs/book/src/SUMMARY.md +++ b/docs/book/src/SUMMARY.md @@ -11,6 +11,7 @@ - [Upgrade](./tasks/upgrade.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) - [clusterctl CLI](./clusterctl/overview.md) - [clusterctl Commands](clusterctl/commands/commands.md) - [init](clusterctl/commands/init.md) diff --git a/docs/book/src/tasks/change-machine-template.md b/docs/book/src/tasks/change-machine-template.md new file mode 100644 index 000000000000..04c03b89b75d --- /dev/null +++ b/docs/book/src/tasks/change-machine-template.md @@ -0,0 +1,40 @@ +# Changing Infrastructure Machine Templates + +Several different components of Cluster API leverage _infrastructure machine templates_, +including `KubeadmControlPlane`, `MachineDeployment`, and `MachineSet`. These +`MachineTemplate` resources should be immutable, unless the infrastructure provider +documentation indicates otherwise for certain fields (see below for more details). + +The correct process for modifying an infrastructure machine template is as follows: + +1. Duplicate an existing template. + Users can use `kubectl get -o yaml > file.yaml` + to retrieve a template configuration from a running cluster to serve as a starting + point. +2. Update the desired fields. + Fields that might need to be modified could include the SSH key, the AWS instance + type, or the Azure VM size. Refer to the provider-specific documentation + for more details on the specific fields that each provider requires or accepts. +3. Give the newly-modified template a new name by modifying the `metadata.name` field + (or by using `metadata.generateName`). +4. Create the new infrastructure machine 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 infrastructure machine template has been persisted, users may modify +the object that was referencing the infrastructure machine template. For example, +to modify the infrastructure machine template for the `KubeadmControlPlane` object, +users would modify the `spec.infrastructureTemplate.name` field. For a `MachineDeployment` +or `MachineSet`, users would need to modify the `spec.template.spec.infrastructureRef.name` +field. In all cases, the `name` field should be updated to point to the newly-modified +infrastructure machine template. This will trigger a rolling update. (This same process +is described in the documentation for [upgrading the underlying machine image for +KubeadmControlPlane](./kubeadm-control-plane.md) in the "How to upgrade the underlying +machine image" section.) + +Some infrastructure providers _may_, at their discretion, choose to support in-place +modifications of certain infrastructure machine template fields. This may be useful +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. diff --git a/docs/book/src/tasks/kubeadm-control-plane.md b/docs/book/src/tasks/kubeadm-control-plane.md index a232a3ee8e35..cd3400c6764f 100644 --- a/docs/book/src/tasks/kubeadm-control-plane.md +++ b/docs/book/src/tasks/kubeadm-control-plane.md @@ -39,7 +39,9 @@ but is the final step in fully upgrading a Cluster API managed cluster. It is recommended to manage workload 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 workload machines. +`MachineDeployment`s spec will begin a rolling update of the workload machines. Follow +[these instructions](./change-machine-template.md) for changing the +template for an existing `MachineDeployment`. For a more in-depth look at how `MachineDeployments` manage scaling events, take a look at the [`MachineDeployment` controller documentation](../developer/architecture/controllers/machine-deployment.md) and the [`MachineSet` controller