Virtual machine concepts

A virtual machine is a record in the inventory that describes a computer, plus the instance of it that runs on a host. This page explains the parts that every task in this section relies on.

Configuration and observed state

The record of a virtual machine has two halves.

• The configuration is what you ask for: the number of vCPUs, the memory, the firmware, the disks, the network adapters and the CD/DVD drives. You change it with Edit settings, kyvernon vm reconfigure or POST /v1/vms/{id}/reconfigure.
• The observed state is what the host reports: the power state, the host it runs on, the time of the last power-on, the memory in use, and, when the guest agent runs, the host name and addresses of the guest.

Kyvernon records the power state that you want and the host agent brings the virtual machine to it. When the host cannot do that, the host reports the reason and the task that asked for it fails with it.

Two people can change the same virtual machine at the same time. Each change names the version of the configuration it started from, and Kyvernon merges changes that started from versions it still knows. When a change cannot be merged, the request fails with error.vm.concurrent_modification; read the virtual machine again and repeat the change.

Power states

A virtual machine is powered on, powered off or suspended. A powered-on machine can also be paused: its vCPUs are stopped and its memory stays in place. The API reports the states as powered_on, powered_off, suspended and paused.

Power off stops the virtual machine at once and does not ask the guest. Shutting down asks the guest first, through the guest agent and then through the power button of the virtual machine, and powers off hard when the guest has not stopped after the timeout, 90 seconds by default. On a virtual machine that is already off, both succeed and change nothing.

Tasks

Every operation that changes a virtual machine runs as a task. The API answers with status 202 and the identifier of the task. The web console follows the task for you and shows it in the pane at the bottom. The command-line client prints the identifier, and --wait waits for the task to end. A task ends as completed, failed or cancelled and keeps the name of the user that started it.

Placement on a host

A virtual machine runs on one host at a time. In the new virtual machine wizard you choose a cluster, to let Kyvernon pick a connected host, or a host, to place it yourself. A virtual machine that has no host yet is placed when it is powered on. A host in maintenance mode receives no new virtual machines. A powered-off virtual machine keeps the host it last ran on until it is powered on again or relocated.

Kyvernon checks the memory before power-on. The memory of the host, minus a reserve of 2,048 MiB by default, minus the memory of the virtual machines that already run there, must cover the new one. The controller settings host_memory_reserve_mib and memory_overcommit_ratio change these checks.

Where a virtual machine is in the inventory

A virtual machine sits in a folder of the datacenter and belongs to a resource group of the cluster or host that it runs on. You choose the folder in the wizard and the compute resource in the same step. Objects have identifiers such as vm-42, host-3, datastore-1, group-v5 for a folder of virtual machines and resgroup-7 for a resource group. The CLI and the API take these identifiers.

To move virtual machines to another folder, run kyvernon inventory move-into <folder> --entity <vm>; it needs the privilege Folder.Move on the destination. To move them to another resource group, run kyvernon inventory move-into-pool <pool> --entity <vm>; it needs Resource.AssignVMToPool on the destination. The tree itself is read with kyvernon inventory roots, children and path, and a long-lived client follows changes with kyvernon inventory changes.

Developers who use gRPC find the same objects in InventoryService, and the virtual machine operations create, delete, power on, power off, shut down, reset, suspend and reconfigure in VmService.

Limits on devices

A running virtual machine accepts only growth: more vCPUs, more memory, larger disks. Smaller values, a different firmware and a different number of cores per socket need the virtual machine to be powered off. Adding or removing devices while it runs needs a host with hot-plug support; without it the change is refused until the virtual machine is powered off.

Related tasks

• Create a virtual machine
• Power operations
• Edit hardware
• Storage concepts