durable-proxmox-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 77769cb099a33a2cda9e1ddb3c170bce9a642e15e8d31b85c8c833a23c23220e
+  data.tar.gz: 4484d3acb3ce9d406d888acec028bc1a9be925ea7eecc9ce4091543b2cc58b08
+SHA512:
+  metadata.gz: 3e4aecb1d8963b1c665f8519b597bfea9f914675d371eedb63cbef446075dc14eb355dbe1c1eb0f9a536942d90050ac46720a98b35a9cc4db6e50c8e6d993307
+  data.tar.gz: 65e00f1417e3b4fa036f619ec8ec627363dec685d79033aa7dcea7b8ea78fb07c974682bae5a17dbb6335f4f6da7c4bee6d63ae2c5e42ecce010414e4bfb1bf1

data/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-01-26
+
+### Added
+- Initial release of durable-proxmox-ruby gem
+- Clean API interface for Proxmox VE interaction
+- Automatic authentication with ticket and CSRF token handling
+- VM lifecycle management (clone, start, stop, delete)
+- Network configuration retrieval (IP addresses, MAC addresses)
+- DHCP/DNS integration with VyOS
+- Caching support for improved performance
+- Task monitoring for asynchronous operations
+- Comprehensive documentation and examples
+
+### Changed
+- Refactored from old script-based structure to proper Ruby gem
+- Updated class names to use DurableProxmox module namespace
+- Improved error handling and code documentation
+
+### Technical Details
+- Ruby 2.7+ compatibility
+- Dependencies: faraday, json, dotenv, sshkit, ipaddr
+- Modular architecture with autoloading
+- Comprehensive test suite foundation

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Durable Programming LLC
+
+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.

data/README.md

@@ -0,0 +1,572 @@
+# durable-proxmox-ruby
+
+A pragmatic Ruby library for interacting with Proxmox VE through a clean API, featuring both imperative API methods and a declarative DSL for infrastructure management. Built with a focus on reliability, maintainability, and developer experience.
+
+This library solves the problem of programmatically managing Proxmox virtual environments without the complexity of shell scripts or manual API calls. It's designed for system administrators and developers who need to automate VM provisioning, configuration, and infrastructure-as-code workflows.
+
+## Features
+
+- **Clean API Interface**: Interact with Proxmox VE through intuitive Ruby objects (Client, Node, VM)
+- **Declarative DSL**: Define and update Proxmox server configurations using declarative scripts
+- **Export System**: Connect to a running Proxmox server and generate declarative configuration scripts from the current state
+- **Automatic Authentication**: Handles Proxmox API token authentication automatically
+- **VM Lifecycle Management**: Clone, start, stop, and delete virtual machines programmatically
+- **Network Configuration**: Retrieve IP addresses, MAC addresses, and network interface information
+- **DHCP/DNS Integration**: Automatically register VMs with VyOS-based DHCP and DNS services
+- **Caching Support**: Built-in caching for improved performance when querying VM and node data
+- **Task Monitoring**: Wait for asynchronous Proxmox tasks (UPIDs) to complete
+
+## Quick Start
+
+```ruby
+require 'durable_proxmox'
+
+# Create a client (uses ENV['PROXMOX_API_URL_BASE'] by default)
+client = DurableProxmox::Client.new
+
+# Get the first node
+node = client.nodes.first
+
+# List all VMs
+node.vms.each do |vm|
+  puts "#{vm.name} (#{vm.vm_id}): #{vm.status}"
+end
+
+# Clone a VM
+new_vmid = node.spawn_vm('my-new-server')
+puts "Created VM with ID: #{new_vmid}"
+
+# Get VM details
+vm = node.vms.find { |v| v.vm_id == new_vmid }
+puts "IP Address: #{vm.get_ip}"
+```
+
+## Installation
+
+### Prerequisites
+
+- Ruby 2.7 or higher
+- Access to a Proxmox VE server
+- Valid Proxmox credentials
+
+### Setup
+
+1. Install the gem:
+```bash
+gem install durable-proxmox-ruby
+```
+
+Or add to your Gemfile:
+```ruby
+gem 'durable-proxmox-ruby'
+```
+
+ 2. Configure environment variables:
+```bash
+# Required
+export PROXMOX_HOSTNAME='your-proxmox-server'
+export PROXMOX_USERNAME='your-username@pam'
+export PROXMOX_API_TOKEN_NAME='your-token-name'
+export PROXMOX_API_TOKEN_SECRET='your-token-secret'
+
+# Optional
+export SOURCE_VMID=911  # Template VM ID for cloning (default: 911)
+```
+
+3. Load environment variables (using dotenv):
+```ruby
+require 'dotenv'
+Dotenv.load
+```
+
+## Usage
+
+### Basic API Usage
+
+#### Connecting to Proxmox
+
+```ruby
+require_relative './old/init.rb'
+
+# Create a client with automatic authentication
+client = DurableProxmoxClient.new
+
+# Or specify a custom URL
+client = DurableProxmoxClient.new('https://custom-server:8006/api2/json/')
+```
+
+#### Working with Nodes
+
+```ruby
+# Get all nodes
+nodes = client.nodes
+
+# Access node properties
+node = nodes.first
+puts node.name
+puts node.status
+puts node.cpu
+puts node.memory
+```
+
+#### Managing Virtual Machines
+
+```ruby
+# List VMs on a node
+vms = node.vms
+
+# Access VM properties
+vm = vms.first
+puts vm.name        # VM hostname
+puts vm.vm_id       # Proxmox VMID
+puts vm.status      # running, stopped, etc.
+puts vm.cpu         # CPU usage
+puts vm.memory      # Memory usage
+
+# Get VM configuration
+config = vm.config
+puts config.inspect
+
+# Get network information
+mac_addresses = vm.mac_addresses
+ip_addresses = vm.ip_addresses
+network_interfaces = vm.network_interfaces
+
+# Start/stop VMs
+vm.start
+vm.stop
+```
+
+#### Cloning VMs
+
+```ruby
+# Clone from template (uses SOURCE_VMID environment variable)
+new_vmid = node.spawn_vm('new-hostname')
+
+# The method automatically:
+# - Generates the next available VMID
+# - Performs a full clone
+# - Waits for the clone operation to complete
+# - Returns the new VMID
+```
+
+#### Network Registration
+
+```ruby
+# Register VM with DHCP (VyOS integration)
+vm.register_dhcp
+
+# Register VM with DNS (VyOS integration)
+vm.register_dns
+
+# Get assigned IP address
+ip = vm.get_ip
+```
+
+#### Task Management
+
+```ruby
+# Wait for an asynchronous Proxmox task to complete
+client.wait_for_upid(node, upid)
+
+# This is automatically called by operations like spawn_vm
+# but can be used manually for custom API calls
+```
+
+### Advanced Usage
+
+#### Caching
+
+The library includes built-in caching to reduce API calls:
+
+```ruby
+# First call queries the API
+vms = node.vms
+
+# Subsequent calls use cached data
+vms = node.vms  # No API call
+
+# Clear cache when needed
+node.clear_cache
+
+# Per-VM caching
+vm.clear_cache
+```
+
+#### Finding Available VMID
+
+```ruby
+# Get the next available VMID
+next_id = node.get_next_vmid
+
+# This method:
+# - Finds gaps in existing VMIDs
+# - Excludes reserved IDs
+# - Considers both VMs and LXC containers
+```
+
+#### Working with IP Addresses
+
+```ruby
+# Get all IP addresses for a VM
+ip_group = vm.ip_addresses
+
+# Filter by subnet
+local_ips = vm.ip_addresses.in_subnets('192.168.2.0/23')
+
+# Get first IP in subnet
+primary_ip = local_ips.octets.first
+```
+
+### Declarative DSL (Planned)
+
+The declarative DSL allows you to define infrastructure as code:
+
+```ruby
+# Example (future feature)
+Proxmox.configure do
+  node 'pve-node-1' do
+    vm 'web-server-1' do
+      vmid 100
+      memory 4096
+      cores 2
+      disk size: '50G'
+      network bridge: 'vmbr0'
+    end
+  end
+end
+```
+
+### Export System (Planned)
+
+Export current Proxmox configuration to declarative scripts:
+
+```ruby
+# Example (future feature)
+client = DurableProxmoxClient.new
+config = client.export_configuration
+
+# Save to file
+File.write('proxmox-config.rb', config)
+```
+
+## API Reference
+
+### DurableProxmox::Client
+
+Main client for interacting with Proxmox API.
+
+#### Methods
+
+- `initialize(url_base = nil)` - Create a new client with automatic authentication
+- `nodes` - Returns array of DurableProxmox::Node objects
+- `get(path)` - Perform authenticated GET request
+- `post(path, params = {})` - Perform authenticated POST request
+- `delete(path)` - Perform authenticated DELETE request
+- `wait_for_upid(node, upid)` - Wait for asynchronous task to complete
+
+### DurableProxmox::Node
+
+Represents a Proxmox node.
+
+#### Attributes
+
+- `name` - Node name
+- `node_id` - Node identifier
+- `status` - Node status
+- `cpu` - CPU usage
+- `memory` - Memory usage
+
+#### Methods
+
+- `vms` - Returns array of DurableProxmox::VM objects
+- `lxcs` - Returns array of LXC container data
+- `spawn_vm(hostname)` - Clone template VM with given hostname
+- `delete_vm(vm)` - Delete a VM
+- `get_next_vmid` - Get next available VMID
+- `clear_cache` - Clear cached data
+
+### DurableProxmox::VM
+
+Represents a Proxmox virtual machine.
+
+#### Attributes
+
+- `vm_id` - Proxmox VMID
+- `name` - VM hostname
+- `status` - VM status (running, stopped, etc.)
+- `cpu` - CPU usage
+- `memory` - Memory usage
+- `data` - Raw VM data from API
+
+#### Methods
+
+- `start` - Start the VM
+- `stop` - Stop the VM
+- `delete` - Delete the VM
+- `config` - Get VM configuration
+- `mac_addresses` - Get array of MAC addresses
+- `network_interfaces` - Get network interface data
+- `ip_addresses` - Get DurableProxmox::IPAddressGroup
+- `mac` - Get first MAC address
+- `get_ip` - Get primary IP address
+- `register_dhcp` - Register with DHCP server (VyOS)
+- `register_dns` - Register with DNS server (VyOS)
+- `clear_cache` - Clear cached data
+
+## Configuration
+
+Configuration is handled through environment variables:
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `PROXMOX_HOSTNAME` | No | `fuzzyfireball.durablelan` | Proxmox server hostname |
+| `PROXMOX_USERNAME` | Yes | - | Proxmox username (e.g., `root@pam`) |
+| `PROXMOX_API_TOKEN_NAME` | Yes | - | API token name |
+| `PROXMOX_API_TOKEN_SECRET` | Yes | - | API token secret |
+| `SOURCE_VMID` | No | `911` | Template VM ID for cloning |
+
+## Examples
+
+### Example 1: Bulk VM Provisioning
+
+```ruby
+require 'durable_proxmox'
+
+client = DurableProxmox::Client.new
+node = client.nodes.first
+
+# Create multiple VMs from hostnames
+hostnames = ['web-01', 'web-02', 'db-01', 'cache-01']
+
+hostnames.each do |hostname|
+  puts "Creating #{hostname}..."
+
+  # Check if VM already exists
+  existing = node.vms.find { |vm| vm.name == hostname }
+  if existing
+    puts "  #{hostname} already exists, skipping..."
+    next
+  end
+
+  # Clone VM
+  vmid = node.spawn_vm(hostname)
+  node.clear_cache  # Refresh VM list
+
+  # Register with network services
+  vm = node.vms.find { |v| v.vm_id == vmid }
+  vm.register_dhcp
+  vm.register_dns
+
+  puts "  Created #{hostname} (VMID: #{vmid}, IP: #{vm.get_ip})"
+end
+```
+
+### Example 2: VM Inventory Report
+
+```ruby
+require 'durable_proxmox'
+require 'json'
+
+client = DurableProxmox::Client.new
+node = client.nodes.first
+
+# Generate inventory report
+inventory = node.vms.map do |vm|
+  {
+    name: vm.name,
+    vmid: vm.vm_id,
+    status: vm.status,
+    ip: vm.get_ip,
+    mac: vm.mac,
+    memory: vm.memory,
+    cpu: vm.cpu
+  }
+end
+
+# Output as JSON
+puts JSON.pretty_generate(inventory)
+
+# Or save to file
+File.write('vm-inventory.json', JSON.pretty_generate(inventory))
+```
+
+### Example 3: Automated VM Cleanup
+
+```ruby
+require 'durable_proxmox'
+
+client = DurableProxmox::Client.new
+node = client.nodes.first
+
+# Find and remove test VMs
+test_vms = node.vms.select { |vm| vm.name.start_with?('test-') }
+
+test_vms.each do |vm|
+  puts "Removing test VM: #{vm.name} (#{vm.vm_id})"
+
+  # Stop if running
+  vm.stop if vm.status == 'running'
+  sleep 5  # Wait for clean shutdown
+
+  # Delete VM
+  node.delete_vm(vm)
+end
+
+puts "Removed #{test_vms.length} test VMs"
+```
+
+## Architecture
+
+This library follows a modular, object-oriented design:
+
+```
+DurableProxmoxClient
+├── Authentication (API token)
+├── HTTP client (Faraday)
+└── Node management
+    └── DurableProxmoxNode
+        ├── VM management
+        │   └── DurableProxmoxVM
+        │       ├── Lifecycle (start/stop/clone)
+        │       ├── Network info
+        │       └── Integration (DHCP/DNS)
+        └── LXC management
+```
+
+**Key Design Principles**:
+- **Separation of Concerns**: Client, Node, and VM classes have distinct responsibilities
+- **Lazy Loading**: Data is fetched only when needed
+- **Caching**: Reduce API calls with intelligent caching
+- **Error Handling**: Clear error messages for authentication and API failures
+- **Extensibility**: Easy to add new Proxmox API endpoints
+
+## Integration
+
+### VyOS Integration
+
+The library includes built-in support for VyOS network configuration:
+
+```ruby
+# DHCP registration (via VyOS)
+vm.register_dhcp
+
+# DNS registration (via VyOS)
+vm.register_dns
+```
+
+This requires:
+- A VyOS router accessible to the Ruby process
+- Appropriate SSH credentials configured
+- The `DurableVyosClient` class (see `lib/durable_vyos_client.rb`)
+
+## Troubleshooting
+
+### Authentication Failures
+
+**Problem**: Authentication error
+
+**Solution**:
+- Verify `PROXMOX_USERNAME`, `PROXMOX_API_TOKEN_NAME`, and `PROXMOX_API_TOKEN_SECRET` are correct
+- Ensure the API token has appropriate permissions
+- Check that the Proxmox server is accessible at the configured hostname
+- For self-signed certificates, you may need to configure SSL verification
+
+### VM Not Found
+
+**Problem**: Cannot find VM after creation
+
+**Solution**:
+```ruby
+# Clear cache after creating VMs
+node.clear_cache
+vm = node.vms.find { |v| v.vm_id == new_vmid }
+```
+
+### Network Information Unavailable
+
+**Problem**: `network_interfaces` returns empty array
+
+**Solution**:
+- Ensure the VM is running
+- Verify QEMU guest agent is installed and running in the VM
+- Check that the VM has had time to boot and initialize the guest agent
+
+## Development
+
+### Running Tests
+
+```bash
+# Run all tests (when available)
+bundle exec rake test
+```
+
+### Code Style
+
+This project follows Durable Programming coding standards:
+- Meaningful variable names
+- Clear method responsibilities
+- Comprehensive error handling
+- YARD documentation for public APIs
+
+### Contributing
+
+We welcome contributions! To contribute:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/my-feature`)
+3. Make your changes with tests
+4. Ensure code follows style guidelines
+5. Submit a pull request
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
+
+## Roadmap
+
+### Planned Features
+
+- **Declarative DSL**: Define infrastructure as code with a clean Ruby DSL
+- **Export System**: Generate declarative scripts from existing Proxmox configurations
+- **LXC Support**: Full support for LXC container management
+- **Storage Management**: Create and manage storage configurations
+- **Backup Operations**: Trigger and manage VM backups
+- **Snapshot Management**: Create, list, and restore snapshots
+- **User Management**: Manage Proxmox users and permissions
+- **Template Management**: Create and manage VM templates
+- **Cluster Support**: Multi-node cluster operations
+
+### Future Improvements
+
+- Comprehensive test suite with mocked API responses
+- RubyGems publication for easy installation
+- CLI tool for common operations
+- Enhanced error handling and retry logic
+- Async operation support with callbacks
+- WebSocket support for real-time updates
+
+## Philosophy
+
+This library embodies Durable Programming principles:
+
+- **Pragmatic Problem-Solving**: Solves real infrastructure automation needs without unnecessary complexity
+- **Sustainability**: Designed for long-term maintenance and incremental improvement
+- **Quality**: Clean, well-tested code with comprehensive error handling
+- **Developer Experience**: Intuitive API that makes Proxmox automation approachable
+- **Interoperability**: Works seamlessly with existing Proxmox setups and other tools
+
+## License
+
+MIT License - See [LICENSE](LICENSE) for details
+
+## Support
+
+- **Documentation**: This README and inline code documentation
+- **Issues**: [GitHub Issues](https://github.com/yourusername/durable-proxmox-ruby/issues)
+- **Email**: commercial@durableprogramming.com
+
+## Credits
+
+Built by [Durable Programming LLC](https://durableprogramming.com) with a focus on creating sustainable, maintainable infrastructure automation tools.
+
+---
+

data/durable-proxmox-ruby.gemspec

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "lib/durable_proxmox/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "durable-proxmox-ruby"
+  spec.version = DurableProxmox::VERSION
+  spec.authors = ["Durable Programming LLC"]
+  spec.email = ["commercial@durableprogramming.com"]
+
+  spec.summary = "A pragmatic Ruby library for interacting with Proxmox VE through a clean API"
+  spec.description = "This library solves the problem of programmatically managing Proxmox virtual environments without the complexity of shell scripts or manual API calls. It's designed for system administrators and developers who need to automate VM provisioning, configuration, and infrastructure-as-code workflows."
+  spec.homepage = "https://github.com/durableprogramming/durable-proxmox-ruby"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 2.7.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/durableprogramming/durable-proxmox-ruby"
+  spec.metadata["changelog_uri"] = "https://github.com/durableprogramming/durable-proxmox-ruby/blob/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  spec.files = Dir.chdir(__dir__) do
+    Dir.glob("{lib,exe}/**/*", File::FNM_DOTMATCH).reject do |f|
+      File.directory?(f)
+    end + %w[LICENSE README.md CHANGELOG.md durable-proxmox-ruby.gemspec]
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Runtime dependencies
+  spec.add_dependency "faraday", "~> 2.0"
+  spec.add_dependency "json", "~> 2.0"
+  spec.add_dependency "dotenv", "~> 2.0"
+  spec.add_dependency "ipaddr", "~> 1.2"
+
+  # Development dependencies
+  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rubocop", "~> 1.0"
+  spec.add_development_dependency "yard", "~> 0.9"
+  spec.add_development_dependency "webmock", "~> 3.18"
+  spec.add_development_dependency "simplecov", "~> 0.22"
+
+  # For more information and examples about making a new gem, check out our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end