Virtual machines: images, templates, cloud-init

15.1 Images¶

Sources:

Download from URL (cloud images: Ubuntu, Debian, Rocky, openSUSE, Fedora, Windows ISOs).
Upload from your browser.
Export a volume to an image (golden image workflow).

apiVersion: harvesterhci.io/v1beta1
kind: VirtualMachineImage
metadata:
  name: ubuntu-2404
  namespace: harvester-public
spec:
  displayName: ubuntu-24.04-cloudimg
  sourceType: download
  url: https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img
  storageClassParameters:
    numberOfReplicas: "3"
    migratable: "true"
    staleReplicaTimeout: "30"

Put shared images in harvester-public so every namespace can use them.
Qcow2 and raw are supported; images are converted to raw backing images.
Image checksums (checksum field) protect against corrupted downloads.
ISOs for installs: attach as a CD-ROM disk, plus an empty volume as the install target.

15.2 Creating a VM (UI)¶

Basics → name, namespace, CPU, memory, SSH key → Volumes (image + size, additional disks) → Networks (VLAN network, model virtio) → Node scheduling → Advanced (cloud-init user data / network data, run strategy, OS type, firmware: BIOS/UEFI/Secure Boot/TPM, reserved memory) → Create.

15.3 cloud-init¶

User data:

#cloud-config
hostname: web01
fqdn: web01.lab.example.net
users:
  - name: andrew
    groups: [sudo]
    shell: /bin/bash
    sudo: ALL=(ALL) NOPASSWD:ALL
    ssh_authorized_keys:
      - ssh-ed25519 AAAAC3... andrew@workstation
package_update: true
packages:
  - qemu-guest-agent
  - curl
runcmd:
  - systemctl enable --now qemu-guest-agent

Always install qemu-guest-agent. It enables the UI to show guest IP addresses, graceful shutdown, filesystem freeze for consistent snapshots, and is required by several features.

Network data (v2 format) for static IPs on VLAN networks without DHCP:

version: 2
ethernets:
  enp1s0:
    addresses: [10.100.0.21/24]
    gateway4: 10.100.0.1
    nameservers:
      addresses: [10.0.0.1]

Store reusable snippets as cloud-config templates (ConfigMaps labelled for Harvester) and pick them in the VM form.

15.4 The raw VirtualMachine object¶

Harvester VMs are KubeVirt VirtualMachines plus Harvester annotations. The notable one is harvesterhci.io/volumeClaimTemplates, which Harvester's webhook uses to create PVCs from images:

apiVersion: kubevirt.io/v1
kind: VirtualMachine
metadata:
  name: web01
  namespace: default
  labels:
    app: web
  annotations:
    harvesterhci.io/volumeClaimTemplates: |
      [{"metadata":{"name":"web01-rootdisk",
        "annotations":{"harvesterhci.io/imageId":"harvester-public/ubuntu-2404"}},
        "spec":{"accessModes":["ReadWriteMany"],"volumeMode":"Block",
        "resources":{"requests":{"storage":"40Gi"}},
        "storageClassName":"longhorn-ubuntu-2404"}}]
spec:
  runStrategy: RerunOnFailure
  template:
    metadata:
      labels:
        app: web
    spec:
      domain:
        cpu:
          cores: 2
          sockets: 1
          threads: 1
        memory:
          guest: 3996Mi          # Harvester subtracts reserved memory
        resources:
          limits:
            cpu: "2"
            memory: 4Gi
        devices:
          disks:
            - name: rootdisk
              bootOrder: 1
              disk:
                bus: virtio
            - name: cloudinitdisk
              disk:
                bus: virtio
          interfaces:
            - name: nic-1
              model: virtio
              bridge: {}
        features:
          acpi: {}
        machine:
          type: q35
      evictionStrategy: LiveMigrate
      networks:
        - name: nic-1
          multus:
            networkName: default/vlan100-servers
      volumes:
        - name: rootdisk
          persistentVolumeClaim:
            claimName: web01-rootdisk
        - name: cloudinitdisk
          cloudInitNoCloud:
            secretRef:
              name: web01-cloudinit
            networkDataSecretRef:
              name: web01-cloudinit

Hand-writing this is error-prone; prefer the UI, templates, or Terraform. But reading it is invaluable for debugging.

15.5 Run strategies¶

Strategy	Behaviour
`RerunOnFailure`	Restart if the VM crashes; stays off if shut down from inside the guest (Harvester default)
`Always`	Always running; restarted even after guest shutdown
`Manual`	Start/stop only via API
`Halted`	Stopped

15.6 Templates¶

VirtualMachineTemplate + VirtualMachineTemplateVersion — versioned blueprints (CPU/mem, disks from images, networks, cloud-init). Create a VM from a template version, and bump versions when the golden image changes. Templates in harvester-public are visible cluster-wide.

15.7 Windows VMs¶

Use the VirtIO drivers ISO as a second CD-ROM during install (storage driver viostor/vioscsi, network NetKVM).
Choose UEFI + TPM for Windows 11 / Server 2025.
Install the QEMU guest agent and VirtIO balloon driver from the virtio-win ISO.
Use the Sysprep support (v1.9) for generalizing images, and cloudbase-init for cloud-init-style customization.
Set OS type to Windows in the VM form so Hyper-V enlightenments are applied for better performance.

15.8 Console and access¶

VNC and serial console in the UI.
virtctl works against Harvester's kubeconfig:

virtctl console web01 -n default
virtctl vnc web01 -n default
virtctl ssh andrew@vm/web01 -n default
virtctl start|stop|restart|migrate web01 -n default

← Harvester storage in depth · Index · Advanced VM features →