✨ feat: add experimental `clusterctl migrate` command #12843

ramessesii2 · 2025-10-10T06:50:05Z

Implements a new clusterctl migrate command to convert core CAPI resources i.e., cluster.x-k8s.io resources between API versions, currently supporting v1beta1 → v1beta2 migration.

✅ Tests
✅ Docs

Implements #12716

k8s-ci-robot · 2025-10-10T06:50:13Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign justinsb for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

k8s-ci-robot · 2025-10-10T06:50:14Z

Welcome @ramessesii2!

It looks like this is your first PR to kubernetes-sigs/cluster-api 🎉. Please refer to our pull request process documentation to help your PR have a smooth ride to approval.

You will be prompted by a bot to use commands during the review process. Do not be afraid to follow the prompts! It is okay to experiment. Here is the bot commands documentation.

You can also check if kubernetes-sigs/cluster-api has its own contribution guidelines.

You may want to refer to our testing guide if you run into trouble with your tests not passing.

If you are having difficulty getting your pull request seen, please follow the recommended escalation practices. Also, for tips and tricks in the contribution process you may want to read the Kubernetes contributor cheat sheet. We want to make sure your contribution gets all the attention it needs!

Thank you, and welcome to Kubernetes. 😃

k8s-ci-robot · 2025-10-10T06:50:15Z

Hi @ramessesii2. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

neolit123

did a quick first pass on migrate.go

please keep the commits squashed to 1 on amends.

neolit123 · 2025-10-15T12:36:01Z

cmd/clusterctl/cmd/migrate.go

+	"os"
+
+	"github.com/spf13/cobra"
+	"k8s.io/apimachinery/pkg/runtime/schema"


add new line between these two.

k8s vs non-k8s sources.

Apparently, linter is not happy with the suggested change.

Apparently, linter is not happy with the suggested change.

that's odd. linters normally allow you to define as many 'groups' of imports as you like.

cmd/clusterctl/cmd/migrate.go

sbueringer · 2025-10-16T04:54:48Z

/ok-to-test

- Experimental migration support focuses on v1beta1 to v1beta2 conversions for core Cluster API resources Signed-off-by: Satyam Bhardwaj <[email protected]>

fabriziopandini · 2025-10-16T14:58:06Z

/area clusterctl

neolit123

thanks for the updates. i did a bigger pass on the code today.
this is in relatively good shape, but i made some suggestions to re-organize it a bit and make api types opaque to the migrate package.

neolit123 · 2025-10-16T16:07:46Z

cmd/clusterctl/cmd/migrate.go

+var migrateOpts = &migrateOptions{}
+
+var supportedTargetVersions = []string{
+	clusterv1.GroupVersion.Version,


isn't there a programmatic way to enumerate these instead of requiring the OWNERS to manually add a new version here?

e.g. core k8s types manage that in the internal types for a given group, but in CAPI the layout is different.

neolit123 · 2025-10-16T16:08:57Z

cmd/clusterctl/cmd/migrate.go

+
+func runMigrate(args []string) error {
+	if !isSupportedTargetVersion(migrateOpts.toVersion) {
+		return errors.Errorf("invalid --to-version value %q: supported versions are %s", migrateOpts.toVersion, strings.Join(supportedTargetVersions, ", "))


Suggested change

return errors.Errorf("invalid --to-version value %q: supported versions are %s", migrateOpts.toVersion, strings.Join(supportedTargetVersions, ", "))

return errors.Errorf("invalid --to-version value %q. Supported versions are: %s", migrateOpts.toVersion, strings.Join(supportedTargetVersions, ", "))

neolit123 · 2025-10-16T16:10:07Z

cmd/clusterctl/cmd/migrate.go

+
+func init() {
+	migrateCmd.Flags().StringVarP(&migrateOpts.output, "output", "o", "", "Output file path (default: stdout)")
+	migrateCmd.Flags().StringVar(&migrateOpts.toVersion, "to-version", clusterv1.GroupVersion.Version, fmt.Sprintf("Target API version for migration (supported: %s)", strings.Join(supportedTargetVersions, ", ")))


Suggested change

migrateCmd.Flags().StringVar(&migrateOpts.toVersion, "to-version", clusterv1.GroupVersion.Version, fmt.Sprintf("Target API version for migration (supported: %s)", strings.Join(supportedTargetVersions, ", ")))

migrateCmd.Flags().StringVar(&migrateOpts.toVersion, "to-version", clusterv1.GroupVersion.Version, fmt.Sprintf("Target API version for migration. Supported versions are: %s)", strings.Join(supportedTargetVersions, ", ")))

neolit123 · 2025-10-16T16:18:41Z

cmd/clusterctl/cmd/migrate.go

+	parser := migrate.NewYAMLParser(scheme.Scheme)
+
+	targetGV := schema.GroupVersion{
+		Group:   clusterv1.GroupVersion.Group,


this is ok, but it hardcodes the group to the group of an imported version package.
i think a local constant that copies the group string might be better.
...or a proper mapping that takes the user version input and determines the group from it.

neolit123 · 2025-10-16T16:21:05Z

cmd/clusterctl/cmd/migrate.go

+	"os"
+
+	"github.com/spf13/cobra"
+	"k8s.io/apimachinery/pkg/runtime/schema"


Apparently, linter is not happy with the suggested change.

that's odd. linters normally allow you to define as many 'groups' of imports as you like.

neolit123 · 2025-10-16T16:50:35Z

cmd/clusterctl/internal/migrate/parser.go

+	yamlserializer "k8s.io/apimachinery/pkg/runtime/serializer/yaml"
+	yamlutil "k8s.io/apimachinery/pkg/util/yaml"
+
+	clusterv1 "sigs.k8s.io/cluster-api/api/core/v1beta2"


ditto. the GVKs must be opaque to the internal/migrate package i would say. it can accept a list of known source and target GVKs.

neolit123 · 2025-10-16T16:52:25Z

cmd/clusterctl/internal/migrate/parser.go

+
+const (
+	// ResourceTypeCoreV1Beta1 identifies v1beta1 core ClusterAPI resources.
+	ResourceTypeCoreV1Beta1 ResourceType = iota


the classification of input GVKs can be done based on provided GVK inputs as params.
the first const in the enum here could be a generic ResourceTypeSupported (or similar for a type that can be parsed on migrated).

neolit123 · 2025-10-16T16:53:42Z

cmd/clusterctl/internal/migrate/parser.go

+
+func (p *YAMLParser) classifyResource(gvk schema.GroupVersionKind) ResourceType {
+	if p.isCoreCAPIGroup(gvk.Group) {
+		if gvk.Version == "v1beta1" {


best to check from the input GVK i mention above instead of hardcoding known versions in string literals.

neolit123 · 2025-10-16T16:53:58Z

cmd/clusterctl/internal/migrate/parser.go

+	return ok
+}
+
+var coreCapiGroups = map[string]struct{}{


put vars on top of the doc.

neolit123 · 2025-10-16T16:54:40Z

cmd/clusterctl/cmd/migrate.go

+
+Examples:
+  # Migrate from file to stdout
+  clusterctl migrate cluster.yaml


would migrate from new to old be supported?
e.g. v1beta2 -> v1beta1

k8s-ci-robot added do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. labels Oct 10, 2025

k8s-ci-robot added the do-not-merge/needs-area PR is missing an area label label Oct 10, 2025

k8s-ci-robot added size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels Oct 10, 2025

k8s-ci-robot requested review from Jont828 and sivchari October 10, 2025 06:50

ramessesii2 mentioned this pull request Oct 10, 2025

v1beta1 -> v1beta2 migration tool #12716

Open

ramessesii2 force-pushed the RAMESSES/migrate-cmd branch from db40551 to 1bf4039 Compare October 15, 2025 07:53

k8s-ci-robot added size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. and removed size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. labels Oct 15, 2025

ramessesii2 changed the title ~~feat: add clusterctl alpha migrate command~~ feat: add experimental clusterctl migrate command Oct 15, 2025

ramessesii2 force-pushed the RAMESSES/migrate-cmd branch 3 times, most recently from 6f90e35 to c2050f4 Compare October 15, 2025 08:51

ramessesii2 marked this pull request as ready for review October 15, 2025 08:52

k8s-ci-robot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Oct 15, 2025

k8s-ci-robot requested a review from richardcase October 15, 2025 08:52

ramessesii2 changed the title ~~feat: add experimental clusterctl migrate command~~ ✨ feat: add experimental clusterctl migrate command Oct 15, 2025

neolit123 reviewed Oct 15, 2025

View reviewed changes

ramessesii2 force-pushed the RAMESSES/migrate-cmd branch from c2050f4 to f67227b Compare October 16, 2025 01:33

k8s-ci-robot added ok-to-test Indicates a non-member PR verified by an org member that is safe to test. and removed needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels Oct 16, 2025

feat: add experimental clusterctl migrate command

dd58aab

- Experimental migration support focuses on v1beta1 to v1beta2 conversions for core Cluster API resources Signed-off-by: Satyam Bhardwaj <[email protected]>

ramessesii2 force-pushed the RAMESSES/migrate-cmd branch from f67227b to dd58aab Compare October 16, 2025 10:29

k8s-ci-robot added area/clusterctl Issues or PRs related to clusterctl and removed do-not-merge/needs-area PR is missing an area label labels Oct 16, 2025

neolit123 reviewed Oct 16, 2025

View reviewed changes

	return errors.Errorf("invalid --to-version value %q: supported versions are %s", migrateOpts.toVersion, strings.Join(supportedTargetVersions, ", "))
	return errors.Errorf("invalid --to-version value %q. Supported versions are: %s", migrateOpts.toVersion, strings.Join(supportedTargetVersions, ", "))

	migrateCmd.Flags().StringVar(&migrateOpts.toVersion, "to-version", clusterv1.GroupVersion.Version, fmt.Sprintf("Target API version for migration (supported: %s)", strings.Join(supportedTargetVersions, ", ")))
	migrateCmd.Flags().StringVar(&migrateOpts.toVersion, "to-version", clusterv1.GroupVersion.Version, fmt.Sprintf("Target API version for migration. Supported versions are: %s)", strings.Join(supportedTargetVersions, ", ")))

✨ feat: add experimental clusterctl migrate command #12843

Are you sure you want to change the base?

✨ feat: add experimental clusterctl migrate command #12843

Conversation

ramessesii2 commented Oct 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

k8s-ci-robot commented Oct 10, 2025

Uh oh!

k8s-ci-robot commented Oct 10, 2025

Uh oh!

k8s-ci-robot commented Oct 10, 2025

Uh oh!

neolit123 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ramessesii2 Oct 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sbueringer commented Oct 16, 2025

Uh oh!

fabriziopandini commented Oct 16, 2025

Uh oh!

neolit123 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

✨ feat: add experimental `clusterctl migrate` command #12843

✨ feat: add experimental `clusterctl migrate` command #12843

ramessesii2 commented Oct 10, 2025 •

edited

Loading

neolit123 left a comment •

edited

Loading

ramessesii2 Oct 16, 2025 •

edited

Loading

neolit123 left a comment •

edited

Loading