Show examples as

VM creation modes

VMs are created through the controller API. The patterns below are kcore-kctl create vm, YAML, and Terraform provider kcorehypervisor/kcore 0.5.0.

Showing CLI examples below. Use the toggle above to switch to YAML manifests.

Showing YAML examples below. Use the toggle above for raw kctl commands.

Showing Terraform examples. Provider source is kcorehypervisor/kcore, version 0.5.0.

Requirements

HTTPS image + SHA256

Recommended when you want deterministic verification and node-side caching. Provide an https:// URL and --image-sha256.

kcore-kctl create vm web-01 \
  --image https://cloud.debian.org/images/cloud/bookworm/latest/debian-12-genericcloud-amd64.qcow2 \
  --image-sha256 <sha256> \
  --network default \
  --storage-backend filesystem \
  --storage-size-bytes 42949672960

Node-local image path

Use when the image file already exists on the target node (e.g. after upload).

kcore-kctl create vm web-01 \
  --image-path /var/lib/kcore/images/base.qcow2 \
  --image-format qcow2 \
  --network default \
  --storage-backend filesystem \
  --storage-size-bytes 42949672960

YAML manifest

Declarative definitions can be applied with kctl apply -f vm.yaml or kcore-kctl create vm -f vm.yaml. Use kind: VM, image reference under spec.disks, and NICs under spec.nics.

# vm.yaml
kind: VM
metadata:
  name: web-01
spec:
  cpu: 2
  memoryBytes: "4G"
  storageBackend: filesystem
  storageSizeBytes: 42949672960
  disks:
    - backendHandle: https://cloud.debian.org/images/cloud/bookworm/latest/debian-12-genericcloud-amd64.qcow2
      sha256: "<sha256>"
      format: qcow2
  nics:
    - network: default

Apply the manifest:

kctl apply -f vm.yaml

CLI flags (--storage-backend, --storage-size-bytes) override the YAML values when both are provided.

Terraform

image_url and image_path are mutually exclusive. URL mode needs image_sha256. cpu and memory_bytes are required.

HTTPS image + SHA256

resource "kcore_vm" "web" {
  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"
  }
}

Node-local image path

Do not set image_url on the same resource.

resource "kcore_vm" "web" {
  name               = "web-01"
  cpu                = 2
  memory_bytes       = 4 * 1024 * 1024 * 1024
  storage_backend    = "filesystem"
  storage_size_bytes = 40 * 1024 * 1024 * 1024

  image_path   = "/var/lib/kcore/images/base.qcow2"
  image_format = "qcow2"

  nic {
    network = "default"
  }
}

Pin placement with target_node or target_dc. nodeLabels and antiAffinity are CLI and YAML only in provider 0.5.0. Register a key with kcore_ssh_key and set ssh_key_names. cloud_init_user_data is the cloud-init YAML string.

SSH access patterns

Scheduling

Omit --target-node to let the controller choose a node, or set --target-node <node id> to pin placement.

Automatic placement still picks the ready, approved node with the most free memory, then CPU. Free capacity is heartbeat load subtracted from physical capacity times the overcommit ratio in controller.yaml (scheduler.cpuOvercommit and scheduler.memoryOvercommit, both default 1.0).

YAML: spec.nodeLabels is a list of key=value strings, and spec.antiAffinity is the group name.

Readiness

Validation rules (summary)