Virtual Machine Orchestration

Cockpit provides a centralized management console to orchestrate the lifecycle of virtual machines (VMs) running across physical Vapor hosts. Administrators can monitor performance, provision new workloads, manage virtual device attachments, execute power actions, and coordinate backup policies from a single control pane.

---

1. Centralized VM Inventory

Cockpit consolidates virtual machines across all connected Vapor hosts into a single inventory.

Key Features

• Unified Inventory: View, search, and organize virtual machines into logical groupings regardless of the physical host they reside on.
• Resource and Metrics Panel: Displays real-time charts of CPU utilization, memory allocation, network traffic (IP/MAC addresses), and disk read/write throughput.
• Console Access: Open direct interactive console sessions (VNC or SPICE protocol) in the web browser. This acts as a virtual monitor and keyboard for direct operating system access and troubleshooting.

---

2. Virtual Machine Provisioning Wizard

The provisioning wizard guides administrators through creating virtual machines and templates. Its steps adapt to the creation type chosen first: a from-scratch build exposes the full set of hardware steps, while clone, deploy, and convert flows collapse to only the fields they need.

Creation types

Type	What it does
Create a New Virtual Machine	Build a VM from a blank slate — placement, OS, firmware, storage, network, PCI, and cloud-init.
Deploy from Template	Instantiate a new VM from an existing template, choosing its name and target storage.
Clone an Existing VM	Create an independent copy of a VM's configuration and disks.
Clone a VM to Template	Copy a VM and register the copy as a reusable template.
Convert Template to VM	In-place conversion of a template back into a runnable VM.
Clone Template to Template	Create a copy of an existing template.
Convert VM to Template	In-place, destructive conversion of a VM into a template.

Steps for a from-scratch build

1. Creation Type: Pick one of the modes above.

2. Placement Target: Choose the datacenter, cluster, and host. Cockpit shows each host's free CPU and RAM to assist with scheduling.

3. Identity & OS: Set the VM name; the initial and maximum vCPUs and Memory (MiB) — the maximum values reserve headroom for CPU/memory hot-plug; autostart; firmware (UEFI, Secure Boot — requires q35 on x86_64, and TPM); and the guest OS family (Linux, Windows, FreeBSD, Other) and variant, which applies libvirt driver presets.

4. Storage: Add one or more disks. Each disk has an action:

   • Create New — allocate a new disk (qcow2, raw, or vmdk) of a given size on a datastore.
   • Clone From — copy an existing volume.
   • Attach Existing — attach a volume already present on a datastore.
   • Direct Raw Device (DRM) — map a raw host block device (raw format).

   You also choose the disk bus (VirtIO, SCSI, IDE, or SATA), and can Add ISO/CD-ROM media.

5. Network: Add network interfaces. For each, choose the type (Network, Bridge, Direct/macvtap, or User mode), the source virtual switch (a standard bridge or a cluster distributed network), the driver model (VirtIO, e1000, rtl8139, or vmxnet3), and optionally a fixed MAC address.

6. Advanced: Attach PCI passthrough devices such as GPUs or network controllers. Each entry maps a host PCI address, with optional guest address, ROM file, multi-function, and primary-GPU settings.

7. Cloud-Init: Inject cloud-init customizations across five tabs — User Data, Metadata, Network Data, SSH Keys, and Packages — for automatic post-boot provisioning.

8. Review and Create: Verify the configuration and dispatch the asynchronous create request to the target host. An optional Power on VM after creation toggle boots the guest as soon as it is built.

Clone, deploy, and convert flows show a reduced set of steps — typically source selection, a new name, and (where disks are copied) a target storage pool.

---

3. Lifecycle and Power Operations

Cockpit exposes the following power controls for a VM:

• Power On: Boots the guest operating system.
• Pause: Suspends execution, freezing the VM's active CPU and memory state in place.
• Resume: Restores CPU execution and memory state for a paused VM.
• Restart Guest OS: Requests an in-guest (ACPI) reboot, letting the operating system restart cleanly.
• Reset (Hard): Immediately resets the VM — the equivalent of a reset button, with no guest cooperation.
• Power Off (Hard): Immediately powers off the VM (similar to disconnecting power), terminating the domain without a graceful guest shutdown.

Each action is offered only when it applies to the VM's current state — for example, Resume appears only for a paused VM, and Restart Guest OS / Reset (Hard) only while it is running.

---

4. Hardware and Spec Modification

The Edit Settings dialog changes a VM's virtual hardware. It is organized into Hardware, Options, and Advanced Parameters tabs, and applies to both running and stopped VMs (some changes take effect on next boot).

• Resources & CPU: Adjust vCPUs and Memory, the CPU topology (sockets / dies / cores / threads), and the CPU model. Max vCPUs and Max Memory ceilings — set above the current values — reserve headroom for CPU and memory hot-plug.
• Device Management:
  • Hard Disks: Add or detach virtual disks. New disks can be created, cloned, attached, or mapped as a direct raw device, with a selectable bus and format; CD-ROM/ISO media is supported.
  • Network Adapters: Add or remove network interfaces (Network, Bridge, Direct/macvtap, or User mode; VirtIO / e1000 / rtl8139 / vmxnet3 models).
  • PCI Device Passthrough: Map host PCI devices (e.g., GPUs, network controllers) directly to the VM, with ROM file, multi-function, and primary-GPU options.
• Firmware & Options: Toggle UEFI, Secure Boot, and TPM, set architecture and machine type, and control autostart with host.
• Advanced Parameters: A read-only view of the VM's current domain definition (autostart and other libvirt parameters), for reference and troubleshooting. This tab reflects the live configuration; it does not edit it.

---

5. Cloning and Template Management

Templates and cloning standardize VM configurations and speed up provisioning. All of these run from the provisioning wizard's creation-type step:

• VM Cloning: Creates an independent copy of a source VM's configuration and virtual disks. The wizard prompts for the source VM, the new VM name, and the target storage pool for disk duplication.
• Deploy from Template: Provisions a new VM from a template, choosing its name and destination storage.
• Clone VM to Template: Copies a source VM and registers the copy as a read-only template in the VMs and Templates inventory. The template dialog also captures an optional description and target storage pool.
• Clone Template to Template: Duplicates an existing template.
• Convert VM to Template: Permanently converts a VM into a template in place — a status transition that marks the VM as a template.
• Convert Template to VM: Reverts a template back into an independent virtual machine, restoring normal power-cycle and configuration-edit operations.

---

6. Deletion and Cleanup Options

When deleting a virtual machine, Cockpit exposes options to manage underlying resources:

• Metadata Deletion: Removes the VM registration from Cockpit and the host hypervisor configuration.
• Storage Cleanup: By default, deleting a VM keeps its virtual disks to prevent data loss. Administrators can toggle the remove_disks parameter (executing API DELETE /vms/:id?remove_disks=true) to delete all associated virtual disk volumes from their respective datastores.