durable-proxmox-ruby 0.1.0

data/lib/durable_proxmox/vm.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+module DurableProxmox
+  # Represents a Proxmox virtual machine.
+  #
+  # Provides access to VM properties, lifecycle operations, and network configuration.
+  class VM
+    # @return [String] VM ID
+    attr_reader :vm_id
+
+    # @return [String] VM name/hostname
+    attr_reader :name
+
+    # @return [String] VM status
+    attr_reader :status
+
+    # @return [Float] CPU usage
+    attr_reader :cpu
+
+    # @return [Float] Memory usage
+    attr_reader :memory
+
+    # @return [DurableProxmox::Client] The client instance
+    attr_reader :client
+
+    # @return [String] Node ID where the VM resides
+    attr_reader :node_id
+
+    # @return [Hash] Raw VM data from API
+    attr_reader :data
+
+    # Creates a new VM instance.
+    #
+    # @param data [Hash] VM data from the API
+    # @param node [DurableProxmox::Node] The node this VM belongs to
+    # @param client [DurableProxmox::Client] The client instance
+    def initialize(data, node, client)
+      @client = client
+      @data = data
+      @vm_id = data["vmid"]
+      @name = data["name"]
+      @status = data["status"]
+      @cpu = data["cpu"]
+      @memory = data["memory"]
+      @node = node
+      @cache = {}
+    end
+
+    # Clears the internal cache.
+    #
+    # Useful when the VM state has changed externally.
+    def clear_cache
+      @cache.clear
+    end
+
+    # Starts the VM.
+    #
+    # @return [Faraday::Response] The API response
+    def start
+      puts "Starting VM #{vm_id} (#{name})..."
+      response = @client.post("nodes/#{node_id}/qemu/#{vm_id}/status/start")
+      upid = response.body.dig("data")
+      if upid
+        @client.wait_for_upid(node_id, upid)
+        puts "VM #{vm_id} (#{name}) started successfully"
+      end
+      response
+    end
+
+    # Stops the VM.
+    #
+    # @return [Faraday::Response] The API response
+    def stop
+      puts "Stopping VM #{vm_id} (#{name})..."
+      response = @client.post("nodes/#{node_id}/qemu/#{vm_id}/status/stop")
+      upid = response.body.dig("data")
+      if upid
+        @client.wait_for_upid(node_id, upid)
+        puts "VM #{vm_id} (#{name}) stopped successfully"
+      end
+      response
+    end
+
+    # Deletes the VM.
+    #
+    # @return [Faraday::Response] The API response
+    def delete
+      puts "Deleting VM #{vm_id} (#{name})..."
+      response = @client.delete("nodes/#{node_id}/qemu/#{vm_id}")
+      upid = response.body.dig("data")
+      if upid
+        @client.wait_for_upid(node_id, upid)
+        puts "VM #{vm_id} (#{name}) deleted successfully"
+      end
+      response
+    end
+
+    # Retrieves the VM configuration.
+    #
+    # @return [Hash] VM configuration data
+    def config
+      @cache["config"] ||= @client.get("nodes/#{node_id}/qemu/#{vm_id}/config").body.dig("data")
+    end
+
+    # Retrieves MAC addresses for the VM's network interfaces.
+    #
+    # @return [Array<String>] Array of MAC addresses
+    def mac_addresses
+      net_keys = config.keys.select { |key| key =~ /^net\d+$/ }
+      net_keys.map do |key|
+        net = config[key]
+        net.split(",").map do |pair|
+          k, v = pair.split("=")
+          k == "virtio" ? v : nil
+        end.compact.first
+      end
+    end
+
+    # Returns the node ID for this VM.
+    #
+    # @return [String] Node ID
+    def node_id
+      @node.node_id
+    end
+
+    # Retrieves network interface information from the QEMU guest agent.
+    #
+    # @return [Array<Hash>] Array of network interface data
+    def network_interfaces
+      @cache["network_interfaces"] ||= begin
+        url = "nodes/#{node_id}/qemu/#{vm_id}/agent/network-get-interfaces"
+        response = @client.get(url)
+        response.body.dig("data", "result") || []
+      rescue Faraday::ConnectionFailed, Faraday::SSLError, EOFError => e
+        # QEMU guest agent may not be running or connection issues
+        []
+      end
+    end
+
+    # Retrieves IP addresses for the VM from the cloud-init config.
+    #
+    # @return [DurableProxmox::IPAddressGroup] IP address group
+    def ip_addresses
+      ip_addresses = []
+      ipconfig_keys = config.keys.select { |key| key =~ /^ipconfig\d+$/ }
+      ipconfig_keys.each do |key|
+        ipconfig = config[key]
+        # Parse cloud-init ipconfig string like "ip=192.168.1.100/24,gw=192.168.1.1"
+        ipconfig.split(",").each do |pair|
+          k, v = pair.split("=", 2)
+          if k == "ip" && v != "dhcp"
+            # Extract IP without CIDR notation
+            ip_addresses << { "ip-address" => v.split("/").first }
+          end
+        end
+      end
+      IPAddressGroup.new(ip_addresses)
+    end
+
+    # Returns the first MAC address.
+    #
+    # @return [String, nil] The primary MAC address or nil
+    def mac
+      mac_addresses.first
+    end
+
+    # Returns the first IPv4 address for the VM.
+    #
+    # @return [String, nil] The primary IPv4 address or nil
+    def ip
+      ip_addresses.ipv4.octets.first
+    end
+
+    # Exports this VM as DSL code.
+    #
+    # @return [String] DSL code representing this VM
+    def to_dsl
+      lines = []
+      lines << "vm \"#{name}\" do"
+      lines << "  vmid #{vm_id}" if vm_id
+
+      cfg = config
+      lines << "  cores #{cfg['cores']}" if cfg['cores']
+      lines << "  memory #{cfg['memory']}" if cfg['memory']
+
+      # Extract IP from ipconfig
+      primary_ip = ip
+      lines << "  ip \"#{primary_ip}\"" if primary_ip
+
+      # Extract DNS servers from nameserver
+      if cfg['nameserver'] && !cfg['nameserver'].empty?
+        dns_list = cfg['nameserver'].split.map { |dns| "\"#{dns}\"" }.join(", ")
+        lines << "  dns_servers #{dns_list}"
+      end
+
+      lines << "end"
+      lines.join("\n")
+    end
+  end
+end

data/lib/durable_proxmox.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+require "dotenv"
+require "ipaddr"
+
+require_relative "durable_proxmox/version"
+require_relative "durable_proxmox/errors"
+
+module DurableProxmox
+  autoload :Client, "durable_proxmox/client"
+  autoload :Node, "durable_proxmox/node"
+  autoload :VM, "durable_proxmox/vm"
+  autoload :IPAddressGroup, "durable_proxmox/ip_address_group"
+  autoload :DSL, "durable_proxmox/dsl"
+  autoload :VMDefinition, "durable_proxmox/dsl"
+
+  # Convenience method to create a new client
+  #
+  # @param url_base [String, nil] The base URL for the Proxmox API
+  # @param insecure [Boolean, nil] Skip SSL certificate validation (defaults to DP_INSECURE env var)
+  # @return [DurableProxmox::Client] A new client instance
+  def self.client(url_base = nil, insecure: nil)
+    insecure = ENV['DP_INSECURE'] == 'true' if insecure.nil?
+    Client.new(url_base, insecure: insecure)
+  end
+
+  # Load environment variables from .env file if present
+  Dotenv.load if defined?(Dotenv)
+end

metadata

@@ -0,0 +1,201 @@
+--- !ruby/object:Gem::Specification
+name: durable-proxmox-ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Durable Programming LLC
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: ipaddr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+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.
+email:
+- commercial@durableprogramming.com
+executables:
+- proxmox
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- durable-proxmox-ruby.gemspec
+- exe/proxmox
+- lib/durable_proxmox.rb
+- lib/durable_proxmox/client.rb
+- lib/durable_proxmox/dsl.rb
+- lib/durable_proxmox/errors.rb
+- lib/durable_proxmox/ip_address_group.rb
+- lib/durable_proxmox/node.rb
+- lib/durable_proxmox/version.rb
+- lib/durable_proxmox/vm.rb
+homepage: https://github.com/durableprogramming/durable-proxmox-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/durableprogramming/durable-proxmox-ruby
+  source_code_uri: https://github.com/durableprogramming/durable-proxmox-ruby
+  changelog_uri: https://github.com/durableprogramming/durable-proxmox-ruby/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.1
+specification_version: 4
+summary: A pragmatic Ruby library for interacting with Proxmox VE through a clean
+  API
+test_files: []