Skip to main content
Version: v0.33 Stable

Migrate from K3s to Kubernetes

Supported Configurations
Running the control plane as a container with:

Starting in vCluster 0.25.0, you can migrate virtual clusters from the K3s distribution to the standard Kubernetes (K8s) distribution. This migration gives you access to the full Kubernetes feature set while preserving your existing workloads and configuration.

K3s removal in v0.33

vCluster v0.33 removes support for the K3s distribution entirely. If your virtual clusters currently use K3s, migrate them to K8s on your current vCluster version before upgrading to v0.33.

Prerequisites​

  • Administrator access to a Kubernetes cluster: See Accessing Clusters with kubectl for more information. Run the command kubectl auth can-i create clusterrole -A to verify that your current kube-context has administrative privileges.

    info

    To obtain a kube-context with admin access, ensure you have the necessary credentials and permissions for your Kubernetes cluster. This typically involves using kubectl config commands or authenticating through your cloud provider's CLI tools.

  • helm: Helm v3.10 is required for deploying the platform. Refer to the Helm Installation Guide if you need to install it.

  • kubectl: Kubernetes command-line tool for interacting with the cluster. See Install and Set Up kubectl for installation instructions.

Additionally, you need:

  • vCluster CLI version 0.25.0 or higher
  • An existing virtual cluster using K3s distro

Migration process​

The migration is triggered automatically when changing the distribution from K3s to Kubernetes (K8s) during an upgrade.

During migration process vCluster performs these actions:

  • Detects that you are switching from K3s to K8s
  • Copies all relevant certificates and configuration from K3s paths to K8s paths
  • Preserves database content (for both SQLite and embedded etcd backing stores)
  • Adds an annotation to prevent accidental re-migration
  • Launches the new control plane with K8s distro

All your existing workloads, services, and resources remain available after migration without interruption.

Migration limitations

The automated migration process only supports moving from the K3s distro to the K8s distro. Migration between other distro types is not supported. This is a one-way process—migrating back from the K8s distro to K3s is not possible.

Migrate a virtual cluster​

Use a vcluster.yaml file​

If you're managing your virtual cluster with a vcluster.yaml file, modify it to use K8s distro:

Original configuration:

Original vcluster.yaml with K3s
controlPlane:
  distro:
    k3s:
      enabled: true

New configuration:

Updated vcluster.yaml with K8s
controlPlane:
  distro:
    k8s:
      enabled: true

Then apply the changes:

Apply the updated configuration
vcluster create my-vcluster --values vcluster.yaml --upgrade
Migration considerations
  • Migration is one-way: you cannot migrate back from K8s to K3s
  • The K3s-specific resources and directories are preserved after migration for safety
  • Migration supports all backing stores. For external databases (such as PostgreSQL or MySQL), certificates are rotated and the control plane pod restarts during migration
  • High-availability configurations are fully supported

After migration​

After a successful migration, the control plane pod uses the Kubernetes distro instead of K3s. You can verify this by checking the container image of the control plane pod, which now shows a Kubernetes image.

Troubleshoot migration issues​

If you encounter issues during migration, check the control plane pod logs for error messages:

Check control plane logs
kubectl logs -n <namespace> <vcluster-control-plane-pod>

Look for log entries that include "Migrating K3s distro certificates to K8s" to trace the migration process.