📖 docs: machinepool contract spec (#12971)

* docs: machinepool contract spec

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.

Signed-off-by: Richard Case <[email protected]>

* doc: review changes

Changes after the first review by Fabrizio.

Signed-off-by: Richard Case <[email protected]>

* doc: review changes

Changes after the first review by Fabrizio.

Signed-off-by: Richard Case <[email protected]>

* docs: updates after second review

Some updates after an additional review by Andreas.

Signed-off-by: Richard Case <[email protected]>

* docs: incorporate feedback from review

Various updates after review by Fabrizio and Andreas. Specifically:

- Making it clearer what is preferred state vs current deprecated
- Rewording some parts to be clearer.

Signed-off-by: Richard Case <[email protected]>

---------

Signed-off-by: Richard Case <[email protected]>

Author: richardcase

docs/book/src/SUMMARY.md

@@ -95,6 +95,7 @@
         - [Provider contracts](developer/providers/contracts/overview.md)
           - [InfraCluster](./developer/providers/contracts/infra-cluster.md)
           - [InfraMachine](developer/providers/contracts/infra-machine.md)
+          - [InfraMachinePool](developer/providers/contracts/infra-machinepool.md)
           - [BootstrapConfig](developer/providers/contracts/bootstrap-config.md)
           - [ControlPlane](developer/providers/contracts/control-plane.md)
           - [clusterctl](developer/providers/contracts/clusterctl.md)