feat: add experimental clusterctl migrate command

    - Experimental migration support focuses on v1beta1 to v1beta2
    conversions for core Cluster API resources

Signed-off-by: Satyam Bhardwaj <sbhardwaj@mirantis.com>

Author: ramessesii2

cmd/clusterctl/cmd/migrate.go

@@ -0,0 +1,176 @@
+/*
+Copyright 2025 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package cmd
+
+import (
+	"fmt"
+	"io"
+	"os"
+
+	"github.com/spf13/cobra"
+	"k8s.io/apimachinery/pkg/runtime/schema"
+
+	clusterv1 "sigs.k8s.io/cluster-api/api/core/v1beta2"
+	"sigs.k8s.io/cluster-api/cmd/clusterctl/internal/migrate"
+	"sigs.k8s.io/cluster-api/cmd/clusterctl/internal/scheme"
+)
+
+type migrateOptions struct {
+	output    string
+	toVersion string
+}
+
+var migrateOpts = &migrateOptions{}
+
+var migrateCmd = &cobra.Command{
+	Use:   "migrate [SOURCE]",
+	Short: "EXPERIMENTAL: Migrate cluster.x-k8s.io resources between API versions",
+	Long: `EXPERIMENTAL: Migrate cluster.x-k8s.io resources between API versions.
+
+This command is EXPERIMENTAL and currently supports only cluster.x-k8s.io core resources
+(Cluster, MachineDeployment, etc.) with v1beta2 as the only supported target version.
+
+SCOPE AND LIMITATIONS (Experimental Status):
+- Only cluster.x-k8s.io resources are converted
+- Other CAPI API groups are passed through unchanged
+- Currently only supports v1beta2 as target version (--to-version flag must be "v1beta2")
+- ClusterClass patches are not migrated
+- Field order may change and comments will be removed in output
+- API version references are dropped during conversion (except cluster class and external
+  remediation references)
+
+Examples:
+  # Migrate from file to stdout
+  clusterctl migrate cluster.yaml
+
+  # Migrate from stdin to stdout
+  cat cluster.yaml | clusterctl migrate
+
+  # Explicitly specify target version (currently only v1beta2 is supported)
+  clusterctl migrate cluster.yaml --to-version v1beta2 --output migrated-cluster.yaml`,
+
+	Args: cobra.MaximumNArgs(1),
+	RunE: func(cmd *cobra.Command, args []string) error {
+		return runMigrate(args)
+	},
+}
+
+func init() {
+	migrateCmd.Flags().StringVarP(&migrateOpts.output, "output", "o", "", "Output file path (default: stdout)")
+	migrateCmd.Flags().StringVar(&migrateOpts.toVersion, "to-version", "v1beta2", "Target API version for migration (currently only v1beta2 is supported)")
+
+	RootCmd.AddCommand(migrateCmd)
+}
+
+func runMigrate(args []string) error {
+	if migrateOpts.toVersion != clusterv1.GroupVersion.Version {
+		return fmt.Errorf("invalid --to-version value %q: currently only %s is supported", migrateOpts.toVersion, clusterv1.GroupVersion.Version)
+	}
+
+	fmt.Fprintf(os.Stderr, "WARNING: This command is EXPERIMENTAL and currently supports only cluster.x-k8s.io resources.\n")
+	fmt.Fprintf(os.Stderr, "Only v1beta2 is supported as target version. Other CAPI API groups are passed through unchanged.\n")
+	fmt.Fprintf(os.Stderr, "See 'clusterctl migrate --help' for scope, limitations, and usage details.\n\n")
+
+	var input io.Reader
+	var inputName string
+
+	if len(args) == 0 {
+		input = os.Stdin
+		inputName = "stdin"
+	} else {
+		sourceFile := args[0]
+		file, err := os.Open(sourceFile)
+		if err != nil {
+			return fmt.Errorf("failed to open input file %q: %w", sourceFile, err)
+		}
+		defer file.Close()
+		input = file
+		inputName = sourceFile
+	}
+
+	// Determine output destination
+	var output io.Writer
+	var outputFile *os.File
+	var err error
+
+	if migrateOpts.output == "" {
+		output = os.Stdout
+	} else {
+		outputFile, err = os.Create(migrateOpts.output)
+		if err != nil {
+			return fmt.Errorf("failed to create output file %q: %w", migrateOpts.output, err)
+		}
+		defer outputFile.Close()
+		output = outputFile
+	}
+
+	// Create migration engine components
+	parser := migrate.NewYAMLParser(scheme.Scheme)
+	
+	targetGV := schema.GroupVersion{
+		Group:   clusterv1.GroupVersion.Group,
+		Version: migrateOpts.toVersion,
+	}
+	
+	converter, err := migrate.NewConverter(targetGV)
+	if err != nil {
+		return fmt.Errorf("failed to create converter: %w", err)
+	}
+
+	engine, err := migrate.NewEngine(parser, converter)
+	if err != nil {
+		return fmt.Errorf("failed to create migration engine: %w", err)
+	}
+
+	opts := migrate.MigrationOptions{
+		Input:     input,
+		Output:    output,
+		Errors:    os.Stderr,
+		ToVersion: migrateOpts.toVersion,
+	}
+
+	result, err := engine.Migrate(opts)
+	if err != nil {
+		return fmt.Errorf("migration failed: %w", err)
+	}
+
+	if result.TotalResources > 0 {
+		fmt.Fprintf(os.Stderr, "\nMigration completed:\n")
+		fmt.Fprintf(os.Stderr, "  Total resources processed: %d\n", result.TotalResources)
+		fmt.Fprintf(os.Stderr, "  Resources converted: %d\n", result.ConvertedCount)
+		fmt.Fprintf(os.Stderr, "  Resources skipped: %d\n", result.SkippedCount)
+
+		if result.ErrorCount > 0 {
+			fmt.Fprintf(os.Stderr, "  Resources with errors: %d\n", result.ErrorCount)
+		}
+
+		if len(result.Warnings) > 0 {
+			fmt.Fprintf(os.Stderr, "  Warnings: %d\n", len(result.Warnings))
+		}
+
+		fmt.Fprintf(os.Stderr, "\nSource: %s\n", inputName)
+		if migrateOpts.output != "" {
+			fmt.Fprintf(os.Stderr, "Output: %s\n", migrateOpts.output)
+		}
+	}
+
+	if result.ErrorCount > 0 {
+		return fmt.Errorf("migration completed with %d errors", result.ErrorCount)
+	}
+
+	return nil
+}

cmd/clusterctl/internal/migrate/converter.go

@@ -0,0 +1,180 @@
+/*
+Copyright 2025 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package migrate
+
+import (
+	"fmt"
+
+	"k8s.io/apimachinery/pkg/runtime"
+	"k8s.io/apimachinery/pkg/runtime/schema"
+	"sigs.k8s.io/controller-runtime/pkg/conversion"
+
+	clusterv1 "sigs.k8s.io/cluster-api/api/core/v1beta2"
+	"sigs.k8s.io/cluster-api/cmd/clusterctl/internal/scheme"
+)
+
+// Converter handles conversion of individual CAPI resources between API versions.
+type Converter struct {
+	scheme       *runtime.Scheme
+	targetGV     schema.GroupVersion
+	targetGVKMap gvkConversionMap
+}
+
+// gvkConversionMap caches conversions from a source GroupVersionKind to its target GroupVersionKind.
+type gvkConversionMap map[schema.GroupVersionKind]schema.GroupVersionKind
+
+// ConversionResult represents the outcome of converting a single resource.
+type ConversionResult struct {
+	Object runtime.Object
+	// Converted indicates whether the object was actually converted
+	Converted bool
+	Error     error
+	Warnings  []string
+}
+
+// NewConverter creates a new resource converter using the clusterctl scheme.
+func NewConverter(targetGV schema.GroupVersion) (*Converter, error) {
+	return &Converter{
+		scheme:       scheme.Scheme,
+		targetGV:     targetGV,
+		targetGVKMap: make(gvkConversionMap),
+	}, nil
+}
+
+// CanConvert determines if a resource can be converted.
+func (c *Converter) CanConvert(info ResourceInfo, obj runtime.Object) bool {
+	gvk := info.GroupVersionKind
+
+	if gvk.Group != clusterv1.GroupVersion.Group {
+		return false
+	}
+
+	if gvk.Version == c.targetGV.Version {
+		return false
+	}
+
+	return true
+}
+
+// ConvertResource converts a single resource to the target version.
+// Returns the converted object, or the original if no conversion is needed.
+func (c *Converter) ConvertResource(info ResourceInfo, obj runtime.Object) ConversionResult {
+	gvk := info.GroupVersionKind
+
+	if gvk.Group == clusterv1.GroupVersion.Group && gvk.Version == c.targetGV.Version {
+		return ConversionResult{
+			Object:    obj,
+			Converted: false,
+			Warnings:  []string{fmt.Sprintf("Resource %s/%s is already at version %s", gvk.Kind, info.Name, c.targetGV.Version)},
+		}
+	}
+
+	if gvk.Group != clusterv1.GroupVersion.Group {
+		return ConversionResult{
+			Object:    obj,
+			Converted: false,
+			Warnings:  []string{fmt.Sprintf("Skipping non-%s resource: %s", clusterv1.GroupVersion.Group, gvk.String())},
+		}
+	}
+
+	targetGVK, err := c.getTargetGVK(gvk)
+	if err != nil {
+		return ConversionResult{
+			Object:    obj,
+			Converted: false,
+			Error:     fmt.Errorf("failed to determine target GVK for %s: %w", gvk.String(), err),
+		}
+	}
+
+	// Check if the object is already typed
+	// If it's typed and implements conversion.Convertible, use the custom ConvertTo method
+	if convertible, ok := obj.(conversion.Convertible); ok {
+		// Create a new instance of the target type
+		targetObj, err := c.scheme.New(targetGVK)
+		if err != nil {
+			return ConversionResult{
+				Object:    obj,
+				Converted: false,
+				Error:     fmt.Errorf("failed to create target object for %s: %w", targetGVK.String(), err),
+			}
+		}
+
+		// Check if the target object is a Hub
+		if hub, ok := targetObj.(conversion.Hub); ok {
+			if err := convertible.ConvertTo(hub); err != nil {
+				return ConversionResult{
+					Object:    obj,
+					Converted: false,
+					Error:     fmt.Errorf("failed to convert %s from %s to %s: %w", gvk.Kind, gvk.Version, c.targetGV.Version, err),
+				}
+			}
+
+			// Ensure the GVK is set on the converted object
+			hubObj := hub.(runtime.Object)
+			hubObj.GetObjectKind().SetGroupVersionKind(targetGVK)
+
+			return ConversionResult{
+				Object:    hubObj,
+				Converted: true,
+				Error:     nil,
+				Warnings:  nil,
+			}
+		}
+	}
+
+	// Use scheme-based conversion for all remaining cases
+	convertedObj, err := c.scheme.ConvertToVersion(obj, targetGVK.GroupVersion())
+	if err != nil {
+		return ConversionResult{
+			Object:    obj,
+			Converted: false,
+			Error:     fmt.Errorf("failed to convert %s from %s to %s: %w", gvk.Kind, gvk.Version, c.targetGV.Version, err),
+		}
+	}
+
+	return ConversionResult{
+		Object:    convertedObj,
+		Converted: true,
+		Error:     nil,
+		Warnings:  nil,
+	}
+}
+
+// getTargetGVK returns the target GroupVersionKind for a given source GVK.
+func (c *Converter) getTargetGVK(sourceGVK schema.GroupVersionKind) (schema.GroupVersionKind, error) {
+	// Check cache first
+	if targetGVK, ok := c.targetGVKMap[sourceGVK]; ok {
+		return targetGVK, nil
+	}
+
+	// Create target GVK with same kind but target version
+	targetGVK := schema.GroupVersionKind{
+		Group:   c.targetGV.Group,
+		Version: c.targetGV.Version,
+		Kind:    sourceGVK.Kind,
+	}
+
+	// Verify the target type exists in the scheme
+	if !c.scheme.Recognizes(targetGVK) {
+		return schema.GroupVersionKind{}, fmt.Errorf("target GVK %s not recognized by scheme", targetGVK.String())
+	}
+
+	// Cache for future use
+	c.targetGVKMap[sourceGVK] = targetGVK
+
+	return targetGVK, nil
+}