📖 Document the immutability of machine templates #3105
Conversation
k8s-ci-robot
added
the
cncf-cla: yes
|
Hi @scottslowe. Thanks for your PR. I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with Once the patch is verified, the new status will be reflected by the I understand the commands that are listed here. 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. |
k8s-ci-robot
added
the
needs-ok-to-test
k8s-ci-robot
added
the
size/S
|
/ok-to-test |
k8s-ci-robot
added
ok-to-test
|
@scottslowe would you mind breaking long lines at ~100 characters? It makes it easier to comment. Thanks! |
k8s-ci-robot
added
size/M
|
@ncdc Done, sorry about that! |
|
|
||
| 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 |
There was a problem hiding this comment.
xref kubernetes-sigs/cluster-api-provider-aws#1711. I know you mention at the bottom that providers may decide to support some field changes, but I wonder if we should highlight this use case here, or soften/clarify the immutable bit here?
There was a problem hiding this comment.
Addressed via af55bb4.
| `MachineDeployment`s spec will begin a rolling update of the workload machines. | ||
| `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 |
There was a problem hiding this comment.
Given that infrastructure provider might relax the immutability, here I suggest to simplify an simply link the other page. e.g.
follow these instruction for changing the template for an existing MachineDeployment
There was a problem hiding this comment.
Changes incorporated into af55bb4.
| 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 | ||
| 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. |
There was a problem hiding this comment.
Or using metadata.generateName?
There was a problem hiding this comment.
Added via af55bb4.
|
thanks @scottslowe |
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: fabriziopandini, scottslowe The full list of commands accepted by this bot can be found here. The pull request process is described here
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
k8s-ci-robot
added
the
approved
| 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`. |
There was a problem hiding this comment.
If you saved to disk as indicated in step 1, you'll also need to clear out the resource version before trying to send it to the apiserver.
There was a problem hiding this comment.
@ncdc Should I omit this command entirely? Is there a better way to generate a new machine template?
There was a problem hiding this comment.
I would just add a parenthetical that says make sure you clear out the RV
|
LGTM. Please squash. Thanks! |
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 <[email protected]>
|
@ncdc Commits squashed, thanks! |
|
/lgtm |
k8s-ci-robot
added
the
lgtm
What this PR does / why we need it:
This PR adds documentation regarding the immutability of machine templates, and provides information on the recommended process for modifying a machine template. This PR adds a new page, a link to the sidebar, and modifies the Tasks/KCP page to reference the new page.
Which issue(s) this PR fixes (optional, in
fixes #<issue number>(, fixes #<issue_number>, ...)format, will close the issue(s) when PR gets merged):Fixes #2557