Document infrastructure machine templates & immutability

[ncdc]

We should document that when using infrastructure machine templates (e.g. in KubeadmControlPlane, MachineDeployment, MachineSet), these templates are generally meant to be immutable. If you want to change a field in one of these templates (e.g. AWS instance type), the typical process is to duplicate an existing template, update field(s), give it a new name, and create it in the apiserver. Once the new template has been persisted, then modify the KubeadmControlPlane/MachineDeployment/MachineSet to have it reference the new template. This will trigger a rolling update.

One caveat, is that some infrastructure providers, at their discretion, can choose to support in-place modifications of certain template fields, as long as they understand that Cluster API WILL NOT trigger a rolling update. This could be helpful if an infrastructure provider is able to do a live change for something like # of CPUs or memory.

/kind documentation
/help
/milestone Next

[k8s-ci-robot]

@ncdc:
This request has been marked as needing help from a contributor.

Please ensure the request meets the requirements listed here.

If this request no longer meets these requirements, the label can be removed
by commenting with the /remove-help command.

In response to this:

We should document that when using infrastructure machine templates (e.g. in KubeadmControlPlane, MachineDeployment, MachineSet), these templates are generally meant to be immutable. If you want to change a field in one of these templates (e.g. AWS instance type), the typical process is to duplicate an existing template, update field(s), give it a new name, and create it in the apiserver. Once the new template has been persisted, then modify the KubeadmControlPlane/MachineDeployment/MachineSet to have it reference the new template. This will trigger a rolling update.

One caveat, is that some infrastructure providers, at their discretion, b choose to support in-place modifications of certain template fields, as long as they understand that Cluster API WILL NOT trigger a rolling update. This could be helpful if an infrastructure provider is able to do a live change for something like # of CPUs or memory.

/kind documentation
/help
/milestone Next

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[scottslowe]

I'd like to help with this issue. Do we anticipate this would create a new standalone doc somewhere (like in the docs directory), or that it should be a new page/section in the book?

[ncdc]

It should show up on our docs site, so it'll need to go somewhere in docs/book/src. I'm not sure off the top of my head where the best place in there is. Do you have any thoughts?

[scottslowe]

Perhaps in the “Tasks” section, with a title like “Changing Infrastructure Machine Templates” or similar?

[ncdc]

SGTM. We can always move it around later if needed.

[scottslowe]

/assign

[scottslowe]

PR submitted, appreciate any feedback.