📖 Update contract documentation #12093

fabriziopandini · 2025-04-15T06:40:35Z

What this PR does / why we need it:
This PR updates v1beta2 contract documentation + compatibility with v1beta1

Which issue(s):
Rif #11947

/area documentation

docs/book/src/developer/providers/migrations/v1.10-to-v1.11.md

docs/book/src/developer/providers/contracts/control-plane.md

docs/book/src/developer/providers/contracts/infra-cluster.md

chrischdi · 2025-04-15T14:23:01Z

docs/book/src/developer/providers/contracts/bootstrap-config.md

-When the v1beta2 contract will be released (tentative Apr 2025), `status.initialization.dataSecretCreated` will be used
-instead of `status.ready`. However, `status.ready` will be supported until v1beta1 removal (~one year later).
+In order to ease the transition for providers, the v1beta2 version of the Cluster API contract _temporarily_
+preserve compatibility with the deprecated v1beta1 contract; compatibility will be removed tentatively in August 2026.


Suggested change

preserve compatibility with the deprecated v1beta1 contract; compatibility will be removed tentatively in August 2026.

preserves compatibility with the deprecated v1beta1 contract; compatibility will be removed tentatively in August 2026.

chrischdi · 2025-04-15T14:24:33Z

docs/book/src/developer/providers/contracts/bootstrap-config.md

- `message` (optional)
- `lastTransitionTime` (optional, if omitted, time.Now will be used)
+In order to ease the transition for providers, the v1beta2 version of the Cluster API contract _temporarily_
+preserve compatibility with the deprecated v1beta1 contract; compatibility will be removed tentatively in August 2026.


Suggested change

preserve compatibility with the deprecated v1beta1 contract; compatibility will be removed tentatively in August 2026.

preserves compatibility with the deprecated v1beta1 contract; compatibility will be removed tentatively in August 2026.

chrischdi · 2025-04-15T14:26:29Z

docs/book/src/developer/providers/contracts/bootstrap-config.md

+<h1>Compatibility with the deprecated v1beta1 contract</h1>
+
+In order to ease the transition for providers, the v1beta2 version of the Cluster API contract _temporarily_
+preserve compatibility with the deprecated v1beta1 contract; compatibility will be removed tentatively in August 2026.


Suggested change

preserve compatibility with the deprecated v1beta1 contract; compatibility will be removed tentatively in August 2026.

preserves compatibility with the deprecated v1beta1 contract; compatibility will be removed tentatively in August 2026.

chrischdi · 2025-04-15T14:26:57Z

docs/book/src/developer/providers/contracts/bootstrap-config.md

+
+In case a Bootstrap provider reports that a BootstrapConfig resource is in a state that cannot be recovered (terminal failure) by
+setting `status.failureReason` and `status.failureMessage` as defined by the deprecated v1beta1 contract, 
+the "core" Machine controller will surface those info in the corresponding fields within in Machine's `status.deprecatd.v1beta1` struct.


Suggested change

the "core" Machine controller will surface those info in the corresponding fields within in Machine's `status.deprecatd.v1beta1` struct.

the "core" Machine controller will surface those info in the corresponding fields within in Machine's `status.deprecated.v1beta1` struct.

chrischdi · 2025-04-15T14:27:06Z

docs/book/src/developer/providers/contracts/bootstrap-config.md


-See [Improving status in CAPI resources].
+After compatibility with the deprecated v1beta1 contract will be removed, `status.failureReason` and `status.failureMessage`
+fields in the BootstrapConfig resource will be ignored and Machine's `status.deprecatd.v1beta1` struct will be dropped.


Suggested change

fields in the BootstrapConfig resource will be ignored and Machine's `status.deprecatd.v1beta1` struct will be dropped.

fields in the BootstrapConfig resource will be ignored and Machine's `status.deprecated.v1beta1` struct will be dropped.

chrischdi · 2025-04-15T14:34:47Z

docs/book/src/developer/providers/contracts/infra-machine.md


-See [Improving status in CAPI resources].
+After compatibility with the deprecated v1beta1 contract will be removed, `status.failureReason` and `status.failureMessage`
+fields in the InfraMachine resource will be ignored and Machine's `status.deprecatd.v1beta1` struct will be dropped.


Suggested change

fields in the InfraMachine resource will be ignored and Machine's `status.deprecatd.v1beta1` struct will be dropped.

fields in the InfraMachine resource will be ignored and Machine's `status.deprecated.v1beta1` struct will be dropped.

chrischdi · 2025-04-15T14:35:47Z

docs/book/src/developer/providers/migrations/v1.10-to-v1.11.md

+  - The transition to the new K8s aligned conditions using `metav1.Conditions` types and the new condition semantic
+    has been completed for all Kinds:
+    - `status.conditions` has been replaced with `status.v1beta2.conditions`
+    - the old `status.conditions` will continue to exist temporarily under `status.deprecatd.v1beta1` for the sake of


Suggested change

- the old `status.conditions` will continue to exist temporarily under `status.deprecatd.v1beta1` for the sake of

- the old `status.conditions` will continue to exist temporarily under `status.deprecated.v1beta1` for the sake of

chrischdi · 2025-04-15T14:35:56Z

docs/book/src/developer/providers/migrations/v1.10-to-v1.11.md

+    - the old `status.conditions` will continue to exist temporarily under `status.deprecatd.v1beta1` for the sake of
+      down conversions and to provide a temporary option for users willing to continue using old conditions.
+  - Support for terminal errors has been dropped from all Kinds
+    - `status.failureReason` and `status.failureMessage` will continue to exist temporarily under `status.deprecatd.v1beta1`


Suggested change

- `status.failureReason` and `status.failureMessage` will continue to exist temporarily under `status.deprecatd.v1beta1`

- `status.failureReason` and `status.failureMessage` will continue to exist temporarily under `status.deprecated.v1beta1`

chrischdi · 2025-04-15T14:36:05Z

docs/book/src/developer/providers/migrations/v1.10-to-v1.11.md

+### Deprecation
+
+- v1beta1 API version is deprecated and it will be removed tentatively in August 2026 
+  - All the fields under `status.deprecatd.v1beta1` in the new v1beta2 API are deprecated and whey will be removed


Suggested change

- All the fields under `status.deprecatd.v1beta1` in the new v1beta2 API are deprecated and whey will be removed

- All the fields under `status.deprecated.v1beta1` in the new v1beta2 API are deprecated and whey will be removed

chrischdi · 2025-04-15T14:40:16Z

docs/book/src/developer/providers/migrations/v1.10-to-v1.11.md

+- Conditions utils for deprecated v1beta1 conditions have been moved to `util/conditions/deprecated/v1beta1`
+
+Also, please note that starting from the CAPI release when v1beta1 removal will happen (tentative Aug 2026), the Cluster API project
+will remove the Cluster API condition type, the `util/conditions` package, the code handling conditions in `util/patch.Helper`


Suggested change

will remove the Cluster API condition type, the `util/conditions` package, the code handling conditions in `util/patch.Helper`

will remove the Cluster API condition type, the `util/conditions/deprecated/v1beta1` package, the code handling conditions in `util/patch.Helper`

chrischdi · 2025-04-15T15:06:07Z

Two dead links, besides that lgtm!

/approve

k8s-ci-robot · 2025-04-15T15:06:17Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: chrischdi

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:

~~OWNERS~~ [chrischdi]

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

chrischdi · 2025-04-15T15:06:26Z

  ERROR: 2 dead links found in docs/book/src/developer/providers/migrations/overview.md !
  [✖] v1.7-to-v1.8.md → Status: 400
  [✖] #clusterapi-documentation-versions → Status: 404

chrischdi · 2025-04-15T15:43:25Z

/lgtm

k8s-ci-robot · 2025-04-15T15:43:33Z

LGTM label has been added.

Git tree hash: 648ff35e02cc051a72e4e09a88797124e336ad51

sbueringer · 2025-08-07T13:40:17Z

lgtm

k8s-ci-robot added area/documentation Issues or PRs related to documentation cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. labels Apr 15, 2025

k8s-ci-robot requested review from JoelSpeed and jackfrancis April 15, 2025 06:40

k8s-ci-robot added the size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. label Apr 15, 2025

Update contract documentation

f34d6d2

fabriziopandini force-pushed the document-v1beta2-contract branch from 4fd2f85 to f34d6d2 Compare April 15, 2025 06:50

Fix summary

4172344

fabriziopandini mentioned this pull request Apr 15, 2025

Tracking issue for v1Beta2 #11947

Closed

84 tasks

chrischdi reviewed Apr 15, 2025

View reviewed changes

Address comments

cf63169

fabriziopandini added the tide/merge-method-squash Denotes a PR that should be squashed by tide when it merges. label Apr 15, 2025

Fix broken link

95c9398

chrischdi reviewed Apr 15, 2025

View reviewed changes

more comments

f89c3d7

k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Apr 15, 2025

Fix more links

018e86b

k8s-ci-robot assigned chrischdi Apr 15, 2025

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Apr 15, 2025

k8s-ci-robot merged commit 81517d6 into kubernetes-sigs:main Apr 15, 2025
15 checks passed

k8s-ci-robot added this to the v1.11 milestone Apr 15, 2025

sbueringer mentioned this pull request Aug 7, 2025

📖 Fix small typo in contract docs #12593

Merged

fabriziopandini deleted the document-v1beta2-contract branch November 11, 2025 10:10

	preserve compatibility with the deprecated v1beta1 contract; compatibility will be removed tentatively in August 2026.
	preserves compatibility with the deprecated v1beta1 contract; compatibility will be removed tentatively in August 2026.

	the "core" Machine controller will surface those info in the corresponding fields within in Machine's `status.deprecatd.v1beta1` struct.
	the "core" Machine controller will surface those info in the corresponding fields within in Machine's `status.deprecated.v1beta1` struct.

	fields in the BootstrapConfig resource will be ignored and Machine's `status.deprecatd.v1beta1` struct will be dropped.
	fields in the BootstrapConfig resource will be ignored and Machine's `status.deprecated.v1beta1` struct will be dropped.

	fields in the InfraMachine resource will be ignored and Machine's `status.deprecatd.v1beta1` struct will be dropped.
	fields in the InfraMachine resource will be ignored and Machine's `status.deprecated.v1beta1` struct will be dropped.

	- the old `status.conditions` will continue to exist temporarily under `status.deprecatd.v1beta1` for the sake of
	- the old `status.conditions` will continue to exist temporarily under `status.deprecated.v1beta1` for the sake of

	- `status.failureReason` and `status.failureMessage` will continue to exist temporarily under `status.deprecatd.v1beta1`
	- `status.failureReason` and `status.failureMessage` will continue to exist temporarily under `status.deprecated.v1beta1`

	- All the fields under `status.deprecatd.v1beta1` in the new v1beta2 API are deprecated and whey will be removed
	- All the fields under `status.deprecated.v1beta1` in the new v1beta2 API are deprecated and whey will be removed

	will remove the Cluster API condition type, the `util/conditions` package, the code handling conditions in `util/patch.Helper`
	will remove the Cluster API condition type, the `util/conditions/deprecated/v1beta1` package, the code handling conditions in `util/patch.Helper`

📖 Update contract documentation #12093

📖 Update contract documentation #12093

Uh oh!

Conversation

fabriziopandini commented Apr 15, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chrischdi commented Apr 15, 2025

Uh oh!

k8s-ci-robot commented Apr 15, 2025

Uh oh!

chrischdi commented Apr 15, 2025

Uh oh!

chrischdi commented Apr 15, 2025

Uh oh!

k8s-ci-robot commented Apr 15, 2025

Uh oh!

Uh oh!

sbueringer commented Aug 7, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants