pyrecracker 0.5.1__tar.gz

pyrecracker-0.5.1/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: pyrecracker
+Version: 0.5.1
+Summary: Python module for creating and controlling micro VMs with Firecracker
+License-Expression: MIT
+Author: Jake Jongewaard
+Author-email: jjongewaard1@gmail.com
+Requires-Python: >=3.12
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: requests-unixsocket (>=0.4.1,<0.5.0)
+Description-Content-Type: text/markdown
+
+# Pyrecracker
+Pyrcracker is a python module that can be used to create, run, and manage the lifecycle of micro virtual machines using Firecracker.  Pyrecracker gives a simple to use API for VM management that can be used from within python based applications.
+
+## Supported Operating Systems
+The following are the operating systems that pyrecracker has been tested on:
+- Ubuntu 24.04 LTS (with nested virtualization enabled)
+
+## Installing
+If using pip, pyrecracker can be installed with:
+
+```
+pip install pyrecracker
+```
+
+If using poetry, pyrecracker can be installed with:
+
+```
+poetry add pyrecracker
+```
+
+## Building
+This project uses poetry for building and packaging.  Pyrecracker can be built with the following command:
+
+```
+poetry build
+```
+
+This will generate the project's tar.gz and .whl files in the `./dist` directory.
+
+## Testing
+Unit tests can be run with the following:
+
+```
+poetry run pytest
+```
+
+Examples on using pyrecracker can be found in the `./examples` directory.

pyrecracker-0.5.1/README.md

@@ -0,0 +1,37 @@
+# Pyrecracker
+Pyrcracker is a python module that can be used to create, run, and manage the lifecycle of micro virtual machines using Firecracker.  Pyrecracker gives a simple to use API for VM management that can be used from within python based applications.
+
+## Supported Operating Systems
+The following are the operating systems that pyrecracker has been tested on:
+- Ubuntu 24.04 LTS (with nested virtualization enabled)
+
+## Installing
+If using pip, pyrecracker can be installed with:
+
+```
+pip install pyrecracker
+```
+
+If using poetry, pyrecracker can be installed with:
+
+```
+poetry add pyrecracker
+```
+
+## Building
+This project uses poetry for building and packaging.  Pyrecracker can be built with the following command:
+
+```
+poetry build
+```
+
+This will generate the project's tar.gz and .whl files in the `./dist` directory.
+
+## Testing
+Unit tests can be run with the following:
+
+```
+poetry run pytest
+```
+
+Examples on using pyrecracker can be found in the `./examples` directory.

pyrecracker-0.5.1/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "pyrecracker"
+version = "0.5.1"
+description = "Python module for creating and controlling micro VMs with Firecracker"
+authors = [
+    {name = "Jake Jongewaard",email = "jjongewaard1@gmail.com"}
+]
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "requests-unixsocket (>=0.4.1,<0.5.0)"
+]
+license = "MIT"
+
+[tool.poetry]
+packages = [{include = "pyrecracker", from = "src"}]
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[dependency-groups]
+dev = [
+    "pytest (>=9.0.2,<10.0.0)",
+    "pytest-mock (>=3.15.1,<4.0.0)"
+]

pyrecracker-0.5.1/src/pyrecracker/client.py

@@ -0,0 +1,175 @@
+import logging
+from dataclasses import asdict
+from typing import Any
+
+import requests_unixsocket
+from requests.exceptions import HTTPError
+
+from pyrecracker.client_types import (
+    VM,
+    MachineConfiguration, 
+    BootSource, 
+    Drive, 
+    InstanceActionInfo,
+    NetworkInterface,
+    SnapshotCreateParams,
+    SnapshotLoadParams
+)
+
+
+log = logging.getLogger(__name__)
+
+
+class FirecrackerClient:
+    """
+    A client for interacting with the Firecracker HTTP API via a Unix socket.
+    """
+
+    def __init__(self, socket_path: str) -> None:
+        """
+        Initialize the FirecrackerClient with the path to the Unix socket.
+
+        Args:
+            socket_path (str): The path to the Firecracker API Unix socket.
+        """
+        self.__session = requests_unixsocket.Session()
+        self.__socket_path = socket_path
+        self.__socket_url = f"http+unix://{socket_path.replace('/', '%2F')}"
+
+    @property
+    def socket_path(self) -> str:
+        """
+        Get the socket path for the Firecracker API.
+        """
+        return self.__socket_path
+
+    def __put(self, endpoint: str, data: dict) -> None:
+        """
+        Helper method to send a PUT request to the Firecracker API.
+
+        Args:
+            endpoint (str): The API endpoint to which the request should be sent.
+            data (dict): The JSON data to be included in the PUT request.
+        Raises:
+            HTTPError: If the PUT request receives with an HTTP error response.
+        """
+        try:
+            response = self.__session.put(f"{self.__socket_url}/{endpoint}", json=data)
+            response.raise_for_status()
+        except HTTPError as err:
+            log.error(f"Error occurred while sending PUT request to {endpoint}: {err}")
+            raise
+
+    def __patch(self, endpoint: str, data: dict) -> None:
+        """
+        Helper method to send a PATCH request to the Firecracker API.
+
+        Args:
+            endpoint (str): The API endpoint to which the request should be sent.
+            data (dict): The JSON data to be included in the PATCH request.
+        Raises:
+            HTTPError: If the PATCH request receives with an HTTP error response.
+        """
+        try:
+            response = self.__session.patch(f"{self.__socket_url}/{endpoint}", json=data)
+            response.raise_for_status()
+        except HTTPError as err:
+            log.error(f"Error occurred while sending PATCH request to {endpoint}: {err}")
+            raise
+
+    def __body_to_dict(self, body: Any) -> dict:
+        """
+        Helper method to convert a dataclass instance to a dictionary.
+
+        Args:
+            body (Any): The dataclass instance to be converted.
+
+        Returns:
+            dict: The dictionary representation of the dataclass instance.
+        """
+        return asdict(
+            body, 
+            dict_factory=lambda x: {k: v for (k, v) in x if v is not None}
+        )
+
+    def put_machine_config(self, machine_config: MachineConfiguration) -> None:
+        """
+        Configure the machine with the specified number of vCPUs and memory size.
+
+        Args:
+            vcpu_count (int): The number of virtual CPUs to allocate to the machine.
+            mem_size_mib (int): The amount of memory in MiB to allocate to the machine.
+            ht_enabled (bool): Whether to enable hyper-threading for the machine.
+        """
+        data = self.__body_to_dict(machine_config)
+        self.__put("machine-config", data)
+
+    def put_boot_source(self, boot_source: BootSource) -> None:
+        """
+        Configure the linux kernel boot source for the machine.
+
+        Args:
+            kernel_image_path (str): The path to the kernel image to be used as the boot source.
+            boot_args (str): The kernel command line arguments to be passed to the kernel on boot.
+        """
+        data = self.__body_to_dict(boot_source)
+        self.__put("boot-source", data)
+
+    def put_drives(self, drive: Drive) -> None:
+        """
+        Configure a root filesystem drive for the machine.
+
+        Args:
+            drive_id (str): The identifier inside firecracker for the drive to be configured.
+            path_on_host (str): The path on the host where the drive's backing file is located.
+            is_root_device (str): True if disk should be the root file drive else False
+            is_read_only (bool): Whether the drive should be configured as read-only.
+        """
+        data = self.__body_to_dict(drive)
+        self.__put(f"drives/{drive.drive_id}", data)
+
+    def put_network_interfaces(self, network_interface: NetworkInterface) -> None:
+        """
+        Configure a network interface for the machine.
+
+        Args:
+            network_interface (NetworkInterface): The network interface configuration.
+        """
+        data = self.__body_to_dict(network_interface)
+        self.__put(f"network-interfaces/{network_interface.iface_id}", data)   
+
+    def put_actions(self, instance_action_info: InstanceActionInfo) -> None:
+        """
+        Send an action request to the Firecracker API.
+
+        Args:
+            action_type (str): The type of action to be performed. Valid values are "InstanceStart" and "InstanceStop".
+        """
+        self.__put("actions", self.__body_to_dict(instance_action_info))
+
+    def patch_vm(self, vm: VM) -> None:
+        """
+        Configure the VM with the specified configuration.
+
+        Args:
+            vm (VM): The VM configuration to be applied.
+        """
+        self.__patch("vm", self.__body_to_dict(vm))
+
+    def put_snapshot_create(self, snapshot_create_params: SnapshotCreateParams) -> None:
+        """
+        Create a snapshot of the VM.
+
+        Args:
+            snapshot_create_params (SnapshotCreateParams): The parameters for creating the snapshot.
+        """
+        self.__put("snapshot/create", self.__body_to_dict(snapshot_create_params))
+
+    def put_snapshot_load(self, snapshot_load_params: SnapshotLoadParams) -> None:
+        """
+        Load a snapshot of the VM.
+
+        Args:
+            snapshot_load_params (SnapshotLoadParams): The parameters for loading the snapshot.
+        """
+        self.__put("snapshot/load", self.__body_to_dict(snapshot_load_params))

pyrecracker-0.5.1/src/pyrecracker/client_types.py

@@ -0,0 +1,218 @@
+from typing import Optional
+from dataclasses import dataclass
+from enum import StrEnum
+
+
+@dataclass
+class BootSource:
+    """
+    Represents the request body for the Firecracker BootSource API.
+    Maps 1-to-1 with the BootSource definition in the Firecracker Swagger spec.
+    
+    Attributes:
+        kernel_image_path (str): Path to the kernel image on the host.
+        boot_args (Optional[str]): Kernel boot arguments.
+        initrd_path (Optional[str]): Path to the initrd image on the host.
+    """
+    kernel_image_path: str
+    boot_args: Optional[str] = None
+    initrd_path: Optional[str] = None
+
+
+class HugePages(StrEnum):
+    NONE = "None"
+    TWO_MIB = "2M"
+
+
+@dataclass
+class MachineConfiguration:
+    """
+    Represents the request body for the Firecracker Machine Configuration API.
+    Maps 1-to-1 with the MachineConfiguration definition in the Firecracker Swagger spec.
+    
+    Attributes:
+        mem_size_mib (int): Memory size in MiB.
+        vcpu_count (int): Number of vCPUs (1-32).
+        smt (Optional[bool]): Simultaneous multithreading enabled.
+        track_dirty_pages (Optional[bool]): Track dirty pages for live migration.
+        huge_pages (Optional[HugePages]): Use huge pages.
+    """
+    mem_size_mib: int
+    vcpu_count: int
+    #cpu_template: Optional[CPUTemplate] = None will have to be a ref to another dataclass
+    smt: Optional[bool] = None
+    track_dirty_pages: Optional[bool] = None
+    huge_pages: Optional[HugePages] = None
+
+    def __post__init__(self):
+        if self.vcpu_count < 1 or self.vcpu_count > 32:
+            raise ValueError("vcpu_count must be between 1 and 32")
+        if self.huge_pages is not None:
+            if self.huge_pages not in [HugePages.NONE, HugePages.TWO_MIB]:
+                raise ValueError(
+                    "MachineConfiguration.huge_pages must be either"
+                    f" '{HugePages.NONE}' or '{HugePages.TWO_MIB}'"
+                )
+
+
+class CacheType(StrEnum):
+    UNSAFE = "Unsafe"
+    WRITEBACK = "Writeback"
+
+
+class IOEngine(StrEnum):
+    SYNC = "Sync"
+    ASYNC = "Async"
+
+
+@dataclass
+class Drive:
+    """
+    Represents the request body for the Firecracker Drive API.
+    Maps 1-to-1 with the Drive definition in the Firecracker Swagger spec.
+    
+    Attributes:
+        drive_id (str): Unique identifier for the drive.
+        is_root_device (bool): Whether this drive is the root device.
+        partuuid (Optional[str]): Partition UUID.
+        cache_type (Optional[CacheType]): Cache type.
+        is_read_only (Optional[bool]): If the drive is read-only.
+        path_on_host (Optional[str]): Path to the drive on the host.
+        io_engine (Optional[IOEngine]): IO engine.
+        socket (Optional[str]): Path to the drive's socket.
+    """
+    drive_id: str
+    is_root_device: bool
+    partuuid: Optional[str] = None
+    cache_type: Optional[CacheType] = None
+    is_read_only: Optional[bool] = None
+    path_on_host: Optional[str] = None
+    #rate_limiter: Optional[RateLimiter] = None This needs to be a ref to another dataclass
+    io_engine: Optional[IOEngine] = None
+    socket: Optional[str] = None
+
+    def __post__init__(self):
+        if self.cache_type is not None:
+            if self.cache_type not in [CacheType.UNSAFE, CacheType.WRITEBACK]:
+                raise ValueError(
+                    f"DriveBody.cache_type must be either '{CacheType.UNSAFE}' or '{CacheType.WRITEBACK}'"
+                )
+        if self.io_engine is not None:
+            if self.io_engine not in [IOEngine.SYNC, IOEngine.ASYNC]:
+                raise ValueError(
+                    f"DriveBody.io_engine must be either '{IOEngine.SYNC}' or '{IOEngine.ASYNC}'"
+                )
+
+
+class ActionType(StrEnum):
+    FLUSH_METRICS = "FlushMetrics"
+    INSTANCE_START = "InstanceStart"
+    SEND_CTRL_ALT_DEL = "SendCtrlAltDel"
+
+
+@dataclass
+class InstanceActionInfo:
+    """
+    Represents the request body for the Firecracker Instance Action API.
+    Maps 1-to-1 with the InstanceActionInfo definition in the Firecracker Swagger spec.
+    
+    Attributes:
+        action_type (ActionType): Action type to execute.
+    """
+    action_type: ActionType
+
+    def __post__init__(self):
+        if self.action_type not in [
+            ActionType.FLUSH_METRICS,
+            ActionType.INSTANCE_START,
+            ActionType.SEND_CTRL_ALT_DEL
+        ]:
+            raise ValueError(
+                f"InstanceActionInfo.action_type must be one of '{ActionType.FLUSH_METRICS}', "
+                f"'{ActionType.INSTANCE_START}', or '{ActionType.SEND_CTRL_ALT_DEL}'"
+            )
+        
+
+@dataclass
+class NetworkInterface:
+    """
+    Represents the request body for the Firecracker Network Interface API.
+
+    Attributes:
+        host_dev_name (str): Host level path for the guest network interface (e.g. tap0).
+        iface_id (str): Unique identifier for the network interface within Firecracker.
+        guest_mac (Optional[str]): MAC address to be assigned to the guest network interface.
+    """
+    host_dev_name: str
+    iface_id: str
+    guest_mac: Optional[str] = None
+    #rx_rate_limiter: Optional[RateLimiter] = None This needs to be a ref
+    #tx_rate_limiter: Optional[RateLimiter] = None This needs to be a ref
+
+
+class VMState(StrEnum):
+    PAUSED = "Paused"
+    RESUMED = "Resumed"
+
+
+@dataclass
+class VM:
+    """
+    Represents the state of a Firecracker microVM.
+
+    Attributes:
+        state (VMState): The current state of the microVM
+    """
+    state: VMState
+
+    def __post__init__(self):
+        if self.state not in [VMState.PAUSED, VMState.RESUMED]:
+            raise ValueError(
+                f"VM.state must be one of '{VMState.PAUSED}' or '{VMState.RESUMED}'"
+            )
+
+
+class SnapshotType(StrEnum):
+    FULL = "Full"
+    DIFF = "Diff"
+
+
+@dataclass
+class SnapshotCreateParams:
+    """
+    Represents the request body for the Firecracker Create Snapshot API.
+
+    Attributes:
+        mem_file_path (str): The path on the host where the memory file will be stored.
+        snapshot_path (str): The path on the host where the snapshot will be stored.
+        snapshot_type (Optional[SnapshotType]): The type of snapshot to create ('Full' or 'Diff').
+    """
+    snapshot_path: str
+    mem_file_path: str
+    snapshot_type: Optional[SnapshotType] = None
+
+    def __post__init__(self):
+        if self.snapshot_type not in [SnapshotType.FULL, SnapshotType.DIFF]:
+            raise ValueError(
+                f"SnapshotCreateParams.snapshot_type must be either '{SnapshotType.FULL}' or '{SnapshotType.DIFF}'"
+            )
+
+
+@dataclass
+class SnapshotLoadParams:
+    """
+    Represents the request body for the Firecracker Load Snapshot API.
+
+    Attributes:
+        snapshot_path (str): Path to the file that contains the microVM state to be loaded.
+        track_dirty_pages (Optional[bool]): Whether to track dirty pages after loading the snapshot.
+        mem_file_path (Optional[str]): The path on the host that contains the guest memory to be loaded.
+        resume_vm (Optional[bool]): Whether to resume the VM immediately after loading the snapshot.
+    """
+    snapshot_path: str
+    track_dirty_pages: Optional[bool] = None
+    mem_file_path: Optional[str] = None
+    # mem_backend: Optional[MemoryBackend] = None This needs to be a ref to another dataclass
+    resume_vm: Optional[bool] = None
+    # network_overrides: Optional[List[NetworkOverride]] = None This needs to be a ref to a list of dataclasses
+    # vsock_override: Optional[VsockOverride] = None This needs to be a ref to another dataclass

pyrecracker-0.5.1/src/pyrecracker/cmd.py

@@ -0,0 +1,132 @@
+import subprocess
+from functools import singledispatchmethod
+from typing import Optional, Self
+from pathlib import Path
+
+
+class CommandError(Exception):
+    """Custom exception for command execution errors."""
+    pass
+
+
+class Command:
+    """
+    A class to build and execute shell commands. This class supports
+    adding arguments by chaining calls to `add_arg` or `add_args`.
+
+    Attributes:
+        __name (str): The base command to execute.
+        __command_list (list[str]): The list of command components to be executed.
+    """
+    def __init__(self, name: str, sudo: bool = False) -> None:
+        self.__name: str = name
+        self.__command_list: list[str] = ["sudo", self.__name] if sudo else [self.__name]
+
+    def __str__(self) -> str:
+        """
+        Returns the full command as a string.
+
+        Returns:
+            str: The full command string.
+        """
+        return " ".join(self.__command_list)
+    
+    def add_arg(self, arg: str) -> Self:
+        """
+        Adds a single argument to the command's command list.  This method
+        can be chained to add multiple arguments.
+
+        Returns:
+            Command: The Command instance with the added argument.
+        """
+        self.__command_list.append(arg)
+        return self
+
+    @singledispatchmethod
+    def add_args(self, args) -> Self:
+        """
+        Adds multiple arguments to the command's command list. This method 
+        can be chained to add multiple arguments.
+        """
+        raise NotImplementedError("Unsupported type for add_args")
+    
+    @add_args.register
+    def _(self, args: list) -> Self:
+        """
+        Adds a list of arguments to the command's command list. This method 
+        can be chained to add multiple arguments.
+
+        Args: 
+            args (list[str]): A list of arguments to add to the command.
+        Returns:
+            Command: The Command instance with the added arguments.
+        """
+        self.__command_list.extend(args)
+        return self
+
+    @add_args.register
+    def _(self, args: str) -> Self:
+        """
+        Adds a string of arguments to the command's command list. The string 
+        is split into individual arguments based on whitespace. This method can 
+        be chained to add multiple arguments.
+
+        Args:
+            args (str): A string of arguments to add to the command.
+        Returns:
+            Command: The Command instance with the added arguments.
+        """
+        args_list = args.split()
+        self.__command_list.extend(args_list)
+        return self
+    
+    def run(self) -> None:
+        """
+        Executes the command using subprocess.run.
+
+        Raises:
+            RuntimeError: If the command execution fails, a RuntimeError is raised with the command error code.
+        """
+        try:
+            result = subprocess.run(self.__command_list, check=True)
+            if result.returncode != 0:
+                error_message = f"Command '{str(self)}' failed with exit code {result.returncode} and output: {result.stdout}"
+                raise CommandError(error_message)
+        except subprocess.CalledProcessError as e:
+            error_message = f"Command '{str(self)}' failed with exit code {e.returncode}"
+            raise CommandError(error_message) from e
+
+    def popen(self, log_file_path: Optional[str] = None) -> subprocess.Popen:
+        """
+        Executes the command by spawning a background process using subprocess.Popen.
+        Returns the Popen object to allow the caller to maintain a reference to the process.
+
+        Returns:
+            subprocess.Popen: The Popen object representing the spawned process.
+            log_file_path (str): The path to the log file where the command's 
+                output will be written.
+
+        Raises:
+            RuntimeError: If the command execution fails, a RuntimeError is raised with the command error code.
+        """
+        try:
+            if log_file_path is None:
+                process = subprocess.Popen(
+                    self.__command_list, 
+                    stdin=subprocess.DEVNULL,
+                    stdout=subprocess.DEVNULL
+                )
+                return process
+            path = Path(log_file_path)
+            path.parent.mkdir(parents=True, exist_ok=True)
+            with open(path, "w") as log_file:
+                process = subprocess.Popen(
+                    self.__command_list, 
+                    stdin=subprocess.DEVNULL,
+                    stdout=log_file,
+                    stderr=log_file
+                )
+                return process
+        except subprocess.CalledProcessError as e:
+            error_message = f"Command '{str(self)}' failed with exit code {e.returncode}"
+            raise CommandError(error_message) from e