Skip to main content
Version: main 🚧

Migrate from K3s to Kubernetes

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.

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. Both migration methods are covered in detail in the Migrate a virtual cluster section.

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 the vCluster CLI​

You can migrate using the CLI by specifying the K8s distro during upgrade:

Migrate using vcluster CLI
vcluster --upgrade my-vcluster --distro=K8s

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 my-vcluster --values vcluster.yaml
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 both SQLite and embedded etcd backing stores
  • 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.

Clean up K3s resources​

The migration process preserves the K3s configuration and certificates on the control plane pod. These resources are located in specific directories on the control plane pod and are safe to delete once you've confirmed the migration was successful:

K3s resource directories on the control plane pod
/data/k3s-config    # Contains the K3s kubeconfig and other configuration files
/data/agent         # Contains K3s agent credentials, certificates and keys

You can remove these directories using a kubectl exec command:

Removing K3s resources after successful migration
kubectl exec -n <vcluster-namespace> <vcluster-control-plane-pod> -- rm -rf /data/K3s-config /data/agent
tip

Consider keeping these resources for some time after migration before deleting them. They can be useful for:

  • Troubleshooting any issues that might arise after migration
  • Providing a reference for certificate paths and configurations
  • Enabling potential recovery options if needed

The storage impact of these directories is typically minimal, so there's usually no urgency to remove them immediately.

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> -c syncer

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