Show examples as

VM images

Supported formats for VM disks are qcow2 and raw. ISO-based workflows for VM disks are not supported in the current upload path.

Controller-fetched image

The controller records desired state; the node agent downloads and verifies the image, caches it under /var/lib/kcore/images/, and applies generated Nix configuration. Use --image with --image-sha256 (see VM creation modes).

Upload to a node

For large or air-gapped files, stream an image to the node cache once, then reference it by path on subsequent creates:

kcore-kctl --node 192.168.40.105:9091 node upload-image \
  -f /path/to/image.qcow2 \
  --name my-image.qcow2 \
  --format qcow2
resource "kcore_vm" "fetched" {
  name               = "web-01"
  cpu                = 2
  memory_bytes       = 4 * 1024 * 1024 * 1024
  storage_backend    = "filesystem"
  storage_size_bytes = 40 * 1024 * 1024 * 1024
  image_url          = "https://cloud.debian.org/images/cloud/bookworm/latest/debian-12-genericcloud-amd64.qcow2"
  image_sha256       = "<sha256>"

  nic {
    network = "default"
  }
}

resource "kcore_vm" "uploaded" {
  name               = "web-02"
  cpu                = 2
  memory_bytes       = 4 * 1024 * 1024 * 1024
  storage_backend    = "filesystem"
  storage_size_bytes = 40 * 1024 * 1024 * 1024
  image_path         = "/var/lib/kcore/images/my-image.qcow2"
  image_format       = "qcow2"

  nic {
    network = "default"
  }
}

Optional --image-sha256 validates content during upload. Then create a VM with --image-path /var/lib/kcore/images/... and --image-format.

Wait for SSH

--wait-for-ssh checks that the VM is running, resolves an IP (DHCP lease or fallback), and probes the SSH port from the hypervisor. Use a timeout appropriate for cloud-init.

Constraints