hysn-firecracker-python 1.0.3.post0__py3-none-any.whl

hysn_firecracker_python-1.0.3.post0.dist-info/METADATA

@@ -0,0 +1,246 @@
+Metadata-Version: 2.4
+Name: hysn-firecracker-python
+Version: 1.0.3.post0
+Summary: A Python client library to interact with Firecracker microVMs
+Author: Muhammad Yuga Nugraha
+License: MIT License
+        
+        Copyright (c) 2024 Practical DevSecOps
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: docker==7.1.0
+Requires-Dist: pyroute2==0.8.1
+Requires-Dist: paramiko==3.5.1
+Requires-Dist: faker==37.9.0
+Dynamic: license-file
+Dynamic: requires-python
+
+# firecracker-python
+
+<p align="center">
+<a href="https://opensource.org/license/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg"></a>
+<a href="https://github.com/myugan/firecracker-python"><img src="https://img.shields.io/github/stars/myugan/firecracker-python.svg?style=social&label=Star"></a>
+<a href="https://github.com/myugan/firecracker-python"><img src="https://img.shields.io/github/forks/myugan/firecracker-python.svg?style=social&label=Fork"></a>
+<a href="https://github.com/myugan/firecracker-python"><img src="https://img.shields.io/github/watchers/myugan/firecracker-python.svg?style=social&label=Watch"></a>
+</p>
+
+![Firecracker](assets/img/firecracker.png)
+
+**firecracker-python** is a simple Python library that makes it easy to manage Firecracker microVMs. It provides a simple way to create, configure, and manage microVMs.
+
+Some features are still being developed and will be added in the future. You can track these in the [TODO.md](TODO.md) file.
+
+[![asciicast](https://asciinema.org/a/725316.svg)](https://asciinema.org/a/725316)
+
+## Table of Contents
+
+- [How to Install](#how-to-install)
+- [Key Features](#key-features)
+- [Getting Started](#getting-started)
+- [Usage](#usage)
+- [License](#license)
+- [Contributing](#contributing)
+
+### How to Install
+
+To install from PyPI, you need to have a personal access token with read access to the repository.
+
+```bash
+pip3 install firecracker-python
+```
+
+Or install from source, by cloning the repository and installing the package using pip:
+
+```bash
+git clone https://github.com/myugan/firecracker-python.git
+cd firecracker-python
+
+# Using uv (recommended)
+uv sync --dev
+
+# Or using pip
+python3 -m venv venv
+source venv/bin/activate
+pip3 install -r requirements.txt
+pip3 install -e .
+```
+
+### Key Features
+
+- Easily create microVMs with default or custom settings
+- View a list of all running microVMs
+- Access and modify microVM settings
+- Remove one or all microVMs
+- Connect to microVMs using SSH
+- Set up port forwarding in microVMs
+
+### Getting Started
+
+The easiest way to get started is to use the official Firecracker setup script:
+
+```bash
+# Run the official setup script (downloads official CI kernel and rootfs)
+./assets/rootfs/setup-firecracker-official.sh
+
+# Then run the sample script
+./examples/sample.py
+```
+
+This will:
+1. Download the latest Firecracker kernel from official CI (tested with Ubuntu)
+2. Download the official Ubuntu rootfs from Firecracker CI
+3. Set up SSH keys for root access
+4. Create a properly configured ext4 rootfs image
+
+The official setup uses Firecracker's CI kernel and rootfs which are **proven to work together**, avoiding kernel compatibility issues.
+
+**Manual Setup (Alternative):**
+
+If you prefer to build your own rootfs, see [`FIRECRACKER_SETUP.md`](FIRECRACKER_SETUP.md) for detailed instructions.
+
+#### Prerequisites
+
+Before running the setup script, ensure you have:
+
+- **Firecracker binary** installed at `/usr/local/bin/firecracker` or `/usr/bin/firecracker`
+- **KVM** enabled on your system: `lsmod | grep kvm`
+- **Docker** installed and running (for rootfs setup)
+- **Python 3.9+** installed
+
+#### Enable IP Forwarding
+
+To enable networking for Firecracker VMs, run:
+
+```bash
+sudo sh -c "echo 1 > /proc/sys/net/ipv4/ip_forward"
+sudo iptables -P FORWARD ACCEPT
+```
+
+#### Quick Start Example
+
+```bash
+# Activate virtual environment and run sample
+source .venv/bin/activate
+./examples/sample.py
+```
+
+The sample script includes:
+- Automatic IP conflict detection
+- VM creation with verified files
+- SSH connection capability
+- Cleanup instructions
+
+To get started with **firecracker-python**, check out the [getting started guide](docs/getting-started.md)
+
+### Usage
+
+Here are some examples of how to use the library.
+
+#### Create a microVM with custom configuration and list them all
+
+```python
+from firecracker import MicroVM
+
+# Create a new microVM with custom configuration
+vm = MicroVM(vcpu=2, memory="4096")
+# Or
+vm = MicroVM(vcpu=2, memory="4G")
+
+vm.create()
+
+# List all running microVMs
+vms = MicroVM.list()  # Static method to list all VMs
+for vm in vms:
+    print(f"VM with id {vm['id']} has IP {vm['ip_addr']} and is in state {vm['state']}")
+```
+
+#### Delete a microVM by id or all microVMs
+
+```python
+from firecracker import MicroVM
+
+# Create a new microVM
+vm = MicroVM()
+vm.create()
+
+# Delete the microVM just created
+vm.delete()
+
+# Delete a specific microVM by ID
+vm.delete(id="<specific_id>")
+
+# Delete all microVMs
+vm.delete(all=True)
+```
+
+#### Enable port forwarding
+
+During initialization:
+
+```python
+from firecracker import MicroVM
+
+# Single port
+vm = MicroVM(expose_ports=True, host_port=10222, dest_port=22)
+# Multiple ports
+# vm = MicroVM(expose_ports=True, host_port=[10222, 10280], dest_port=[22, 80])
+
+vm.create()
+```
+
+After creation you can also expose ports using the `port_forward` function:
+
+```python
+from firecracker import MicroVM
+
+vm = MicroVM()
+vm.create()
+
+# Forward a single port
+vm.port_forward(host_port=10222, dest_port=22)
+# 'Port forwarding added successfully'
+
+# Forward multiple ports
+vm.port_forward(host_port=[10222, 10280], dest_port=[22, 80])
+# 'Port forwarding added successfully'
+
+# Remove port forwarding
+vm.port_forward(host_port=10222, dest_port=22, remove=True)
+# 'Port forwarding removed successfully'
+```
+
+> **Note:** When using port forwarding, you need to specify both `host_port` and `dest_port`. The number of host ports must match the number of destination ports.
+
+### License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+### Contributing
+
+Contributions are welcome! Please open an issue or submit a Pull Request (PR).

hysn_firecracker_python-1.0.3.post0.dist-info/RECORD

@@ -0,0 +1,18 @@
+firecracker/__init__.py,sha256=tVrFN8DTus2ECu5REZWaaHc-ssuU84TFU4Csq9Oa_cY,444
+firecracker/_version.py,sha256=YvlepUiKrcq1HdxigGnv1IA16ttnJCqVWrXBKQKICDA,727
+firecracker/api.py,sha256=tom62ct8qTO2-HjsoA2BtuQfCZd7hnVOE9XvAYHG9fI,6358
+firecracker/config.py,sha256=8i_ILfzG1DjFGHIFvx_Sm7Z_-pM6WSe4_QVw-xRpS_E,858
+firecracker/exceptions.py,sha256=eP_pvSjTiwbzOXytx6NcMHjrH-DswalDGCIPSCfGyH8,686
+firecracker/logger.py,sha256=Dapmrl4rOaIlV4hTjXJEbfzgXYNnJ2vXt8Xmv9dS9ek,3034
+firecracker/microvm.py,sha256=4Fm2jy1S8ZYiqiOOzjNQix4Vlv6byCLIBqwDBBbKRZM,67553
+firecracker/network.py,sha256=-wstjy_0ZMhmfFzcmh2FTfQX3FYlGPmZ_nTys4I6D1U,46486
+firecracker/process.py,sha256=eIa98O4g5HFQZaZNyG-NbAPwLg1EC3-XKIsedr-pea4,15798
+firecracker/scripts.py,sha256=-5qN1S5nTEyOZnQ3OZKh5E3zmdcfjmBJHdJx3ztzjwE,1715
+firecracker/utils.py,sha256=PATNnvxaThEfBW4OZUVcPQdGD_nbfra9CaYKVeWTiRo,5456
+firecracker/vmm.py,sha256=M9ggvFTflSFYJte4meQADxyl8vNBvjWBTu6gc4XdS3E,16812
+hysn_firecracker_python-1.0.3.post0.dist-info/licenses/LICENSE,sha256=NIYXDmhVsJ3HLDnHQmMrCN504brUDG7_GQAA7u0RJek,1075
+hysn_firecracker_python-1.0.3.post0.dist-info/METADATA,sha256=SFM8qYO86KBFzqRM3TUl4Pa1BqG2_YP9OGFN__wYSfM,7675
+hysn_firecracker_python-1.0.3.post0.dist-info/WHEEL,sha256=SmOxYU7pzNKBqASvQJ7DjX3XGUF92lrGhMb3R6_iiqI,91
+hysn_firecracker_python-1.0.3.post0.dist-info/entry_points.txt,sha256=T7TXm3t_0Of1La6E2f8lQGaUD8i7IYdQHkqlKgCdtc0,83
+hysn_firecracker_python-1.0.3.post0.dist-info/top_level.txt,sha256=w30yvfbEl4GrqkeROCQP1HA-NqnfClaD2obrPT0i7t4,12
+hysn_firecracker_python-1.0.3.post0.dist-info/RECORD,,

hysn_firecracker_python-1.0.3.post0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (79.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

hysn_firecracker_python-1.0.3.post0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+firecracker-check = firecracker.scripts:check_firecracker_binary

hysn_firecracker_python-1.0.3.post0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Practical DevSecOps
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hysn_firecracker_python-1.0.3.post0.dist-info/top_level.txt

@@ -0,0 +1 @@
+firecracker