## Overview

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:
  ```console
  $ 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](#migration-timeline) and [migration guide](#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.

<Steps>
<Step>Bump the <code>apiVersion</code></Step>

Change `apiVersion` from `cluster.x-k8s.io/v1beta1` to `cluster.x-k8s.io/v1beta2`.

<Step>Rename <code>class</code> to <code>classRef.name</code></Step>

Change `spec.topology.class` to `spec.topology.classRef.name`.

<Step>Drop empty <code>metadata</code> objects</Step>

Remove `metadata` fields that are empty objects from `spec.topology.controlPlane` and `spec.topology.workers.machineDeployments` entries.

<Step>Commit and let GitOps reconcile</Step>

Commit and push the changes, then let your GitOps controller reconcile.

</Steps>

**Example Changes:**

```yaml
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
```