Merge pull request #820 from yiannistri/819-cp-changes

docs: Document `v1beta2` changes for control-plane CRs

Author: furkatgofurov7

docs/book/src/02_topics/09_secrets_encryption.md

@@ -2,13 +2,13 @@
 
 ## Overview
 
-By default, RKE2 enables Secret encryotion at rest with `aescbc` provider and generate private key automatically. [Refer](https://docs.rke2.io/security/secrets_encryption)
+By default, RKE2 enables Secrets encryption at rest with `aescbc` provider and generates private key automatically. [Reference](https://docs.rke2.io/security/secrets_encryption)
 
 ## Customizing Encryption provider
 
-To configure different provider (`aescbc` or `secretbox`) or specify encryption key explicitly configure `spec.serverConfig.secretsEncryption` block
+To configure different provider (`aescbc` or `secretbox`) or specify encryption key explicitly, configure `spec.serverConfig.secretsEncryption` block.
 
-Expample:
+Example:
 
 ```yaml
 apiVersion: controlplane.cluster.x-k8s.io/v1beta1
@@ -21,11 +21,11 @@ spec:
       provider: "secretbox"
       encryptionKeySecret:
         name: encryption-key
-        namespace: exmaple
+        namespace: example
 ```
 
 ## Encryption secret format
 
-When configuring the `encryptionKeySecret`, ensure the secret contains the following keys:
+When configuring the `encryptionKeySecret` field, ensure the secret contains the following keys:
 
 - **encryptionKey** - base64 decoded value of the encryption key

docs/book/src/05_reference/01_api_versions.md

@@ -0,0 +1,43 @@
+# API Versions
+
+This page provides a detailed list of any changes between different API versions of CAPRKE2. It is intended to assist end users when upgrading from one version of the API to the next one.
+
+### v1beta1 to v1beta2
+
+#### Control Plane
+
+In `v1beta1` the following fields were marked as `deprecated` and have been removed from `v1beta2`:
+- `infrastructureRef` has been removed from `RKE2ControlPlane.spec`. Use `RKE2ControlPlane.spec.machineTemplate.spec.infrastructureRef` instead.
+- `nodeDrainTimeout` has been removed from `RKE2ControlPlane.spec`. Use `RKE2ControlPlane.spec.machineTemplate.spec.deletion.nodeDrainTimeout` instead.
+
+The following `v1beta1` fields have moved:
+- `infrastructureRef` has moved from `RKE2ControlPlaneMachineTemplate` to `RKE2ControlPlaneMachineTemplateSpec.infrastructureRef` in `v1beta2`.
+- `nodeDrainTimeout`, `nodeVolumeDetachTimeout` and `nodeDeletionTimeout` have moved under `RKE2ControlPlaneMachineTemplateSpec.deletion` in `v1beta2` and have been renamed to:
+  - `deletion.nodeDrainTimeoutSeconds`
+  - `deletion.nodeVolumeDetachTimeoutSeconds`
+  - `deletion.nodeDeletionTimeoutSeconds`
+  
+  Note that these fields have changed their type to int32 and now expect a timeout expressed in seconds.
+
+The `RKE2ControlPlaneMachineTemplate` object in `v1beta2` now includes a `spec` field which is required.
+
+The following `v1beta1` `RKE2ControlPlaneStatus` fields have been moved under `RKE2ControlPlane.status.deprecated` in `v1beta2`:
+- `conditions`
+- `failureReason`
+- `failureMessage`
+- `updatedReplicas`
+- `readyReplicas`
+- `unavailableReplicas`
+
+In `v1beta1`, status conditions are using `clusterv1beta1.Conditions`, which are CAPI-specific condition types, whereas in `v1beta2` they are using `metav1.Conditions`, inline with upstream CAPI. The benefit of using `metav1.Conditions` is that it provides a standard way of reporting status that is common across many Kubernetes resource types ([reference](https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20240916-improve-status-in-CAPI-resources.md)).
+
+The following `RKE2ControlPlaneStatus` fields have been removed from `v1beta2`:
+- `ready`
+- `initialized`
+- `dataSecretName`
+- `failureReason`
+- `failureMessage`
+- `updatedReplicas`
+- `unavailableReplicas`
+
+An RKE2 cluster is considered initialized when `RKE2ControlPlaneStatus.initialization.controlPlaneInitialized` is set to `true`. 

docs/book/src/SUMMARY.md

@@ -12,6 +12,7 @@
     - [Configuring manager options](./02_topics/06_configure-manager-options.md)
     - [External load balancer exclusion](./02_topics/07_load_balancer_exclusion.md)
     - [External datastore](./02_topics/08_external_datastore.md)
+    - [Secrets encryption](./02_topics/09_secrets_encryption.md)
 - [Examples](./03_examples/00.md)
     - [AWS](./03_examples/01_aws.md)
     - [vSphere](./03_examples/02_vsphere.md)
@@ -20,3 +21,4 @@
     - [Development](./04_developer/01_development.md)
     - [Releasing](./04_developer/02_releasing.md)
 - [Reference](./05_reference/00.md)
+    - [API Versions](./05_reference/01_api_versions.md)