diff --git a/docs/book/src/developer/providers/contracts/bootstrap-config.md b/docs/book/src/developer/providers/contracts/bootstrap-config.md index e0011d273b0e..268ec253da60 100644 --- a/docs/book/src/developer/providers/contracts/bootstrap-config.md +++ b/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"` } ``` diff --git a/docs/book/src/developer/providers/contracts/control-plane.md b/docs/book/src/developer/providers/contracts/control-plane.md index f17e51c5887d..1f80894053ba 100644 --- a/docs/book/src/developer/providers/contracts/control-plane.md +++ b/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"` } ``` diff --git a/docs/book/src/developer/providers/contracts/infra-cluster.md b/docs/book/src/developer/providers/contracts/infra-cluster.md index d1e23d4f5893..c16eee228a32 100644 --- a/docs/book/src/developer/providers/contracts/infra-cluster.md +++ b/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"` } ``` diff --git a/docs/book/src/developer/providers/contracts/infra-machine.md b/docs/book/src/developer/providers/contracts/infra-machine.md index 77876152e2de..10fe71a6e6e0 100644 --- a/docs/book/src/developer/providers/contracts/infra-machine.md +++ b/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:////. // +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"` } ``` diff --git a/docs/book/src/developer/providers/migrations/v1.10-to-v1.11.md b/docs/book/src/developer/providers/migrations/v1.10-to-v1.11.md index fdc2289ff8f8..27ee6b32b371 100644 --- a/docs/book/src/developer/providers/migrations/v1.10-to-v1.11.md +++ b/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,