✨ 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.

TBH I don't think it is necessary to automate managing this list, I would prefer to avoid unnecessary complexity

The list should be defined only once, and it should be defined into the library, not at the cmd level

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

fabriziopandini

@ramessesii2 thanks for this PR and sorry for the delay in the review.

Two main comments from my side

The code should be structured to support usage of clusterctl as a library
I would suggest to simplify the code as much as possible, the code target a specific use case and we do not expect to change this code frequently (let's prefer simplicity over extensibility)

See comments for more details; also feel free to pin me in the CAPI channel if you need more clarifications

fabriziopandini · 2025-10-25T11:31:05Z

cmd/clusterctl/cmd/migrate.go

+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.


I'm wondering if we should position this command as "clusterctl config migrate" instead of "clusterctl migrate", for a ca reasons:

as of today the "config" subcommand in clusterctl supervise to repositories, and repositories is where clusterctl expect the yaml templates to be.

it will allow to position this command in a way that makes more sense to users, e.g. description could be "Migrate cluster and cluster class templates between API versions" (which is less opaque than Migrate cluster.x-k8s.io resources")

it will keep the top level list of commands in clusterctl nice and clean (and we will not add an experimental command to it)

it will be nicely consistent with kubeadm config migrate

Wdyt is this enough to make clear that we are just converting YAML files?

I saw so much confusion already about how apiVersions work that I wonder if that command will make some folks think they have to run the migration when bumping to v1beta2.

Especially as we have components like CRD migrator in CAPI

Should we rather use conversion instead of migration? (It's using our conversion and not our migration code, also apiserver calls this conversion)

clusterctl convert yaml also works for me (e.g we already have clusterctl generate yaml)

Not sure if true, but according to Gemini convert would probably be a good fit

fabriziopandini · 2025-10-25T11:33:49Z

cmd/clusterctl/cmd/migrate.go

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


The list should be defined only once, and it should be defined into the library, not at the cmd level

fabriziopandini · 2025-10-25T11:37:25Z

cmd/clusterctl/cmd/migrate.go

+	"k8s.io/apimachinery/pkg/runtime/schema"
+
+	clusterv1 "sigs.k8s.io/cluster-api/api/core/v1beta2"
+	"sigs.k8s.io/cluster-api/cmd/clusterctl/internal/migrate"


The migrate command should not be implemented in an internal packages.

All clusterctl commands should be implemented as a single method in the clusterctl Client interface so they can be used both from the cmd as well as from users leveraging to clusterctl as a library

This also implies that most of the content of runMigrate must be moved into the method above.

The single method in the clustectl library can then use subcomponents from client subpacages.
For this command I will be ok to have the content of internal/migrate moved to client/migrate

fabriziopandini · 2025-10-25T11:58:22Z

cmd/clusterctl/cmd/migrate.go

+	return false
+}
+
+func runMigrate(args []string) error {


Most of the code in this func must be moved to the client interface method, all except:

flag validation

input handling (reading from a file or stdin)

output handling (writing to file, stdout, stderr)

fabriziopandini · 2025-10-25T12:08:53Z

cmd/clusterctl/internal/migrate/parser.go

+}
+
+func (p *YAMLParser) classifyResource(gvk schema.GroupVersionKind) ResourceType {
+	if p.isCoreCAPIGroup(gvk.Group) {


Let's simplify this, there is only one CAPI group

Suggested change

if p.isCoreCAPIGroup(gvk.Group) {

if gvk.Group == clusterv1.GroupVersion.Group {

fabriziopandini · 2025-10-25T13:27:57Z