VM creation modes

VMs are created through the controller API. Below are the main patterns supported by kcore-kctl create vm (and equivalent YAML).

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.

Requirements

At least one approved node.
Storage flags: --storage-backend (filesystem, lvm, or zfs) and --storage-size-bytes.

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.

SSH access patterns

Controller-managed keys: register a public key (kcore-kctl ssh-key create ...) and pass --ssh-key <name> on create.
Inline key: --username + --ssh-public-key for compliant, passwordless cloud-init.
Custom cloud-init: --cloud-init-user-data-file (cannot combine with generated identity flags).
Password login requires explicit --compliant=false (non-compliant mode).

Scheduling

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

Readiness

--wait — wait until the VM reaches running state.
--wait-for-ssh — wait until SSH is reachable from the node (with optional timeout and port).

Validation rules (summary)

--image and --image-path are mutually exclusive.
URL mode requires HTTPS and a SHA256.
Path mode requires --image-format when format cannot be inferred.
Password mode requires --username; SSH public key mode requires --username.