Proxmox K3s VM Automation with Python

This project automates the creation and management of K3s virtual machines (VMs) in a Proxmox Virtual Environment (PVE) using Python. It follows a src layout, leveraging proxmoxer for API interactions, python-dotenv for configuration management, and requests for ISO downloads.

Project Structure

homelab/  # Project Root
│── src/              # Contains all Python code
│   ├── homelab/
│   │   ├── __init__.py
│   │   ├── config.py
│   │   ├── proxmox_api.py
│   │   ├── resource_manager.py
│   │   ├── iso_manager.py
│   │   ├── vm_manager.py
│   │   ├── main.py
│   │   ├── .env  <-- Environment variables file
│── tests/
│── .gitignore
│── README.md
│── pyproject.toml  <-- Poetry project configuration
│── poetry.lock

Setup Instructions

1. Install Poetry

Follow the official installation guide to install Poetry.

2. Clone the Repository

git clone https://github.com/your-repo/homelab.git
cd homelab

3. Install Dependencies

poetry install

4. Configure Environment Variables

Create the .env file inside src/homelab/ and populate it with:

# Proxmox API Token (Replace with actual values)
API_TOKEN=root@pam!your_token_id=your_token_secret

# VM Defaults
ISO_NAME=ubuntu-24.04.2-desktop-amd64.iso
ISO_URL=https://releases.ubuntu.com/24.04.2/ubuntu-24.04.2-desktop-amd64.iso

Note: The .env file is ignored in .gitignore to prevent accidental commits.

5. Run the Application

Run the script from the project root (where pyproject.toml is located):

cd homelab
poetry run python -m homelab.main | tee proxmox_setup.log

Important Notes

  • The application must be run from the project root, not from src/ or src/homelab/.

  • The .env file must be inside src/homelab/ because the script loads environment variables from that location.

  • Logging output is stored in proxmox_setup.log.

Python Module Overview

  • config.py - Loads configuration from .env.

  • proxmox_api.py - Handles Proxmox API interactions.

  • resource_manager.py - Calculates VM CPU and memory allocations.

  • iso_manager.py - Manages ISO downloads and uploads.

  • vm_manager.py - Creates VMs dynamically.

  • main.py - Orchestrates the entire setup process.

Each module is tested in tests/, ensuring robustness and maintainability.

Running Unit Tests

To verify the functionality, run:

poetry add --dev pytest
pytest tests/

This ensures a fully automated, modular, and testable Proxmox K3s VM deployment workflow.