"""VM Drive resource manager."""
from __future__ import annotations
import builtins
import logging
from typing import TYPE_CHECKING, Any, cast
from pyvergeos.filters import combine_filters, quote_value
from pyvergeos.resources.base import ResourceManager, ResourceObject
if TYPE_CHECKING:
from pyvergeos.client import VergeClient
from pyvergeos.resources.drive_stats import MachineDriveStatsManager
from pyvergeos.resources.vms import VM
logger = logging.getLogger(__name__)
# Default fields for drives
DRIVE_DEFAULT_FIELDS = [
"$key",
"name",
"orderid",
"interface",
"media",
"description",
"enabled",
"serial",
"preferred_tier",
"readonly",
"ms_2023_kek_applied",
"disksize",
"used_bytes",
"media_source",
"machine",
"status#status as status",
"status#display(status) as status_display",
"media_source#name as media_file",
"media_source#allocated_bytes as allocated_bytes",
]
# Interface display names
INTERFACE_DISPLAY_MAP = {
"virtio": "Virtio (Legacy)",
"ide": "IDE",
"ahci": "SATA (AHCI)",
"nvme": "NVMe",
"virtio-scsi": "Virtio-SCSI",
"virtio-scsi-dedicated": "Virtio-SCSI (Dedicated)",
"lsi53c895a": "LSI SCSI",
"megasas": "LSI MegaRAID SAS",
"megasas-gen2": "LSI MegaRAID SAS 2",
"usb": "USB",
}
# Media display names
MEDIA_DISPLAY_MAP = {
"cdrom": "CD-ROM",
"disk": "Disk",
"efidisk": "EFI Disk",
"import": "Import Disk",
"9p": "Pass-Through (9P)",
"dir": "Pass-Through (Directory)",
"clone": "Clone Disk",
"nonpersistent": "Non-Persistent",
}
def _supports_ms_2023_kek(os_version: str | None) -> bool:
"""Return whether a VergeOS version exposes the Microsoft 2023 KEK field."""
parts = (os_version or "").split(".")
if len(parts) < 2:
return False
try:
return (int(parts[0]), int(parts[1])) >= (26, 1)
except ValueError:
return False
[docs]
class Drive(ResourceObject):
"""VM Drive resource object."""
@property
def size_gb(self) -> float:
"""Get disk size in GB."""
size_bytes = self.get("disksize") or self.get("allocated_bytes") or 0
return round(size_bytes / (1024**3), 2)
@property
def used_gb(self) -> float:
"""Get used space in GB."""
used_bytes = self.get("used_bytes") or 0
return round(used_bytes / (1024**3), 2)
@property
def interface_display(self) -> str:
"""Get friendly interface name."""
interface = self.get("interface", "")
return INTERFACE_DISPLAY_MAP.get(interface, str(interface))
@property
def media_display(self) -> str:
"""Get friendly media type name."""
media = self.get("media", "")
return MEDIA_DISPLAY_MAP.get(media, str(media))
@property
def is_enabled(self) -> bool:
"""Check if drive is enabled."""
return bool(self.get("enabled", True))
@property
def is_readonly(self) -> bool:
"""Check if drive is read-only."""
return bool(self.get("readonly", False))
@property
def ms_2023_kek_applied(self) -> bool:
"""Check if the Microsoft 2023 Secure Boot keys have been applied."""
return bool(self.get("ms_2023_kek_applied", False))
@property
def drive_stats(self) -> MachineDriveStatsManager:
"""Per-drive IO statistics, scoped to this drive (issue #128).
Addresses the stats by a filter on ``parent_drive``, avoiding the
path-key aliasing that reports another drive's counters.
Returns:
MachineDriveStatsManager scoped to this drive.
Example:
>>> stats = drive.drive_stats.get()
>>> print("booted" if stats.has_booted else "not booted")
"""
from pyvergeos.resources.drive_stats import MachineDriveStatsManager
return MachineDriveStatsManager(self._manager._client, self.key)
[docs]
def apply_universal_vars(self) -> dict[str, Any] | None:
"""Apply the Microsoft 2023 Secure Boot keys to this EFI disk.
The owning VM must be offline with Secure Boot enabled. VergeOS also
requires this drive to use the ``efidisk`` media type.
Returns:
Action response, which may include task information.
"""
manager = cast("DriveManager", self._manager)
return manager.apply_universal_vars(self.key)
[docs]
class DriveManager(ResourceManager[Drive]):
"""Manager for VM Drive operations.
This manager is accessed through a VM object's drives property.
"""
_endpoint = "machine_drives"
_default_fields = DRIVE_DEFAULT_FIELDS
[docs]
def __init__(self, client: VergeClient, vm: VM) -> None:
super().__init__(client)
self._vm = vm
self._default_fields = [
field
for field in DRIVE_DEFAULT_FIELDS
if field != "ms_2023_kek_applied" or _supports_ms_2023_kek(client.os_version)
]
@property
def machine_key(self) -> int:
"""Get the machine key for this VM."""
machine = self._vm.get("machine")
if machine is None:
raise ValueError("VM has no machine key")
return int(machine)
def _to_model(self, data: dict[str, Any]) -> Drive:
return Drive(data, self)
def _scope_resource(self) -> str:
return "Drive"
def _scope_bindings(self) -> list[tuple[str, Any]]:
"""Drives are owned by the VM's machine (#168)."""
return [("machine", self.machine_key)]
[docs]
def list( # type: ignore[override] # noqa: A003
self,
filter: str | None = None, # noqa: A002
fields: str | list[str] | None = None,
media: str | None = None,
limit: int | None = None,
offset: int | None = None,
**kwargs: Any,
) -> list[Drive]:
"""List drives for this VM.
Args:
filter: Additional OData filter string.
fields: List of fields to return.
media: Filter by media type (disk, cdrom, efidisk).
**kwargs: Additional filter arguments.
Returns:
List of Drive objects.
"""
# Use default fields if not specified
if fields is None:
fields = self._default_fields
# Build filter for this VM's machine
machine_filter = f"machine eq {self.machine_key}"
if media:
machine_filter = f"{machine_filter} and media eq {quote_value(media)}"
if filter:
machine_filter = f"{machine_filter} and ({filter})"
# Merge shorthand kwargs instead of silently dropping them (issue #96)
combined_filter = combine_filters(machine_filter, kwargs)
params: dict[str, Any] = {
"filter": combined_filter,
"fields": self._projection(fields),
"sort": "+orderid",
}
if limit is not None:
params["limit"] = limit
if offset is not None:
params["offset"] = offset
response = self._client._request("GET", self._endpoint, params=params)
if response is None:
return []
if not isinstance(response, list):
return [self._to_model(response)]
return [self._to_model(item) for item in response]
[docs]
def get(
self,
key: int | None = None,
*,
name: str | None = None,
fields: str | builtins.list[str] | None = None,
) -> Drive:
"""Get a drive by key or name.
Args:
key: Drive $key (ID).
name: Drive name.
fields: List of fields to return.
Returns:
Drive object.
Raises:
NotFoundError: If the drive does not exist or belongs to another VM.
ValueError: If neither key nor name provided.
"""
if fields is None:
fields = self._default_fields
if key is not None:
from pyvergeos.exceptions import NotFoundError
# list() is filtered by machine; a key is not. Ask for machine even
# when the caller narrowed fields, then refuse another VM's row (#168).
selected = self._with_scope_fields(fields)
params: dict[str, Any] = {"fields": self._projection(selected)}
response = self._client._request("GET", f"{self._endpoint}/{key}", params=params)
if response is None:
raise NotFoundError(f"Drive {key} not found")
if not isinstance(response, dict):
raise NotFoundError(f"Drive {key} returned invalid response")
self._assert_row_in_scope(key, response)
return self._to_model(response)
if name is not None:
drives = self.list(filter=f"name eq {quote_value(name)}", fields=fields)
if not drives:
from pyvergeos.exceptions import NotFoundError
raise NotFoundError(f"Drive with name '{name}' not found")
return drives[0]
raise ValueError("Either key or name must be provided")
[docs]
def create( # type: ignore[override]
self,
size_gb: int | None = None,
name: str | None = None,
interface: str = "virtio-scsi",
media: str = "disk",
tier: int | None = None,
description: str = "",
readonly: bool = False,
enabled: bool = True,
media_source: int | str | None = None,
) -> Drive:
"""Create a new drive for this VM.
Args:
size_gb: Disk size in GB (required for disk media).
name: Drive name (optional, auto-generated if not provided).
interface: Drive interface type (virtio-scsi, nvme, ahci, ide, etc.).
media: Media type (disk, cdrom, efidisk).
tier: Preferred storage tier (1-5).
description: Drive description.
readonly: Make drive read-only.
enabled: Enable drive (default True).
media_source: File key (int) or name (str) for CD-ROM media source.
Used to attach ISO or other media files.
Returns:
Created Drive object.
Raises:
ValueError: If size_gb not provided for disk media.
ValueError: If media_source file not found (when passed as string).
"""
if media == "disk" and size_gb is None:
raise ValueError("size_gb is required for disk media")
if media == "efidisk" and size_gb is not None:
# The platform templates EFI vars stores at a fixed size
# (~528 KiB). A caller-sized efidisk is created as a raw volume
# without the OVMF vars layout: the VM cannot persist UEFI
# variables and apply_universal_vars() fails with
# 'Operation not permitted'. Verified on VergeOS 26.1.8.
raise ValueError(
"size_gb is not applicable to efidisk media; omit it so the "
"platform creates a templated EFI vars store"
)
body: dict[str, Any] = {
"machine": self.machine_key,
"interface": interface,
"media": media,
"enabled": enabled,
}
if name:
body["name"] = name
if size_gb is not None:
body["disksize"] = int(size_gb) * (1024**3) # Convert to bytes
if tier is not None:
body["preferred_tier"] = str(tier)
if description:
body["description"] = description
if readonly:
body["readonly"] = True
# Resolve media_source by name if string provided
if media_source is not None:
if isinstance(media_source, str):
# Look up file by name
response = self._client._request(
"GET",
"files",
params={
"filter": f"name eq {quote_value(media_source)}",
"fields": "$key,name",
},
)
if not response:
raise ValueError(f"Media file '{media_source}' not found")
if isinstance(response, list):
if not response:
raise ValueError(f"Media file '{media_source}' not found")
media_source = response[0].get("$key")
else:
media_source = response.get("$key")
body["media_source"] = int(media_source) # type: ignore[arg-type]
response = self._client._request("POST", self._endpoint, json_data=body)
if response is None:
raise ValueError("No response from create operation")
if not isinstance(response, dict):
raise ValueError("Create operation returned invalid response")
# Fetch the full drive data with all fields
drive = self._to_model_unprojected(response)
return self.get(drive.key)
[docs]
def delete(self, key: int) -> None:
"""Delete a drive belonging to this VM.
Args:
key: Drive $key (ID).
Raises:
NotFoundError: If the drive does not exist or belongs to another VM.
Note:
VM should typically be powered off before removing drives.
"""
self._ensure_in_scope(key)
self._client._request("DELETE", f"{self._endpoint}/{key}")
[docs]
def update(self, key: int, **kwargs: Any) -> Drive:
"""Update a drive.
Args:
key: Drive $key (ID).
**kwargs: Fields to update. ``tier`` is accepted as an alias for
the API's ``preferred_tier`` field and is translated the same
way ``create()`` translates it. Passing the raw ``tier`` name
to the API is silently ignored by VergeOS, so it is never
sent as-is.
Returns:
Updated Drive object.
Raises:
NotFoundError: If the drive does not exist or belongs to another VM.
"""
self._ensure_in_scope(key)
kwargs = self._prepare_write_fields(kwargs)
response = self._client._request("PUT", f"{self._endpoint}/{key}", json_data=kwargs)
if response is None:
return self.get(key)
if not isinstance(response, dict):
return self.get(key)
return self._to_model_unprojected(response)
def _prepare_write_fields(self, fields: dict[str, Any]) -> dict[str, Any]:
"""Translate the ``tier`` alias to the API's ``preferred_tier`` field.
The API has no ``tier`` field on machine_drives; the writable field
is ``preferred_tier`` (a string). ``create()`` already translates
this, so apply the same alias on every write path instead of sending
a field the platform ignores with HTTP 200. Used by both ``update()``
and ``ResourceObject._save()`` so ``drive.tier = N; drive.save()``
works too. See issues #81 and #97.
"""
if "tier" not in fields:
return fields
fields = dict(fields)
tier = fields.pop("tier")
if tier is not None:
fields["preferred_tier"] = str(tier)
return fields
[docs]
def apply_universal_vars(self, key: int) -> dict[str, Any] | None:
"""Apply the Microsoft 2023 Secure Boot keys to an EFI disk.
Args:
key: Drive $key (ID).
Returns:
Action response, which may include task information.
Note:
The owning VM must be offline with Secure Boot enabled. VergeOS
validates those preconditions along with the EFI media type.
Verified against VergeOS 26.1.8: this path-form invocation
(``POST machine_drives/{key}/apply_universal_vars``) is required.
The generic ``?action=`` form returns HTTP 200 but is a silent
no-op - do not use :meth:`ResourceManager.action` for this.
The EFI disk must be a platform-templated vars store (create the
drive with ``media="efidisk"`` and no ``size_gb``); the patch
fails with ``Operation not permitted`` on raw fixed-size disks.
"""
response = self._client._request(
"POST", f"{self._endpoint}/{key}/apply_universal_vars", json_data={}
)
if isinstance(response, dict):
return response
return None
[docs]
def import_drive(
self,
file_key: int | None = None,
file_name: str | None = None,
name: str | None = None,
interface: str = "virtio-scsi",
tier: int | None = None,
preserve_drive_format: bool = False,
enabled: bool = True,
) -> Drive:
"""Import a disk image file as a new drive.
Creates a new drive by importing from a disk image file (VMDK, QCOW2,
VHD, VHDX, OVA, OVF, etc.). The file must already be uploaded to the
VergeOS media catalog.
This is the recommended way to import VMs from OVA/OVF/VMDK files:
1. Create a new VM with client.vms.create()
2. Import the disk(s) with vm.drives.import_drive()
Args:
file_key: The $key (ID) of the disk image file to import.
file_name: The name of the disk image file to import.
One of file_key or file_name is required.
name: Name for the new drive. If not specified, auto-generated.
interface: Drive interface type. Default is 'virtio-scsi'.
Valid values: virtio, ide, ahci, nvme, virtio-scsi,
virtio-scsi-dedicated.
tier: Preferred storage tier (1-5).
preserve_drive_format: Keep the original drive format instead of
converting to raw. Default is False.
enabled: Enable the drive. Default is True.
Returns:
Created Drive object.
Raises:
ValueError: If neither file_key nor file_name is provided.
ValueError: If file not found (when looking up by name).
Example:
>>> # Import a QCOW2 disk image
>>> vm = client.vms.get(name="NewServer")
>>> drive = vm.drives.import_drive(
... file_name="debian-12-generic-amd64.qcow2",
... interface="virtio-scsi",
... tier=1,
... )
>>> # Import from an OVA file's disk
>>> vm = client.vms.create(name="ImportedVM", cpu_cores=2, ram=4096)
>>> drive = vm.drives.import_drive(file_name="server-disk.vmdk")
Note:
Supported import formats: VMDK, QCOW2, VHD, VHDX, VDI, RAW, OVA, OVF.
The import process converts the disk to VergeOS format unless
preserve_drive_format is True.
"""
if file_key is None and file_name is None:
raise ValueError("Either file_key or file_name must be provided")
# Resolve file by name if needed
resolved_file_key = file_key
if file_key is None and file_name is not None:
response = self._client._request(
"GET",
"files",
params={"filter": f"name eq {quote_value(file_name)}", "fields": "$key,name"},
)
if not response:
raise ValueError(f"File '{file_name}' not found in media catalog")
if isinstance(response, list):
if not response:
raise ValueError(f"File '{file_name}' not found in media catalog")
resolved_file_key = response[0].get("$key")
else:
resolved_file_key = response.get("$key")
# Build request body for import drive
body: dict[str, Any] = {
"machine": self.machine_key,
"interface": interface,
"media": "import",
"media_source": int(resolved_file_key) if resolved_file_key else 0,
"enabled": enabled,
"preserve_drive_format": preserve_drive_format,
}
if name:
body["name"] = name
if tier is not None:
body["preferred_tier"] = str(tier)
response = self._client._request("POST", self._endpoint, json_data=body)
if response is None:
raise ValueError("No response from import operation")
if not isinstance(response, dict):
raise ValueError("Import operation returned invalid response")
# Fetch the full drive data with all fields
drive = self._to_model_unprojected(response)
return self.get(drive.key)