Skip to main content
Version: v0.27 Stable

Migrate from K3s to Kubernetes

Limited vCluster Tenancy Configuration Support

This feature is only available when using the following worker node types:

  • Host Nodes

    • 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.