Migrate a manifest to v1beta2

Cluster API (CAPI) introduced the v1beta2 API version for its core resources starting with CAPI version v1.11. Syself Autopilot has been upgraded to use the new Cluster API version with the v1beta2 API types.

However, no immediate action is required, as both v1beta1 and v1beta2 are fully supported and functional on the management cluster. Your existing clusters and their workloads will continue to operate normally regardless of which API version their manifests use.

How API Versions Work#

After the upgrade, the management cluster:

• Stores resources in v1beta2 (storage version)
• Serves both v1beta1 and v1beta2 (for compatibility)

This means:

• Existing objects originally created as v1beta1 are automatically converted to v1beta2 internally.
• When using kubectl, you will typically see resources returned as v1beta2 (the preferred version).
• You can still explicitly request v1beta1 as long as it remains served:

  		$ kubectl get clusters.v1beta1.cluster.x-k8s.io
  	

New Clusters use v1beta2 by default#

We have updated our documentation to use the new API version cluster.x-k8s.io/v1beta2. You should also create new clusters using this API version.

GitOps Compatibility#

GitOps workflows will continue to work with existing v1beta1 manifests without requiring changes to controllers or tooling.

However, you should plan to migrate your manifests to v1beta2 before v1beta1 support is removed (see the migration timeline and migration guide below).

Once v1beta1 is no longer served, GitOps reconciliation using v1beta1 manifests will fail.

Migration Timeline#

Cluster API (CAPI) plans to stop serving v1beta1 starting with CAPI v1.16, scheduled for April 2027.

Syself Autopilot will continue supporting v1beta1 until May 2027 to provide additional migration time.

After this:

• v1beta1 will no longer be served.
• Requests using v1beta1 will fail.
• Existing clusters and workloads will continue to operate normally.

Migration Guide#

If you are using GitOps, you should migrate your Cluster manifests to API version cluster.x-k8s.io/v1beta2. While v1beta1 continues to work for now, keeping it in your repository will eventually lead to failures once support is removed.

1. Update the apiVersion field from cluster.x-k8s.io/v1beta1 to cluster.x-k8s.io/v1beta2.
2. Update spec.topology.class to spec.topology.classRef.name.
3. Remove any empty metadata: {} fields from spec.topology.controlPlane and spec.topology.workers.machineDeployments entries.
4. Commit and push the changes, then let your GitOps controller reconcile.
5. Verify against the live object that the new field applied:

   		$ kubectl get cluster <name> -o jsonpath='{.spec.topology.classRef.name}'
   	

   It should print the class name you set. Keep any templated fleet manifests consistent so every cluster uses the same shape.

Example Changes:

		apiVersion: cluster.x-k8s.io/v1beta1
apiVersion: cluster.x-k8s.io/v1beta2
topology:
  class: <value>
  classRef:
    name: <value>
  controlPlane:
    metadata: {} 
    replicas: 3
  ...
  workers:
    machineDeployments:
    - class: workeramd64hcloud
      failureDomain: nbg1
      metadata: {} 
      name: md-amd64
      replicas: 1
	

Related#

• Upgrade to a new Kubernetes version , where this migration usually comes up
• Self-management pattern , keep templated fleet manifests consistent in Git