📖 docs: machinepool contract spec

[richardcase]

What this PR does / why we need it:

This adds documentation that details the contract for providers when implementing an infrastructure machine pool.

This has been created retrospectively from looking at a number of providers and the MachinePool controller.

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 #12799

/area machinepool

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: richardcase / name: Richard Case (3e61afd, 4d5a858, 6191a7e, a46efce, c0f0cca)

[fabriziopandini]

Thanks for this PR!
This really helps folks like me to step up knowledge about MachinePools!

[sbueringer]

/assign

Would like to review after Fabrizio lgtm and before merge

[richardcase]

Thanks for your feedback @fabriziopandini . I will make updates based on this.

[richardcase]

@fabriziopandini - i have updated the doc based on your feedback.

[bnallapeta]

@richardcase are we not going to document anything on the upgrades? My understanding is that the status would change based on the update strategy. For example:

Atomic updates:

• status.replicas temporarily drops to 0
• All providerIDs disappear then reappear
• InfrastructureReady may flip to False

Rolling updates:

• status.replicas stays >= desired (with surge) or slightly below
• providerIDs change gradually (old removed, new added)
• InfrastructureReady stays True

Should providers declare their update strategy in the contract so CAPI can adapt behavior accordingly?

[richardcase]

Should providers declare their update strategy in the contract so CAPI can adapt behavior accordingly?

@bnallapeta - i think we should follow up on this as we are trying to document the current state of the contract. Providers declaring an "update strategy" would be a change to the current contract.

We are going to need to update the MachinePool controller document based on the introduction of this contract doc. Perhaps we should include behaviour type stuff when we do that?

[bnallapeta]

@richardcase quoting from #10496,

Furthermore I don't know if there is a documented contract as of today for MachinePools how BootstrapConfigs are supposed to be rolled out. I also don't know if MachinePools behave the same across providers today.

I think we should talk about this in the contract. A few questions on this:

Should providers watch for bootstrap config changes and trigger updates? If yes, what's the signal? Hash of the secret data? ConfigRef version?

[richardcase]

Note for the maintainers, i will squash the commits when we are all happy with the doc.

[richardcase]

Should providers watch for bootstrap config changes and trigger updates? If yes, what's the signal? Hash of the secret data? ConfigRef version?

I agree i do think we need to document this in the MachinPools documentation. However, i don't think this sits in the contract document. Lets add this elsewhere, perhaps where i suggested earlier: https://cluster-api.sigs.k8s.io/developer/core/controllers/machine-pool when we make changes to that.

[chrischdi]

Note for the maintainers, i will squash the commits when we are all happy with the doc.

no need to

/label tide/merge-method-squash

[sbueringer]

@richardcase Do you have time to address the final findings so we can merge this PR? Thx!

[richardcase]

Do you have time to address the final findings so we can merge this PR? Thx!

I do. Sorry for the delay, i kind of got consumed by some downstream work. Chatting with Fabrizio in a bit to clarify a point, and then I'll get the last edits done today.

[richardcase]

This should be good to go now.

[AndiDog]

LGTM

[fabriziopandini]

last nit from my side, otherwise lgtm

[fabriziopandini]

/lgtm
/approve

[k8s-ci-robot]

LGTM label has been added.

Details

Git tree hash: 3ad8026321ebcdfec493166786e39e7f8b5ec2af

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: fabriziopandini

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• OWNERS [fabriziopandini]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[fabriziopandini]

Thanks @richardcase!
It is great to see foundations being set for the required work for the MachinePool

[fabriziopandini]

/cherry-pick release-1.12

[k8s-infra-cherrypick-robot]

@fabriziopandini: once the present PR merges, I will cherry-pick it on top of release-1.12 in a new PR and assign it to you.

Details

In response to this:

/cherry-pick release-1.12

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-sigs/prow repository.

[k8s-infra-cherrypick-robot]

@fabriziopandini: new pull request created: #13098

Details

In response to this:

/cherry-pick release-1.12

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-sigs/prow repository.