Installer KubeVirt sur un cluster de lab (sans /dev/kvm)

Installer KubeVirt se fait en deux temps : on déploie d'abord son opérateur, puis on crée la ressource KubeVirt qui déclenche l'installation des composants. Ce guide couvre le cas le plus courant en apprentissage : un cluster de lab (ici k3d) sur une machine sans /dev/kvm, grâce à l'émulation logicielle. Public : intermédiaire, qui connaît déjà les bases de Kubernetes. Version : v1.9.

Vous allez déployer l'opérateur, activer l'émulation, vérifier que KubeVirt est prêt, installer virtctl, et valider le tout avec une VM qui démarre réellement. Les composants virt-* que vous allez voir apparaître sont présentés dans la leçon Architecture et concepts : la lire d'abord rend les sorties de kubectl beaucoup plus parlantes.

Ce que vous allez apprendre

• Déployer l'opérateur KubeVirt et les composants.
• Activer l'émulation logicielle pour un lab sans /dev/kvm.
• Vérifier l'installation et installer virtctl.
• Valider avec une première VM.

Prérequis

• Docker en fonctionnement et k3d installé : k3d fait tourner les nœuds Kubernetes dans des conteneurs.
• Un cluster Kubernetes de lab. Ici k3d ; minikube ou kind conviennent aussi, à condition d'une version récente de Kubernetes (voir la section suivante).
• kubectl configuré sur ce cluster.
• Accès sortant pour tirer les images depuis quay.io et GitHub.
• La leçon Architecture et concepts, pour le vocabulaire (VM, VMI, composants virt-*).

Émulation logicielle : pourquoi ?

KubeVirt exécute les VM avec KVM, qui exige le périphérique /dev/kvm (virtualisation matérielle). Sur un laptop, une VM imbriquée ou un CI, ce périphérique est souvent absent. L'émulation logicielle (useEmulation: true) bascule QEMU en mode TCG : plus lent, mais suffisant pour tout apprendre. En production, on garde la virtualisation matérielle.

Créer le cluster de lab

Un cluster k3d jetable suffit. KubeVirt a besoin de pods privilégiés, ce que k3d autorise par défaut. Il faut en revanche une version récente de Kubernetes : KubeVirt 1.9 active par défaut la feature gate ImageVolume (un interrupteur de fonctionnalité), qui s'appuie sur la fonction ImageVolume de Kubernetes, absente du k3s par défaut de k3d. On impose donc une image k3s récente, épinglée par son digest.

k3d cluster create kubevirt-lab \
  --image rancher/k3s:v1.37.1-k3s1@sha256:ca7f37d993d82ef0dcdcfecb2e0e2618ea541dbaffc620c8cedebe01a82acd0d \
  --wait
kubectl config use-context k3d-kubevirt-lab

Le nœud doit passer Ready en quelques secondes (kubectl get nodes, version v1.37.1+k3s1). Avec le k3s par défaut de k3d, l'installation réussit mais la première VM échoue : voir la section Dépannage.

Installer KubeVirt

1. Déployer l'opérateur. On épingle la version de ce guide, v1.9.1. Le projet publie sa dernière version stable dans un fichier stable.txt : consultez-le pour savoir si une version plus récente existe, mais n'installez que celle dont vous suivez la documentation.

   VER=v1.9.1
   # Dernière version stable publiée par le projet :
   curl -sL https://storage.googleapis.com/kubevirt-prow/release/kubevirt/kubevirt/stable.txt
   
   kubectl apply -f "https://github.com/kubevirt/kubevirt/releases/download/${VER}/kubevirt-operator.yaml"
   kubectl -n kubevirt rollout status deploy/virt-operator --timeout=120s
   # deployment "virt-operator" successfully rolled out

2. Activer KubeVirt avec l'émulation. La ressource KubeVirt pilote l'installation ; le champ useEmulation bascule en mode logiciel.

   kubevirt-cr.yaml

   apiVersion: kubevirt.io/v1
   kind: KubeVirt
   metadata:
     name: kubevirt
     namespace: kubevirt
   spec:
     configuration:
       developerConfiguration:
         useEmulation: true   # lab sans /dev/kvm : QEMU en mode TCG

   kubectl apply -f kubevirt-cr.yaml
   kubectl -n kubevirt wait kv kubevirt --for=condition=Available --timeout=360s
   # kubevirt.kubevirt.io/kubevirt condition met

   Le déploiement tire plusieurs images ; comptez quelques minutes au premier lancement.

3. Vérifier l'état. La phase passe à Deployed et les composants tournent.

   kubectl get kubevirt -n kubevirt
   # NAME       AGE    PHASE
   # kubevirt   118s   Deployed
   
   kubectl get pods -n kubevirt
   # virt-api-...                1/1 Running
   # virt-controller-...         1/1 Running   (x2)
   # virt-exportproxy-...        1/1 Running   (x2)
   # virt-handler-...            1/1 Running   (DaemonSet, 1 par nœud)
   # virt-operator-...           1/1 Running   (x2)
   # virt-template-apiserver-... 1/1 Running
   # virt-template-controller-... 1/1 Running

   On attend dix pods Running. Chaque composant a un rôle : virt-api (API agrégée), virt-controller (cycle de vie des VM), virt-handler (agent par nœud qui pilote libvirt), virt-operator (installe et met à jour l'ensemble). Les pods virt-exportproxy et virt-template-* apparaissent avec la 1.9, qui active par défaut toutes les feature gates en Beta, dont Template. Le pod virt-launcher n'apparaît pas encore : il n'est créé qu'au démarrage d'une VM, comme l'explique Architecture et concepts.

Installer virtctl

virtctl est la CLI compagnon pour piloter les VM (console, VNC, start/stop, migration). On installe le binaire de la même version que le cluster. La commande ci-dessous vise linux-amd64 ; la release publie aussi darwin-amd64, darwin-arm64, linux-arm64, linux-s390x et windows-amd64.exe : changez le suffixe selon votre poste.

VER=v1.9.1
curl -sL -o virtctl \
  "https://github.com/kubevirt/kubevirt/releases/download/${VER}/virtctl-${VER}-linux-amd64"
chmod +x virtctl && sudo mv virtctl /usr/local/bin/

virtctl version --client
# Client Version: ... GitVersion:"v1.9.1" ...

La release v1.9.1 ne publie pas de fichier de sommes de contrôle pour les binaires virtctl : seule l'archive des sources porte une signature (v1.9.1.tar.gz.asc). Il n'y a donc aucune empreinte à comparer ; le téléchargement repose sur HTTPS depuis le dépôt officiel, et virtctl version --client confirme au moins la version obtenue.

Elle s'installe aussi en plugin kubectl via krew (kubectl krew install virt), auquel cas on l'appelle avec kubectl virt ....

Valider avec une première VM

Le vrai test : une VM qui démarre. On utilise une image cirros minuscule, empaquetée en containerDisk (un disque livré dans une image de conteneur).

testvm.yaml

apiVersion: kubevirt.io/v1
kind: VirtualMachine
metadata:
  name: testvm
spec:
  runStrategy: Always
  template:
    spec:
      domain:
        devices:
          disks:
          - name: containerdisk
            disk:
              bus: virtio
        resources:
          requests:
            memory: 128Mi
      volumes:
      - name: containerdisk
        containerDisk:
          image: quay.io/kubevirt/cirros-container-disk-demo:v1.9.1@sha256:ebdb8d8b9b480f6ee7664ed3fdde8428767664f507d98f94090edeff04d7ebf2

kubectl apply -f testvm.yaml
kubectl get vm,vmi
# virtualmachine.../testvm    Running   True
# virtualmachineinstance.../testvm   Running   10.42.0.17   ...   True

La VM atteint l'état Running et le VMI (l'instance en cours) reçoit une adresse IP dans le réseau de pods. En émulation, le boot est lent mais bien réel. Nettoyage : kubectl delete vm testvm. Cette VM de test est volontairement minimale : Créer et gérer une VM avec KubeVirt reprend le manifeste pour piloter runStrategy, injecter cloud-init et se connecter en console et en SSH, et indique en fin de guide comment supprimer la VM puis le cluster kubevirt-lab de ce lab.

Dépannage

La VM reste en CrashLoopBackOff et la VMI n'existe pas

Sur un cluster dont Kubernetes est trop ancien (le k3s par défaut de k3d 5.8, en Kubernetes 1.31), l'installation se déroule normalement mais la première VM échoue. Environ 1 min 30 après kubectl apply -f testvm.yaml, kubectl get vm,vmi montre la VM en CrashLoopBackOff (READY False) et aucune VMI : elle est créée puis supprimée en boucle. La condition de la VM est Ready=False avec la raison VMINotExists (VMI does not exist). Le pod virt-launcher n'existe que quelques secondes, ce qui rend kubectl get pods souvent vide et kubectl describe pod inexploitable.

Le diagnostic fiable passe par les événements de type Warning.

kubectl get events --field-selector type=Warning

Le message qui identifie la cause se termine ainsi :

exec: "/container-disk-binary/usr/bin/container-disk": stat /container-disk-binary/usr/bin/container-disk: no such file or directory

La cause est la feature gate ImageVolume, activée par défaut depuis KubeVirt 1.9 : le cluster n'a pas la fonction Kubernetes correspondante. Ce n'est pas un problème d'image, le même échec se produit avec l'image :v1.9.1. Deux parades fonctionnent.

• Utiliser un cluster récent : recréer le cluster avec l'image k3s de la section « Créer le cluster de lab ». La CR de ce guide fonctionne alors sans changement.
• Désactiver la feature gate dans la CR, si vous ne pouvez pas changer de cluster :

kubevirt-cr.yaml

spec:
  configuration:
    developerConfiguration:
      useEmulation: true
      disabledFeatureGates:
        - ImageVolume

Avec cette CR appliquée, la VMI passe en Running en une dizaine de secondes.

Autres symptômes

D'autres échecs courants viennent de la configuration du cluster plutôt que de KubeVirt lui-même. Chaque ligne associe un symptôme à sa cause la plus probable et à ce qu'il faut vérifier.

• La VMI reste en Scheduling/Pending : souvent l'émulation n'est pas activée alors que /dev/kvm est absent. Vérifiez useEmulation: true dans la CR, puis kubectl describe vmi testvm.
• virt-handler en CrashLoopBackOff : le cluster n'autorise pas les pods privilégiés. Sur k3d/k3s c'est bon par défaut ; sur un cluster durci, il faut l'autoriser pour le namespace kubevirt.
• Images non tirées : quay.io inaccessible. Vérifiez la sortie réseau du cluster.
• Boot très lent : normal en TCG. Pour des perfs réelles, un nœud avec /dev/kvm et sans useEmulation.

À retenir

• KubeVirt s'installe en deux temps : opérateur puis ressource KubeVirt.
• L'émulation logicielle (useEmulation: true) permet un lab sans virtualisation matérielle.
• kubectl get kubevirt doit afficher Deployed et les pods virt-* Running.
• virtctl est la CLI indispensable pour piloter les VM.
• Une VM containerDisk cirros valide l'installation de bout en bout.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

6 questions

6 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

×

📖 Voir la documentation →