Merge pull request #12418 from sbueringer/pr-contract-optional-fields

📖 Align v1beta2 contract to API conventions around optional fields

Author: k8s-ci-robot

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

@@ -199,7 +199,20 @@ type FooConfigList struct {
 
 ### BootstrapConfig: data secret
 
-Each BootstrapConfig MUST store generated bootstrap data into a Kubernetes Secret.
+Each BootstrapConfig MUST store generated bootstrap data into a Kubernetes Secret and surface the secret name in .status.dataSecretName.
+
+```go
+type FooConfigStatus struct {
+    // dataSecretName is the name of the secret that stores the bootstrap data script.
+    // +optional
+    // +kubebuilder:validation:MinLength=1
+    // +kubebuilder:validation:MaxLength=253
+    DataSecretName string `json:"dataSecretName,omitempty"`
+
+    // See other rules for more details about mandatory/optional fields in BootstrapConfig status.
+    // Other fields SHOULD be added based on the needs of your provider.
+}
+```
 
 The Secret containing bootstrap data must:
 
@@ -236,7 +249,7 @@ type FooConfigInitializationStatus struct {
     // dataSecretCreated is true when the Machine's boostrap secret is created.
     // NOTE: this field is part of the Cluster API contract, and it is used to orchestrate initial Machine provisioning.
     // +optional
-    DataSecretCreated bool `json:"dataSecretCreated,omitempty"`
+    DataSecretCreated *bool `json:"dataSecretCreated,omitempty"`
 }
 ```
 

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

@@ -350,6 +350,9 @@ type FooControlPlaneSpec struct {
     // version defines the desired Kubernetes version for the control plane. 
     // The value must be a valid semantic version; also if the value provided by the user does not start with the v prefix, it
     // must be added.
+    // +required
+    // +kubebuilder:validation:MinLength=1
+    // +kubebuilder:validation:MaxLength=256
     Version string `json:"version"`
 
     // See other rules for more details about mandatory/optional fields in ControlPlane spec.
@@ -364,13 +367,17 @@ type FooControlPlaneStatus struct {
     // version represents the minimum Kubernetes version for the control plane machines
     // in the cluster.
     // +optional
-    Version *string `json:"version,omitempty"`
+    // +kubebuilder:validation:MinLength=1
+    // +kubebuilder:validation:MaxLength=256
+    Version string `json:"version,omitempty"`
 
     // See other rules for more details about mandatory/optional fields in ControlPlane status.
     // Other fields SHOULD be added based on the needs of your provider.
 }
 ```
 
+NOTE: To align with API conventions, we recommend since the v1beta2 contract that the `Version` field should be 
+of type `string` (it was `*string` before). Both are compatible with the v1beta2 contract though.
 NOTE: The minimum Kubernetes version, and more specifically the API server version, will be used to determine 
 when a control plane is fully upgraded (spec.version == status.version) and for enforcing Kubernetes version skew 
 policies when a Cluster derived from a ClusterClass is managed by the Topology controller.
@@ -480,13 +487,16 @@ managed control plane providers for AKS, EKS, GKE etc), you SHOULD also implemen
 type FooControlPlaneStatus struct {
     // externalManagedControlPlane is a bool that should be set to true if the Node objects do not exist in the cluster.
     // +optional
-    ExternalManagedControlPlane bool `json:"externalManagedControlPlane,omitempty"`
+    ExternalManagedControlPlane *bool `json:"externalManagedControlPlane,omitempty"`
 
     // See other rules for more details about mandatory/optional fields in ControlPlane status.
     // Other fields SHOULD be added based on the needs of your provider.
 }
 ```
 
+NOTE: To align with API conventions, we recommend since the v1beta2 contract that the `ExternalManagedControlPlane` field should be
+of type `*bool` (it was `bool` before). Both are compatible with the v1beta2 contract though.
+
 Please note that by representing each control plane instance as Cluster API machine, each control plane instance
 can benefit from several Cluster API behaviours, for example:
 - Machine provisioning workflow (in coordination with an InfraMachine and a BootstrapConfig of your choice)
@@ -521,7 +531,7 @@ type FooControlPlaneInitializationStatus struct {
     // the control plane is fully provisioned or not.
     // NOTE: this field is part of the Cluster API contract, and it is used to orchestrate initial Cluster provisioning.
     // +optional
-    ControlPlaneInitialized bool `json:"controlPlaneInitialized,omitempty"`
+    ControlPlaneInitialized *bool `json:"controlPlaneInitialized,omitempty"`
 }
 ```
 

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

@@ -265,7 +265,7 @@ type FooClusterStatus struct {
 
 `FailureDomain` is defined as:
 - `name string`: the name of the failure domain (must be unique)
-- `controlPlane bool`: indicates if failure domain is appropriate for running control plane instances.
+- `controlPlane *bool`: indicates if failure domain is appropriate for running control plane instances.
 - `attributes map[string]string`: arbitrary attributes for users to apply to a failure domain.
 
 Once `status.failureDomains` is set on the InfraCluster resource and the [InfraCluster initialization completed],
@@ -307,7 +307,7 @@ type FooClusterInitializationStatus struct {
 	// provisioned is true when the infrastructure provider reports that the Cluster's infrastructure is fully provisioned.
 	// NOTE: this field is part of the Cluster API contract, and it is used to orchestrate initial Cluster provisioning.
 	// +optional
-	Provisioned bool `json:"provisioned,omitempty"`
+	Provisioned *bool `json:"provisioned,omitempty"`
 }
 ```
 

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

@@ -210,13 +210,17 @@ type FooMachineSpec struct {
 	// For Kubernetes Nodes running on the Foo provider, this value is set by the corresponding CPI component 
 	// and it has the format docker:////<vm-name>. 
     // +optional
-    ProviderID *string `json:"providerID,omitempty"`
+	// +kubebuilder:validation:MinLength=1
+	// +kubebuilder:validation:MaxLength=512
+	ProviderID string `json:"providerID,omitempty"`
 
     // See other rules for more details about mandatory/optional fields in InfraMachine spec.
     // Other fields SHOULD be added based on the needs of your provider.
 }
 ```
 
+NOTE: To align with API conventions, we recommend since the v1beta2 contract that the `ProviderID` field should be
+of type `string` (it was `*string` before). Both are compatible with the v1beta2 contract though.
 Once `spec.providerID` is set on the InfraMachine resource and the [InfraMachine initialization completed],
 the Cluster controller will surface this info in Machine's `spec.providerID`.
 
@@ -248,7 +252,10 @@ new corresponding field (also in status).
 type FooMachineStatus struct {
     // failureDomain is the unique identifier of the failure domain where this Machine has been placed in.
     // For this Foo infrastructure provider, the name is equivalent to the name of one of the available regions.
-    FailureDomain *string `json:"failureDomain,omitempty"`
+    // +optional
+    // +kubebuilder:validation:MinLength=1
+    // +kubebuilder:validation:MaxLength=256
+    FailureDomain string `json:"failureDomain,omitempty"`
 
     // See other rules for more details about mandatory/optional fields in InfraMachineStatus.
     // Other fields SHOULD be added based on the needs of your provider.
@@ -301,7 +308,7 @@ type FooMachineInitializationStatus struct {
 	// provisioned is true when the infrastructure provider reports that the Machine's infrastructure is fully provisioned.
 	// NOTE: this field is part of the Cluster API contract, and it is used to orchestrate initial Machine provisioning.
 	// +optional
-	Provisioned bool `json:"provisioned,omitempty"`
+	Provisioned *bool `json:"provisioned,omitempty"`
 }
 ```
 

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

@@ -454,6 +454,8 @@ for providers still implementing the v1beta1 contract.
 Following rules have been changed or are not supported anymore; please read corresponding notes about compatibility
 for providers still implementing the v1beta1 contract.
 
+- [InfraMachine: provider ID](../contracts/infra-machine.md#inframachine-provider-id)
+  - Type of the `spec.providerID` field was changed from `*string` to `string`.
 - [InfraMachine: initialization completed](../contracts/infra-machine.md#inframachine-initialization-completed)
 - [InfraMachine: conditions](../contracts/infra-machine.md#inframachine-conditions)
   - The fact that Providers are not required to implement conditions remains valid
@@ -471,6 +473,8 @@ Following rules have been changed or are not supported anymore; please read corr
 for providers still implementing the v1beta1 contract.
 
 - [BootstrapConfig: initialization completed](../contracts/bootstrap-config.md#bootstrapconfig-initialization-completed)
+- [BootstrapConfig: data secret](../contracts/bootstrap-config.md#bootstrapconfig-data-secret)
+  - Type of the `status.dataSecretName` field was changed from `*string` to `string`.
 - [BootstrapConfig: conditions](../contracts/bootstrap-config.md#bootstrapconfig-conditions)
   - The fact that Providers are not required to implement conditions remains valid
   - In case a provider implements conditions, Cluster API doesn't require anymore usage of a specific condition type,
@@ -489,6 +493,10 @@ for providers still implementing the v1beta1 contract.
 - [ControlPlane: machines](../contracts/control-plane.md#controlplane-machines)
 - [ControlPlane: initialization completed](../contracts/control-plane.md#controlplane-initialization-completed)
 - [ControlPlane: replicas](../contracts/control-plane.md#controlplane-replicas)
+- [ControlPlane: version](../contracts/control-plane.md#controlplane-version)
+  - Type of the `status.version` field was changed from `*string` to `string`.
+- [ControlPlane: machines](../contracts/control-plane.md#controlplane-machines)
+  - Type of the `status.externalManagedControlPlane` field was changed from `bool` to `*bool`.
 - [ControlPlane: conditions](../contracts/control-plane.md#controlplane-conditions)
   - The fact that Providers are not required to implement conditions remains valid
   - In case a provider implements conditions, Cluster API doesn't require anymore usage of a specific condition type,