Migration from MKE to k0s

Applies to management clusters only

Since MOSK management 2.32.0, the Kubernetes underlay of new management clusters is k0s. Existing MKE-based management clusters are migrated to k0s automatically, as part of the regular management cluster upgrade. No manual steps are required to start or drive the migration.

MOSK clusters are not affected by this migration and keep running MKE. For details, see Kubernetes distributions.

Important

The migration is a one-way operation. Once it is initiated, a management cluster cannot be rolled back to MKE. Ensure that a fresh backup of the cluster exists before the upgrade starts, as described in Kubernetes underlay backup.

Migration principles

The migration replaces the Kubernetes distribution in place, without re-provisioning the cluster nodes:

The migration follows the regular cluster release upgrade flow and is orchestrated by the LCM Controller through the maintenance API.
The Kubernetes distribution is replaced while the same etcd data is carried over, so the cluster keeps its identity, objects, and workloads.
Control plane nodes are migrated one by one. At least one MKE control plane node stays operational until the majority of the cluster has moved to k0s.
Both distributions are supported by the MOSK lifecycle management engine at the same time, so the management cluster continues managing the MKE-based MOSK clusters throughout and after the migration.

Migration flow

The following table outlines the phases of the management cluster migration.

Stage	Component	Description
1	Calico datastore	Pre-migration. The Calico datastore is switched from etcd to the Kubernetes datastore driver (KDD) through the MKE API.
2	Node preparation	Pre-migration. All nodes enter the `Prepare` phase, during which the following tasks are performed: The Kubernetes component certificates are copied from the MKE Docker volumes to the k0s certificate paths. The audit policy and the etcd encryption configuration are transferred. The kubelet TLS certificates are generated.
3	First control plane node	The node is cordoned and drained. The MKE `ucp-kube-controller-manager` component is stopped on all control plane nodes. The k0s binary is deployed, the etcd data is carried over in place, and the `k0scontroller` systemd service starts. HAProxy is reconfigured to keep the Kubernetes API reachable on both the MKE and k0s ports. Once the node becomes `Ready`, the Kubernetes controller manager is operational again.
4	Second control plane node	The second node joins the k0s cluster and the etcd quorum is restored. The remaining control plane node temporarily stays on MKE.
5	Third control plane node	The remaining node is migrated. No MKE components remain on any node of the cluster.

Migration impact

The migration is designed to be minimally disruptive. However, it includes the following risk windows that you should plan for.

Risk	Severity	Impact and mitigation
Kubernetes controller manager downtime	High	Between the drain of the first control plane node and the start of k0s on that node, the Kubernetes controller manager is not running. The estimated duration of this window is 30-50 minutes. During the window, pods are not rescheduled, deployments do not maintain the replica count or perform rolling updates, new PersistentVolumeClaims do not bind, CronJobs do not trigger, and terminated objects are not garbage collected. Existing workloads keep running and their network connectivity is not affected. Perform the update during a maintenance window with low cluster activity.
No rollback to MKE	High	The migration is irreversible. Once a node is migrated, the MKE containers and the Docker Swarm state are removed from it. Ensure that a fresh cluster backup exists before the upgrade starts and that the backup is stored on remote storage. For details, see Kubernetes underlay backup.
Calico datastore conversion	Medium	The conversion of the Calico datastore from etcd to KDD freezes cluster networking for about 20 seconds per node. During this window, new or replacement pods cannot start, while existing pods retain full network connectivity.
Synchronization gap of the etcd data	Medium	Between stopping the MKE etcd instance on a node and starting k0s with the carried-over etcd data, the data snapshot becomes progressively stale. Excessive cluster activity during this window may prevent the node from rejoining the etcd cluster and require manual intervention by Mirantis support. Therefore, minimize the cluster activity during the migration.
Configuration parameters that are not migrated automatically	Medium	The MKE settings applied directly through the MKE API are not carried over to k0s, and not all of them have a k0s counterpart. Audit the MKE configuration before the upgrade and re-apply the required settings using the `Cluster` object afterwards, as described in Update notes.
Change of the certificate authority for the CSR API	Low to medium	After the migration, the certificates issued through the Kubernetes CSR API are signed by a different certificate authority. Services that validate the issuer explicitly, such as a service mesh or `cert-manager` in the CSR mode, may need their certificates to be re-issued.
Mismatch of the `iptables` versions	Low	k0s uses its own `iptables` binary. If its version diverges from the host operating system version, the networking rules may conflict and cause intermittent packet drops.