Migrate ARM servers to x86 in your cluster

This guide explains how to replace ARM-based (CAX) nodes in your cluster with x86 nodes.

Step 1: Add x86 worker machine deployments and scale down ARM ones#

Do not change the class of an existing machine deployment in-place. Instead, add a new machine deployment with the workeramd64hcloud class and set the replicas of the ARM machine deployment to 0.

workerMachineTypeHcloud can be set at the cluster level under spec.topology.variables as well as inside a machine deployment's variables.overrides. Check both and update them wherever a CAX type appears:

Under spec.topology.variables:

		 
...
variables:
  - name: workerMachineTypeHcloud
    value: cax31
    value: cpx42
	

In the machine deployments — scale down the ARM deployment, add a new x86 one:

		 
...
workers:
  machineDeployments:
    - class: workerarm64hcloud
      name: md-0
      replicas: 3
      replicas: 0
      failureDomain: nbg1
      variables:
        overrides:
          - name: workerMachineTypeHcloud
            value: cax31
    - class: workeramd64hcloud
      name: md-0-x86
      replicas: 3
      failureDomain: nbg1
      variables:
        overrides:
          - name: workerMachineTypeHcloud
            value: cpx42
	

Wait for the new x86 nodes to become ready and for the ARM nodes to be fully removed before continuing.

Step 2: Remove the ARM machine deployment#

Once the ARM machine deployment has no nodes remaining, remove it from your Cluster resource:

		 
...
workers:
  machineDeployments:
    - class: workerarm64hcloud
      name: md-0
      replicas: 0
      failureDomain: nbg1
      variables:
        overrides:
          - name: workerMachineTypeHcloud
            value: cax31
    - class: workeramd64hcloud
      name: md-0-x86
      replicas: 3
      failureDomain: nbg1
      variables:
        overrides:
          - name: workerMachineTypeHcloud
            value: cpx42
	

Step 3: Update control plane nodes (if applicable)#

If your control plane runs on ARM servers, your cluster variables will include controlPlaneMachineArchHcloud: arm64 and a CAX server type for controlPlaneMachineTypeHcloud.

Check your current control plane count#

Before making any changes, verify that the number of control plane nodes currently running matches the number defined in your Cluster resource.

In your workload cluster, count the ready control plane nodes:

		$ kubectl get nodes -l node-role.kubernetes.io/control-plane
NAME                           STATUS   ROLES           AGE   VERSION
mycluster-xb2gr-abc12          Ready    control-plane   2d    v1.33.1
mycluster-xb2gr-def34          Ready    control-plane   2d    v1.33.1
mycluster-xb2gr-ghi56          Ready    control-plane   2d    v1.33.1
	

In the management cluster, check the defined replica count:

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

If the counts match, you can proceed with the change below.

If the counts do not match, it means some ARM control plane nodes were already removed by the health check and could not be replaced due to unavailable ARM servers. Please contact support and still proceed with the change as switching to x86 will allow the missing nodes to be provisioned.

Apply the change#

Change the architecture to amd64 and the server type to an x86 type. Do not change replicas.

These variables can be set in two locations in your Cluster resource. Check both and update them wherever they appear:

Under spec.topology.variables:

		 
...
variables:
  - name: controlPlaneMachineArchHcloud
    value: arm64
    value: amd64
  - name: controlPlaneMachineTypeHcloud
    value: cax31
    value: cpx42
	

Under spec.topology.controlPlane.variables.overrides:

		 
...
controlPlane:
  variables:
    overrides:
      - name: controlPlaneMachineArchHcloud
        value: arm64
        value: amd64
      - name: controlPlaneMachineTypeHcloud
        value: cax31
        value: cpx42
	

Verifying the migration#

After applying all changes, verify that no CAX server types remain by checking the spec.type field of the HCloudMachine objects:

		$ kubectl get hcloudmachines -o custom-columns='NAME:.metadata.name,TYPE:.spec.type'
NAME                           TYPE
mycluster-xb2gr-rcnbs          cpx42
mycluster-md-0-x86-abc12       cpx42
	

Once no CAX server types appear in the output, the migration is complete and you can proceed with your cluster update.