Skip to content

📖 Align v1beta2 contract to API conventions around optional fields #12418

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 1, 2025
+48 −10
Merged

📖 Align v1beta2 contract to API conventions around optional fields #12418

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 15 additions & 2 deletions docs/book/src/developer/providers/contracts/bootstrap-config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand Up @@ -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"`
}
```

Expand Down
16 changes: 13 additions & 3 deletions docs/book/src/developer/providers/contracts/control-plane.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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"`
}
```

Expand Down
4 changes: 2 additions & 2 deletions docs/book/src/developer/providers/contracts/infra-cluster.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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],
Expand Down Expand Up @@ -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"`
}
```

Expand Down
13 changes: 10 additions & 3 deletions docs/book/src/developer/providers/contracts/infra-machine.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`.

Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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"`
}
```

Expand Down
8 changes: 8 additions & 0 deletions docs/book/src/developer/providers/migrations/v1.10-to-v1.11.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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,
Expand All @@ -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,
Expand Down