From af55bb4b6120f421d59b0ad0bcfd5675a8b121c0 Mon Sep 17 00:00:00 2001 From: Scott Lowe Date: Thu, 28 May 2020 15:30:41 -0600 Subject: [PATCH] Incorporate reviewer feedback Fix typo (change "update" to "updated"). Soften wording regarding immutability of machine templates. Fix link that was causing problems with CI. Change wording regarding Azure VMs. Simplify the link from KCP page to new page on changing templates. Add reference to using `metadata.generateName`. Signed-off-by: Scott Lowe --- docs/book/src/tasks/change-machine-template.md | 14 ++++++++------ docs/book/src/tasks/kubeadm-control-plane.md | 7 +++---- 2 files changed, 11 insertions(+), 10 deletions(-) diff --git a/docs/book/src/tasks/change-machine-template.md b/docs/book/src/tasks/change-machine-template.md index abf5d7e2b8df..c39ff8a8c992 100644 --- a/docs/book/src/tasks/change-machine-template.md +++ b/docs/book/src/tasks/change-machine-template.md @@ -2,8 +2,8 @@ Several different components of Cluster API leverage _infrastructure machine templates_, including `KubeadmControlPlane`, `MachineDeployment`, and `MachineSet`. These -`MachineTemplate` resources are **immutable** and are not intended to be modified -directly. +`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: @@ -13,9 +13,10 @@ The correct process for modifying an infrastructure machine template is as follo 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 machine type). Refer to the provider-specific documentation + 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. +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`. Once the new infrastructure machine template has been persisted, users may modify @@ -23,10 +24,11 @@ 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 update to point to the newly-modified +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.html#how-to-upgrade-the-underlying-machine-image).) +KubeadmControlPlane](./kubeadm-control-plane.html) 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 diff --git a/docs/book/src/tasks/kubeadm-control-plane.md b/docs/book/src/tasks/kubeadm-control-plane.md index 1516729cb67a..56d300efff5a 100644 --- a/docs/book/src/tasks/kubeadm-control-plane.md +++ b/docs/book/src/tasks/kubeadm-control-plane.md @@ -39,10 +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. As described in -[this section on changing a `MachineTemplate`](./change-machine-template.md), infrastructure machine -templates are immutable and should not be modified directly; follow the instructions there for -changing the template for a `MachineDeployment`. +`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