Virtual Machines

​

Overview

• A “lift and shift” of an existing virtual machine image (VMDK, qcow2, VHD) without re‑platforming it into a container.
• A specific guest OS or kernel (Windows, a custom Linux distribution, an appliance image).
• Software that must run against real hardware abstractions (custom kernel modules, nested virtualization‑style tooling, legacy applications).

​

A VM is just another workload

​

Lifecycle & disruption

• Persist anything you need to keep on a volume set — both the boot disk and any data disks. State written only to an ephemeral root disk does not survive rescheduling.
• Expect cold reboots during node scale‑down, node upgrades, and cluster maintenance. When running with your own Mk8s location you can control this in your nodepool settings.
• Make boot idempotent. Your cloud-init and guest services should converge to a working state on every boot, not just the first.

​

Minimal example

kind: workload
name: my-vm
spec:
  type: vm
  containers:
    - name: vm
      cpu: 1000m
      memory: 2Gi
      ports:
        - number: 80
          protocol: http
  vm:
    bootDisk:
      source:
        oci:
          image: quay.io/containerdisks/ubuntu:22.04
      persist:
        volumeSet: cpln://volumeset/my-vm-root
    runStrategy: Always
    cloudInit:
      userData: |
        #cloud-config
        packages:
          - nginx
        runcmd:
          - systemctl enable nginx
          - systemctl start nginx
  firewallConfig:
    external:
      inboundAllowCIDR: ['0.0.0.0/0']
      outboundAllowCIDR: ['0.0.0.0/0']
    internal:
      inboundAllowType: same-gvc
  defaultOptions:
    autoscaling:
      minScale: 1
      maxScale: 1

​

The container entry

• Exactly one container. Multiple containers are rejected.
• cpu must be a whole number of cores — a multiple of 1000m, and at least 1000m. The guest is presented this many vCPU cores. (500m, 1500m, etc. are rejected.)
• memory is the RAM presented to the guest (e.g. 2Gi).
• ports advertise the services the guest listens on, for service discovery and mesh routing. Use the ports array ({ number, protocol }); the singular port field is not valid for VMs.
• metrics enables Prometheus scraping of a guest endpoint (see Custom metrics).
• readinessProbe / livenessProbe support tcpSocket and httpGet only (exec and grpc are rejected).
• volumes attach data disks to the VM (see Persistence).
• Not valid for VMs: image, command, args, workingDir, lifecycle, and the singular port. The guest OS owns process lifecycle.

​

Boot disk

​

OCI containerDisk source

bootDisk:
  source:
    oci:
      image: quay.io/containerdisks/ubuntu:22.04

• The image may be a public containerDisk (e.g. quay.io/containerdisks/ubuntu:22.04), or one you publish to your org’s registry and reference as //image/<name>:<tag> or /org/<org>/image/<name>:<tag>.
• Cross‑org image links are rejected; the image must belong to the calling org or be a public registry reference.
• persist.volumeSet is required. The boot disk is always a per‑replica PVC backed by a volume set; the image seeds it on first boot.

​

HTTP(S) source

bootDisk:
  source:
    http:
      url: https://example.com/images/my-disk.qcow2
      checksum: 'sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08'
    persist:
      volumeSet: cpln://volumeset/my-vm-root

• The importer accepts common disk formats — qcow2, raw, VMDK, VHD/VHDX, VDI, ISO — and gzip/xz‑compressed variants, converting them to the disk’s native format on import.
• checksum is optional but recommended: sha256:<hex> or sha512:<hex>. The import is verified against it.
• Import runs once per replica’s persistent disk; subsequent boots reuse the imported disk.

​

Boot disk options

​

Persistence with volume sets

​

Persisting the boot disk

vm:
  bootDisk:
    source:
      oci:
        image: quay.io/containerdisks/ubuntu:22.04
    persist:
      volumeSet: cpln://volumeset/my-vm-root

​

Attaching additional data disks

containers:
  - name: vm
    cpu: 1000m
    memory: 2Gi
    volumes:
      - uri: cpln://volumeset/my-vm-data
        name: data
        bus: virtio
        serial: DATA001

cloudInit:
  userData: |
    #cloud-config
    runcmd:
      - |
        DEV=/dev/disk/by-id/*DATA001*
        if ! blkid $DEV; then mkfs.ext4 -L data $DEV; fi
        mkdir -p /mnt/data
        echo 'LABEL=data /mnt/data ext4 defaults,nofail 0 2' >> /etc/fstab
        mount -a

​

Networking & ports

• Exposed ports come from containers[0].ports. These are the ports other workloads, domains, and probes can reach, and they flow through the service mesh.
• Port 22 (SSH) is always reachable internally by Control Plane — SSH authenticates with its own certificate trust (see SSH access).
• A single network interface is supported (spec.vm.networks accepts one entry, default name default).
• Service discovery: other workloads reach the VM at <workload>.<gvc>.cpln.local on its exposed ports, exactly like a container workload.

​

Connecting with RDP (Windows)

vm:
  guestOS: windows
  cloudInit:
    userData: |
      #ps1_sysnative
      Set-ItemProperty -Path 'HKLM:\System\CurrentControlSet\Control\Terminal Server' -Name 'fDenyTSConnections' -Value 0
      Enable-NetFirewallRule -DisplayGroup 'Remote Desktop'
      net user admin 'YourStrongPassword!' /add
      net localgroup administrators admin /add

cpln port-forward my-windows-vm 3389:3389 --gvc my-gvc --location aws-us-west-2

localhost:3389

xfreerdp /v:localhost:3389 /u:admin

​

Cloud-init & platform injection

​

Providing your own cloud-init

cloudInit:
  userDataSecret: //secret/my-vm-cloudinit

​

What the platform injects

• Network configuration. A name‑based interface match with DNS pointed at the in‑cluster forwarder. This is platform‑managed and not user‑overridable: KubeVirt re‑randomizes the VM’s MAC on every restart, and a MAC‑pinned network config would stall the guest after a reschedule.
• In‑cluster DNS. So the guest can resolve *.cpln.local and other cluster service names, and so cross‑location (wormhole) peers are reachable.
• Service‑mesh interception. The VM’s pod joins the Istio mesh; traffic on the exposed ports is mutually authenticated with the workload identity.
• SSH trust. A platform SSH certificate authority is trusted by the guest and a platform user is provisioned, enabling certificate‑based SSH (see below). This is re‑applied on every boot so it survives image and platform updates.
• (Windows only) A DNS bootstrap script that points the guest’s adapters at the in‑cluster resolver and sets the cluster search suffixes.

​

SSH access

• cloudInit.sshPublicKeySecrets — a list (max 8) of secrets holding public keys, injected for the default user.
• spec.vm.accessCredentials — per‑user key delivery. Each entry maps a key secret to one or more guest users, delivered via qemuGuestAgent (default) or configDrive.

vm:
  accessCredentials:
    - sshPublicKeySecret: //secret/team-ssh-keys
      users: [ubuntu, ops]
      deliveryMethod: qemuGuestAgent

​

Scaling & lifecycle

• Replicas are controlled by defaultOptions.autoscaling.minScale / maxScale. Each replica is an independent VM with its own persistent disk(s).
• runStrategy controls the power state:
  • Always (default) — keep the VM running; restart it if it stops.
  • RerunOnFailure — restart only on non‑zero exit.
  • Manual — start/stop is driven explicitly.
  • Halted — defined but powered off. Requires minScale: 0.
• clock.timezone sets the guest clock (default UTC).
• hostname / subdomain set the guest’s hostname and DNS subdomain.
• firmware selects the bootloader (efi default, or bios) and optional SMBIOS identifiers (uuid, serial, smbios.*).

​

Settings reference

​

Related

• Publishing & converting VM images
• Run VM workloads on your own mk8s cluster
• Volume sets
• Workload firewall
• Workload identity
• Custom metrics