How to install KubeOps Virtualization (kubevirt)

KubeVirt opens up a powerful way to run virtual machines on top of Kubernetes, creating a unified platform for both containerized and traditional workloads. This guide walks through the essential steps for getting KubeVirt up and running using the KOSI package manager - from pulling and preparing the KubeVirt package, to creating a custom configuration file with your credentials, and finally verifying a successful installation in the kubevirt namespace. Once these steps are complete, you’ll be ready to deploy and manage virtual machines alongside your existing container infrastructure - all within a single Kubernetes cluster.

kubevirt is a specialized package which extends the capabilities of the KubeOps platform to support machine virtualization.

Requirements

To follow the next steps, make sure you have your credentials ready from your KubeOps.net account.

Make sure you have prepared the following points:

• A KubeOps cluster with one master node.
• Access to the master node with root privileges.

Step 1 - Download kubevirtvm

1. Log in to the master node remotely. For example, using ssh.
2. Most kubeops software needs root privileges. Switch to root user.

sudo -i

1. Login to KOSI using your kosi username.

kosi login -u [USERNAME]

1. Use the KOSI package manager to search for available software packages. In this case, we restrict the search to KubeOps virtualization using kubeops-vm.

kosi search --hub kubeops-vm

1. The package is named kosi-example-package-userv4. Download the package using the kosi pull command and save the file with the desired file name. For example, kubevirt.tgz.

kosi pull --hub kubeops-vm kubeops/kubevirt:2.0.1 -o kubevirt.tgz

Step 2 - remove the taint of the master node

if you have a single node cluster, then you need to remove the taint on the master node. replace [NODENAME] with the name of you master-node

kubectl taint nodes [NODENAME] node-role.kubernetes.io/control-plane:NoSchedule-

Step 3 - Create kubevirt Configuration File

Before you can install the package, you must create a configuration file (.yaml). Use the file below and save it in the same folder as the package. Name the file kubevirt-values.yaml.

🛑 Replace [USERNAME] and [PASSWORD] with your KOSI credentials.

🧹 IMPORTANT: If you do not have Prometheus and Grafana installed, you must remove the monitorNamespace and monitorAccount fields entirely from the YAML file. Leaving them in without monitoring components will cause the deployment to fail.

kubevirtValues:
  namespace: kubevirt
  imagePullSecretCred:
    registry: registry.kubeops.net
    user: [USERNAME]
    password: [PASSWORD]
  kubevirtobject:
    spec:
      monitorNamespace: monitoring # change the namespace to the one in which your Grafana is running
      monitorAccount: prometheus-grafana # the standard grafana ServiceAccount of the KubeOps Platform, if you use the prometheus package of the platform, no changes are required
      configuration:
        developerConfiguration:
          logVerbosity:
            virtLauncher: 2
            virtHandler: 3
            virtController: 4
            virtAPI: 5
            virtOperator: 6
          featureGates:
          - ExpandDisks
          - CPUManager
          - ExperimentalIgnitionSupport
          - HypervStrictCheck
          - Sidecar
          - HostDevices
          - Snapshot
          - VMExport
          - HotplugVolumes
          - HostDisk
          - ExperimentalVirtiofsSupport
          - DownwardMetricsFeatureGate
          - Root
          - ClusterProfiler
          - WorkloadEncryptionSEV
          - VSOCK
          - DisableCustomSELinuxPolicy
          - KubevirtSeccompProfile
          - DisableMDEVConfiguration
          - PersistentReservation
          - VMPersistentState
          - MultiArchitecture
          - AutoResourceLimitsGate
          - AlignCPUs
          - VolumesUpdateStrategy
          - VolumeMigration
          - InstancetypeReferencePolicy
          useEmulation: false

Step 3 - Install kubevirt

1. Install the kubevirt package using the prepared configuration file.

kosi install -p kubevirt.tgz -f kubevirt-values.yaml

1. Check your installation using the kubectl command.

kubectl get pods -n kubevirt

The installation is complete when the status of all pods is set to “Running”. For example:

if you have a image pull backoff error message, then you can create the image pullsecret anew. in this example the kubevirt namespace is used, if you have kubevirt deployed in a different namespace, then you need to replace the value of the -n parameter.

kubectl -n kubevirt create secret docker-registry kubeops-vm --docker-server=localhost:30002 --docker-username=admin --docker-password=<admin password - see harborpass value in kubeopsctl.yaml>

Next Steps

After installation, you can start setting up and deploying a custom VM (see [How to create and deploy a Custom Virtual Machine using KubeOps](How to create and deploy a Custom Virtual Machine using KubeOps)).