More feedback

fabriziopandini · fabriziopandini · commit 6e825532f7a0 · 2025-03-26T10:58:04.000+01:00
diff --git a/cmd/clusterctl/client/cluster/client.go b/cmd/clusterctl/client/cluster/client.go
@@ -38,10 +38,11 @@ var (
 )
 
 // GetCompatibleContractVersions return the list of contract version compatible with a given contract version.
-// NOTE: A contract version might be compatible with older contract versions e.g. to allow users time to transition to the new API.
+// NOTE: A contract version might be temporarily compatible with older contract versions e.g. to allow users time to transition to the new API.
 // NOTE: The return value must include also the contract version received in input.
 func GetCompatibleContractVersions(contract string) sets.Set[string] {
 	compatibleContracts := sets.New(contract)
+	// v1beta2 contract is temporarily be compatible with v1beta1 (until v1beta1 is EOL).
 	if contract == "v1beta2" {
 		compatibleContracts.Insert("v1beta1")
 	}
diff --git a/cmd/clusterctl/client/cluster/installer.go b/cmd/clusterctl/client/cluster/installer.go
@@ -56,7 +56,7 @@ type ProviderInstaller interface {
 	// Validate performs steps to validate a management cluster by looking at the current state and the providers in the queue.
 	// The following checks are performed in order to ensure a fully operational cluster:
 	// - There must be only one instance of the same provider
-	// - All the providers in must support contract version or compatible version
+	// - All providers must support the contract version or one of its compatible versions
 	// - All provider CRDs that are referenced in core Cluster API CRDs must comply with the CRD naming scheme,
 	//   otherwise a warning is logged.
 	Validate(context.Context) error
@@ -200,10 +200,10 @@ func (i *providerInstaller) Validate(ctx context.Context) error {
 	coreProvider := coreProviders[0]
 
 	managementClusterContract, err := i.getProviderContract(ctx, providerInstanceContracts, coreProvider)
-	compatibleContracts := i.getCompatibleContractVersions(managementClusterContract)
 	if err != nil {
 		return err
 	}
+	compatibleContracts := i.getCompatibleContractVersions(managementClusterContract)
 
 	// Checks if all the providers supports the same Cluster API contract or compatible contracts.
 	for _, components := range i.installQueue {
@@ -325,7 +325,7 @@ func (i *providerInstaller) getProviderContract(ctx context.Context, providerIns
 
 	compatibleContracts := i.getCompatibleContractVersions(i.currentContractVersion)
 	if !compatibleContracts.Has(releaseSeries.Contract) {
-		return "", errors.Errorf("current version of clusterctl is only compatible with providers implementing the %s contract version, detected contract version %s for provider %s", strings.Join(compatibleContracts.UnsortedList(), ", "), releaseSeries.Contract, provider.ManifestLabel())
+		return "", errors.Errorf("current version of clusterctl is only compatible with providers implementing the %s contract versions, detected contract version %s for provider %s", strings.Join(compatibleContracts.UnsortedList(), ", "), releaseSeries.Contract, provider.ManifestLabel())
 	}
 
 	providerInstanceContracts[provider.InstanceName()] = releaseSeries.Contract
diff --git a/cmd/clusterctl/client/cluster/installer_test.go b/cmd/clusterctl/client/cluster/installer_test.go
@@ -167,7 +167,7 @@ func Test_providerInstaller_Validate(t *testing.T) {
 				proxy: test.NewFakeProxy(), // empty cluster
 				installQueue: []repository.Components{
 					newFakeComponents("cluster-api", clusterctlv1.CoreProviderType, "v1.0.0", "cluster-api-system"),
-					newFakeComponents("infra3", clusterctlv1.InfrastructureProviderType, "v1.0.0", "infra1-system"),
+					newFakeComponents("infra3", clusterctlv1.InfrastructureProviderType, "v1.0.0", "infra3-system"),
 				},
 			},
 			wantErr: false,
@@ -191,7 +191,7 @@ func Test_providerInstaller_Validate(t *testing.T) {
 					WithProviderInventory("cluster-api", clusterctlv1.CoreProviderType, "v1.0.0", "cluster-api-system").
 					WithProviderInventory("infra1", clusterctlv1.InfrastructureProviderType, "v1.0.0", "infra1-system"),
 				installQueue: []repository.Components{
-					newFakeComponents("infra3", clusterctlv1.InfrastructureProviderType, "v1.0.0", "infra2-system"),
+					newFakeComponents("infra3", clusterctlv1.InfrastructureProviderType, "v1.0.0", "infra3-system"),
 				},
 			},
 			wantErr: false,
diff --git a/cmd/clusterctl/client/cluster/upgrader.go b/cmd/clusterctl/client/cluster/upgrader.go
@@ -290,7 +290,7 @@ func (u *providerUpgrader) createCustomPlan(ctx context.Context, upgradeItems []
 		}
 
 		if !compatibleContracts.Has(contract) {
-			return nil, errors.Errorf("unable to perform upgrade: the target version for the provider %s implements the %s contract version, while the core provider supports %s contract version", upgradeItem.InstanceName(), contract, strings.Join(compatibleContracts.UnsortedList(), ", "))
+			return nil, errors.Errorf("unable to perform upgrade: the target version for the provider %s implements the %s contract version, while the core provider supports %s contract versions", upgradeItem.InstanceName(), contract, strings.Join(compatibleContracts.UnsortedList(), ", "))
 		}
 
 		upgradePlan.Providers = append(upgradePlan.Providers, upgradeItem)
@@ -311,7 +311,7 @@ func (u *providerUpgrader) createCustomPlan(ctx context.Context, upgradeItems []
 		}
 
 		if !compatibleContracts.Has(contract) {
-			return nil, errors.Errorf("unable to perform upgrade: the provider %s implements the %s contract version, while the core provider to a version that supports %s contract version. Please include the %[1]s provider in the upgrade", provider.InstanceName(), contract, strings.Join(compatibleContracts.UnsortedList(), ", "))
+			return nil, errors.Errorf("unable to perform upgrade: the provider %s implements the %s contract version, while the core provider is getting updated to a version that supports %s contract versions. Please include the %[1]s provider in the upgrade", provider.InstanceName(), contract, strings.Join(compatibleContracts.UnsortedList(), ", "))
 		}
 	}
 	return upgradePlan, nil
diff --git a/cmd/clusterctl/client/generate_provider.go b/cmd/clusterctl/client/generate_provider.go
@@ -63,7 +63,7 @@ func (c *clusterctlClient) GenerateProvider(ctx context.Context, provider string
 
 	compatibleContracts := c.getCompatibleContractVersions(c.currentContractVersion)
 	if !compatibleContracts.Has(releaseSeries.Contract) {
-		return nil, errors.Errorf("current version of clusterctl is only compatible with provider implementing %s conctract version, detected %s for provider %s", strings.Join(compatibleContracts.UnsortedList(), ", "), releaseSeries.Contract, providerName)
+		return nil, errors.Errorf("current version of clusterctl is only compatible with provider implementing %s conctract versions, detected %s for provider %s", strings.Join(compatibleContracts.UnsortedList(), ", "), releaseSeries.Contract, providerName)
 	}
 
 	return c.GetProviderComponents(ctx, provider, providerType, options)
diff --git a/cmd/clusterctl/cmd/upgrade_apply.go b/cmd/clusterctl/cmd/upgrade_apply.go
@@ -57,8 +57,8 @@ var upgradeApplyCmd = &cobra.Command{
  		Specifying the provider using namespace/name:version is deprecated and will be dropped in a future release.`),
 	Example: templates.Examples(`
 		# Upgrades all the providers in the management cluster to the latest version available which is compliant
-		# to the v1alpha4 Cluster API contract version.
-		clusterctl upgrade apply --contract v1alpha4
+		# to the v1beta2 Cluster API contract version.
+		clusterctl upgrade apply --contract v1beta2
 
 		# Upgrades only the aws provider to the v2.0.1 version.
 		clusterctl upgrade apply --infrastructure aws:v2.0.1`),
@@ -74,7 +74,7 @@ func init() {
 	upgradeApplyCmd.Flags().StringVar(&ua.kubeconfigContext, "kubeconfig-context", "",
 		"Context to be used within the kubeconfig file. If empty, current context will be used.")
 	upgradeApplyCmd.Flags().StringVar(&ua.contract, "contract", "",
-		"The Cluster API contract version (e.g. v1alpha4) the management cluster should upgrade to")
+		"The Cluster API contract version (e.g. v1beta2) the management cluster should upgrade to")
 
 	upgradeApplyCmd.Flags().StringVar(&ua.coreProvider, "core", "",
 		"Core provider instance version (e.g. cluster-api:v1.1.5) to upgrade to. This flag can be used as alternative to --contract.")
diff --git a/docs/book/src/clusterctl/commands/upgrade.md b/docs/book/src/clusterctl/commands/upgrade.md
@@ -34,7 +34,7 @@ You can now apply the upgrade by executing the following command:
    clusterctl upgrade apply --contract v1beta1
 ```
 
-The output contains the latest release available for each cluster API contract version.
+The output contains the latest release available for each Cluster API contract version.
 available at the moment.
 
 <aside class="note">
diff --git a/docs/book/src/reference/versions.md b/docs/book/src/reference/versions.md
@@ -118,17 +118,17 @@ An API version is considered deprecated when a new API version is published.
 API deprecation and removal follow the [Kubernetes Deprecation Policy](https://kubernetes.io/docs/reference/using-api/deprecation-policy/);
 Cluster API maintainers might decide to support API versions longer than what is defined in the Kubernetes policy.
 
-| API Version | Status         | Supported Until                                                                  |
-|-------------|----------------|----------------------------------------------------------------------------------|
-| v1beta2     | Supported      | at least 9 months or 3 minor releases after a newer API version will be released |
-| v1beta1     | Deprecated     | Deprecated since CAPI v1.11, EOL planned for v1.14, Aug 26                       |
-| v1alpha4    | Not served (*) | EOL since 2023-12-05 - v1.6.0 release date; removal planned for v1.13, Apr 26    |
-| v1alpha3    | Not served (*) | EOL since 2023-07-25 - v1.5.0 release date; removal planned for v1.13, Apr 26    |
-
-See [11920](https://github.com/kubernetes-sigs/cluster-api/issues/11920) for details about the v1beta14 removal plan.
+| API Version | Status      | Supported Until                                                                  |
+|-------------|-------------|----------------------------------------------------------------------------------|
+| v1beta2     | Supported   | at least 9 months or 3 minor releases after a newer API version will be released |
+| v1beta1     | Deprecated  | Deprecated since CAPI v1.11; in v1.14, Aug 26 v1beta1 will stop to be served     |
+| v1alpha4    | Not served  | EOL since 2023-12-05 - v1.6.0 release date; removal planned for v1.13, Apr 26    |
+| v1alpha3    | Not served  | EOL since 2023-07-25 - v1.5.0 release date; removal planned for v1.13, Apr 26    |
+
+See [11920](https://github.com/kubernetes-sigs/cluster-api/issues/11920) for details about the v1beta1 removal plan.
 See [11919](https://github.com/kubernetes-sigs/cluster-api/issues/11919) for details about the v1alpha3/v1alpha4 removal plan.
-- (*) Cluster API stopped to serve v1alpha3 API types from the v1.5 release and v1alpha4 types starting from the v1.6 release.
-  Those types still exist in Cluster API while we work to a fix (or a workaround) for [10051](https://github.com/kubernetes-sigs/cluster-api/issues/10051).
+Note: Cluster API stopped to serve v1alpha3 API types from the v1.5 release and v1alpha4 types starting from the v1.6 release.
+Those types still exist in Cluster API while we work to a fix (or a workaround) for [10051](https://github.com/kubernetes-sigs/cluster-api/issues/10051).
 
 <aside class="note warning">
 
@@ -156,17 +156,17 @@ See [provider contracts](../developer/providers/contracts/overview.md)
 Each Cluster API release supports one contract version, and by convention the supported contract version matches
 the newest API version in the same Cluster API release.
 
-A contract version might be compatible with older contract versions; compatibility for older contract versions will 
-be dropped when the older contract version will be considered EOL.
+A contract version might be temporarily compatible with older contract versions to ease transition of providers to
+a new supported version; compatibility for older contract versions will be dropped when the older contract version is EOL.
 
-| Contract Version | Compatible with contract versions | Status      | Supported Until                                            |
-|------------------|-----------------------------------|-------------|------------------------------------------------------------|
-| v1beta2          | v1beta1                           | Supported   | After a newer API contract will be released                |
-| v1beta1          |                                   | Deprecated  | Deprecated since CAPI v1.11, EOL planned for v1.14, Aug 26 |
-| v1alpha4         |                                   | EOL         | EOL since 2023-12-05 - v1.6.0 release date                 |
-| v1alpha3         |                                   | EOL         | EOL since 2023-07-25 - v1.5.0 release date                 |
+| Contract Version | Compatible with contract versions | Status      | Supported Until                                                                             |
+|------------------|-----------------------------------|-------------|---------------------------------------------------------------------------------------------|
+| v1beta2          | v1beta1 (temporarily)             | Supported   | After a newer API contract will be released                                                 |
+| v1beta1          |                                   | Deprecated  | Deprecated since CAPI v1.11; in v1.14, Aug 26 v1beta1 will no more be considered compatible |
+| v1alpha4         |                                   | EOL         | EOL since 2023-12-05 - v1.6.0 release date                                                  |
+| v1alpha3         |                                   | EOL         | EOL since 2023-07-25 - v1.5.0 release date                                                  |
 
-See [11920](https://github.com/kubernetes-sigs/cluster-api/issues/11920) for details about the v1beta14 removal plan.
+See [11920](https://github.com/kubernetes-sigs/cluster-api/issues/11920) for details about the v1beta1 removal plan.
 
 #### Supported Cluster API - Cluster API provider version Skew
 

Original file line number	Diff line number	Diff line change
`@@ -38,10 +38,11 @@ var (`
`38`	`38`	`)`
`39`	`39`
`40`	`40`	`// GetCompatibleContractVersions return the list of contract version compatible with a given contract version.`
`41`		`-// NOTE: A contract version might be compatible with older contract versions e.g. to allow users time to transition to the new API.`
	`41`	`+// NOTE: A contract version might be temporarily compatible with older contract versions e.g. to allow users time to transition to the new API.`
`42`	`42`	`// NOTE: The return value must include also the contract version received in input.`
`43`	`43`	`func GetCompatibleContractVersions(contract string) sets.Set[string] {`
`44`	`44`	`compatibleContracts := sets.New(contract)`
	`45`	`+ // v1beta2 contract is temporarily be compatible with v1beta1 (until v1beta1 is EOL).`
`45`	`46`	`if contract == "v1beta2" {`
`46`	`47`	`compatibleContracts.Insert("v1beta1")`
`47`	`48`	`}`
Original file line number	Diff line number	Diff line change
`@@ -290,7 +290,7 @@ func (u *providerUpgrader) createCustomPlan(ctx context.Context, upgradeItems []`
`290`	`290`	`}`
`291`	`291`
`292`	`292`	`if !compatibleContracts.Has(contract) {`
`293`		`- return nil, errors.Errorf("unable to perform upgrade: the target version for the provider %s implements the %s contract version, while the core provider supports %s contract version", upgradeItem.InstanceName(), contract, strings.Join(compatibleContracts.UnsortedList(), ", "))`
	`293`	`+ return nil, errors.Errorf("unable to perform upgrade: the target version for the provider %s implements the %s contract version, while the core provider supports %s contract versions", upgradeItem.InstanceName(), contract, strings.Join(compatibleContracts.UnsortedList(), ", "))`
`294`	`294`	`}`
`295`	`295`
`296`	`296`	`upgradePlan.Providers = append(upgradePlan.Providers, upgradeItem)`
`@@ -311,7 +311,7 @@ func (u *providerUpgrader) createCustomPlan(ctx context.Context, upgradeItems []`
`311`	`311`	`}`
`312`	`312`
`313`	`313`	`if !compatibleContracts.Has(contract) {`
`314`		`- return nil, errors.Errorf("unable to perform upgrade: the provider %s implements the %s contract version, while the core provider to a version that supports %s contract version. Please include the %[1]s provider in the upgrade", provider.InstanceName(), contract, strings.Join(compatibleContracts.UnsortedList(), ", "))`
	`314`	`+ return nil, errors.Errorf("unable to perform upgrade: the provider %s implements the %s contract version, while the core provider is getting updated to a version that supports %s contract versions. Please include the %[1]s provider in the upgrade", provider.InstanceName(), contract, strings.Join(compatibleContracts.UnsortedList(), ", "))`
`315`	`315`	`}`
`316`	`316`	`}`
`317`	`317`	`return upgradePlan, nil`
Original file line number	Diff line number	Diff line change
`@@ -63,7 +63,7 @@ func (c *clusterctlClient) GenerateProvider(ctx context.Context, provider string`
`63`	`63`
`64`	`64`	`compatibleContracts := c.getCompatibleContractVersions(c.currentContractVersion)`
`65`	`65`	`if !compatibleContracts.Has(releaseSeries.Contract) {`
`66`		`- return nil, errors.Errorf("current version of clusterctl is only compatible with provider implementing %s conctract version, detected %s for provider %s", strings.Join(compatibleContracts.UnsortedList(), ", "), releaseSeries.Contract, providerName)`
	`66`	`+ return nil, errors.Errorf("current version of clusterctl is only compatible with provider implementing %s conctract versions, detected %s for provider %s", strings.Join(compatibleContracts.UnsortedList(), ", "), releaseSeries.Contract, providerName)`
`67`	`67`	`}`
`68`	`68`
`69`	`69`	`return c.GetProviderComponents(ctx, provider, providerType, options)`