This is unreleased documentation for SUSE® Virtual Clusters v1.2.0 (Dev).

How to Choose Between Shared, Virtual, and HCP Mode

This guide helps you choose the right mode for your virtual cluster: Shared, Virtual, or HCP (Hosted Control Plane).

If you are unsure, start with Shared mode - it is the default and fits most common scenarios.

Shared Mode (default)

Best for:

  • Developers who want to run workloads quickly without managing Kubernetes internals

  • Platform teams that require visibility and control over all workloads

  • Users who need access to host-level resources (For example, GPUs)

In Shared mode, the virtual cluster runs its own K3s server but relies on the host to execute workloads. The virtual kubelet syncs resources, enabling lightweight, fast provisioning with support for cluster resource isolation. More details on the architecture.

Use Cases by Persona

Developer

"I’m building a web app that should be exposed outside the virtual cluster."
→ Use Shared mode. It allows you to expose your application.

Data Scientist:

"`I need to run Jupyter notebooks that leverage the cluster’s GPU.`"
→ Use Shared mode. It gives access to physical devices while keeping overhead low.

Platform Admin

"I want to monitor and secure all tenant workloads from a central location."
→ Use Shared mode. Host-level agents (for example, observability, policy enforcement) work across all virtual clusters.

Security Engineer

"I need to enforce security policies like network policies or runtime scanning across all workloads."
→ Use Shared mode. The platform can enforce policies globally without tenant bypass.

"I need to test a new admission controller or policy engine."
→ Use Shared mode, if it is scoped to your virtual cluster. You can run tools like Kubewarden without affecting the host.

CI/CD Engineer

"I want to spin up disposable virtual clusters per pipeline run, fast and with low resource cost."
→ Use Shared mode. Its quick to provision and ideal for short-lived, namespace-scoped environments.

Virtual Mode

Best for:

  • Advanced users who need full Kubernetes isolation

  • Developers testing experimental or cluster-wide features

  • Use cases requiring control over the entire Kubernetes control plane

In Virtual mode, the virtual cluster runs its own isolated Kubernetes control plane. It supports different CNIs, and API configurations — ideal for deep experimentation or advanced workloads. More details on the architecture.

Use Cases by Persona

Developer

"I need to test a new Kubernetes feature gate that is disabled in the host cluster."
→ Use Virtual mode. You can configure your own control plane flags and API features.

Platform Admin

"We are testing upgrades across Kubernetes versions, including new API behaviors." → Use Virtual mode. You can run different Kubernetes versions and safely validate upgrade paths.

Network Engineer

"I’m evaluating a new CNI that needs full control of the cluster’s networking."
→ Use Virtual mode. You can run a separate CNI stack without affecting the host or other tenants.

Security Engineer

"I’m testing a new admission controller and policy engine before rolling it out cluster-wide."
→ Use Virtual mode, if you need to test cluster-wide policies, custom admission flow, or advanced extensions with full control.

HCP Mode

HCP mode is experimental in SUSE® Virtual Clusters v1.2.0.

Best for:

  • Users who want K3k to manage the control plane lifecycle but need real, external worker nodes

  • Edge and IoT scenarios where workers run outside the host data center

  • Evaluating workloads on dedicated bare-metal or VM hardware while keeping the apiserver centrally managed

In HCP mode, K3k runs an agentless K3s control plane inside the host cluster, and you supply the worker nodes. External workers join the cluster using the standard K3s installer script. The apiserver must be reachable from your worker network via nodePort, loadBalancer, or ingress. For more information, see architecture and the step-by-step Creating an HCP Virtual Cluster guide.

Use Cases by Persona

Platform Admin

"I want K3k to manage the control plane lifecycle for me, but I need real worker nodes that aren’t part of the host cluster."
→ Use HCP mode. The control plane runs in the host cluster, while workers stay under your direct control.

Edge / IoT Operator

"I want a managed control plane in my central cluster, with workers running at the edge."
→ Use HCP mode. Edge workers join over the network and run real workloads on local hardware.

Developer

"I need to test workloads on dedicated bare-metal or VM nodes that aren’t part of the host cluster."
→ Use HCP mode. You get a managed control plane without losing access to real-hardware features on the workers.

Additional information

If you are evaluating more advanced use cases or want a deeper comparison, see the full trade-off breakdown in the Architecture documentation.