kitchen-proxmox 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9431e030d0300d57c9fac8a20047375865cedf9f4a48b34b3039370f2d62a98a
-  data.tar.gz: 62e91255a7b9b2586eeef54bcd76bb7110b782ae8c948853ef0691a13e11df5e
+  metadata.gz: e3ed7c8556ee380cd5845babc8b085c3a660736b81ac8f1b1ac92cc62ec4840d
+  data.tar.gz: 8a82f387b8a24b8dfafc4dd99cb9baaa65c62483d3b564974d46a469ec40582e
 SHA512:
-  metadata.gz: e974ac8b7626ed1232e608073c259f5bb90c65aa47bdaf9327195a255dfbcbb7eb969a6cd88c5781c929835daa84f52a63e83aa6e291199de3d32889c244300b
-  data.tar.gz: 4b36857b3cfb877ff3bcf292049389cbe26cd43ab2393fb235d3236e8ad5d50ba74ed1ae55076961f97294f2df14e9a8d98d683a50afe4f37af5253ca3066f63
+  metadata.gz: 750a0b65316bcce6dccdb70c6c0c5061e830ddd7bb26011a034d1fe2e081805b6ca928ee7f027a4d5ee4e472916fed0b56ca6c7914747953596a579d64682b48
+  data.tar.gz: 71499dc0562fa3aa1691d6712fc4b70c9a4f608e27d1cb22f9370c7f604915aa869ca800e0adc817b8c0b3f5b5d8670a32ec2630b69d6eb30b737dad7ed5f17a

data/README.md

@@ -28,6 +28,26 @@ driver:
   template_id: 9000
 ```
 
+### Cluster-Aware Configuration
+
+For multi-node clusters, the driver can auto-select a node and resolve templates by name:
+
+```yaml
+driver:
+  name: proxmox
+  proxmox_url:
+    - https://pve1.example.com:8006
+    - https://pve2.example.com:8006
+  proxmox_token_id: kitchen@pam!kitchen-token
+  proxmox_token_secret: 00000000-0000-0000-0000-000000000000
+  template_name: ubuntu-2204-cloud
+```
+
+This configuration:
+- Tries `pve1` first; if unreachable, fails over to `pve2`
+- Auto-selects the node with the most free memory
+- Resolves `ubuntu-2204-cloud` to the template's VMID at runtime
+
 To avoid committing secrets, you can use ERB to inject them from environment variables. Test Kitchen processes `.kitchen.yml` as ERB before parsing the YAML:
 
 ```yaml
@@ -54,17 +74,34 @@ You can also put the exports in a `.envrc` (if using [direnv](https://direnv.net
 
 | Key | Description |
 |---|---|
-| `proxmox_url` | Proxmox API URL (e.g. `https://host:8006`) |
+| `proxmox_url` | Proxmox API URL (String or Array for failover) |
 | `proxmox_token_id` | API token ID (`user@realm!token-name`) |
 | `proxmox_token_secret` | API token secret (UUID) |
-| `node` | Proxmox node to create VMs on |
-| `template_id` | VM ID of the template to clone |
+
+### Node Selection
+
+| Key | Default | Description |
+|---|---|---|
+| `node` | `nil` | Pin to a specific Proxmox node (bypasses auto-selection) |
+| `node_pool` | `nil` | Restrict auto-selection to these node names (Array) |
+
+When `node` is omitted, the driver queries the cluster and selects the online node with the most free memory.
+
+### Template Selection
+
+| Key | Default | Description |
+|---|---|---|
+| `template_id` | `nil` | VM ID of the template to clone |
+| `template_name` | `nil` | Template name to resolve (mutually exclusive with `template_id`) |
+
+Set one of `template_id` or `template_name`. When using `template_name`, the driver resolves the name to a VMID via the cluster API, preferring a template on the target node.
 
 ### Optional Settings
 
 | Key | Default | Description |
 |---|---|---|
 | `ssl_verify` | `true` | Verify TLS certificates |
+| `connect_timeout` | `10` | Per-URL connection timeout in seconds |
 | `pool` | `nil` | Proxmox resource pool |
 | `vm_name_prefix` | `kitchen-` | Prefix for generated VM names |
 | `cpus` | `1` | Number of CPU cores |

data/lib/kitchen/driver/proxmox/api_client.rb

@@ -13,20 +13,49 @@ module Kitchen
       # HTTP client for the Proxmox VE REST API.
       # Authenticates via API tokens. Provides convenience
       # methods for VM lifecycle operations.
+      #
+      # Supports multiple API URLs for failover. On connection
+      # errors the client tries the next URL. Once a URL works
+      # it becomes the sticky preference for subsequent calls.
       class ApiClient
-        attr_reader :base_url, :token_id, :token_secret, :ssl_verify
-
-        def initialize(base_url:, token_id:, token_secret:, ssl_verify: true)
-          @base_url = base_url.chomp('/')
+        CONNECTION_ERRORS = [
+          Errno::ECONNREFUSED,
+          Errno::ECONNRESET,
+          Errno::ETIMEDOUT,
+          Errno::EHOSTUNREACH,
+          Net::OpenTimeout,
+          Net::ReadTimeout,
+          SocketError,
+          OpenSSL::SSL::SSLError
+        ].freeze
+
+        attr_reader :base_urls, :token_id, :token_secret, :ssl_verify, :connect_timeout
+
+        # Accepts either base_url (String) or base_urls (Array).
+        # The String form is normalized to a one-element array.
+        def initialize(token_id:, token_secret:, base_url: nil, base_urls: nil, ssl_verify: true, connect_timeout: 10)
+          urls = base_urls || Array(base_url)
+          @base_urls = urls.map { |u| u.chomp('/') }
           @token_id = token_id
           @token_secret = token_secret
           @ssl_verify = ssl_verify
+          @connect_timeout = connect_timeout
+          @preferred_url_index = nil
+        end
+
+        # Backward-compat reader: returns the first (or preferred) URL.
+        def base_url
+          @base_urls[@preferred_url_index || 0]
         end
 
         def next_vm_id
           get('/api2/json/cluster/nextid')
         end
 
+        def validate_vmid(vm_id)
+          get("/api2/json/cluster/nextid?vmid=#{vm_id}")
+        end
+
         def clone_vm(node:, template_id:, new_id:, **options)
           full = options.fetch(:full, true)
           body = { newid: new_id, full: full ? 1 : 0, target: node }
@@ -76,7 +105,12 @@ module Kitchen
           deadline = Time.now + timeout
           loop do
             status = task_status(node:, upid:)
-            return status if status['status'] == 'stopped'
+            if status['status'] == 'stopped'
+              exitstatus = status['exitstatus'].to_s
+              raise ProxmoxErrors::ApiError.new(500, exitstatus) unless exitstatus == 'OK'
+
+              return status
+            end
             raise "Task timeout after #{timeout}s: #{upid}" if Time.now > deadline
 
             sleep interval
@@ -111,32 +145,65 @@ module Kitchen
         end
 
         def delete(path, params = {})
-          uri = URI.parse("#{base_url}#{path}")
-          uri.query = URI.encode_www_form(params) unless params.empty?
-          http = build_http(uri)
-          req = Net::HTTP::Delete.new(uri.request_uri)
-          apply_headers(req)
-          handle_response(http.request(req))
+          with_failover do |url|
+            uri = URI.parse("#{url}#{path}")
+            uri.query = URI.encode_www_form(params) unless params.empty?
+            http = build_http(uri)
+            req = Net::HTTP::Delete.new(uri.request_uri)
+            apply_headers(req)
+            handle_response(http.request(req))
+          end
         end
 
         def request(method_class, path, body = nil)
-          uri = URI.parse("#{base_url}#{path}")
-          http = build_http(uri)
-          req = method_class.new(uri.request_uri)
-          apply_headers(req)
-
-          if body && !body.empty? && req.respond_to?(:body=)
-            req['Content-Type'] = 'application/x-www-form-urlencoded'
-            req.body = URI.encode_www_form(body)
+          with_failover do |url|
+            uri = URI.parse("#{url}#{path}")
+            http = build_http(uri)
+            req = method_class.new(uri.request_uri)
+            apply_headers(req)
+
+            if body && !body.empty? && req.respond_to?(:body=)
+              req['Content-Type'] = 'application/x-www-form-urlencoded'
+              req.body = URI.encode_www_form(body)
+            end
+
+            handle_response(http.request(req))
           end
+        end
+
+        # Tries the preferred URL first, then all others in order.
+        # On connection errors, advances to the next URL.
+        # On success, sets the working URL as preferred.
+        def with_failover
+          urls_to_try = failover_order
+          failures = []
+
+          urls_to_try.each_with_index do |url, idx|
+            return yield(url).tap { @preferred_url_index = @base_urls.index(url) }
+          rescue *CONNECTION_ERRORS => e
+            failures << [url, e]
+            # Reset preference if the preferred URL just failed
+            @preferred_url_index = nil if idx.zero? && @preferred_url_index
+          end
+
+          msg = "All Proxmox API URLs failed:\n"
+          failures.each { |url, err| msg += "  #{url}: #{err.class} - #{err.message}\n" }
+          raise ProxmoxErrors::ApiError.new(0, msg)
+        end
+
+        # Returns URLs ordered with preferred first, then the rest.
+        def failover_order
+          return @base_urls unless @preferred_url_index
 
-          handle_response(http.request(req))
+          preferred = @base_urls[@preferred_url_index]
+          [preferred] + @base_urls.reject { |u| u == preferred }
         end
 
         def build_http(uri)
           http = Net::HTTP.new(uri.host, uri.port)
           http.use_ssl = (uri.scheme == 'https')
           http.verify_mode = ssl_verify ? OpenSSL::SSL::VERIFY_PEER : OpenSSL::SSL::VERIFY_NONE
+          http.open_timeout = @connect_timeout
           http
         end
 

data/lib/kitchen/driver/proxmox/errors.rb

@@ -13,12 +13,25 @@ module Kitchen
           super("Proxmox API error #{status_code}: #{response_body}")
         end
 
-        # Returns true when the error indicates a VMID is already in use.
+        # Returns true when the error indicates a VMID is already in use
+        # or cannot be locked (concurrent clone race).
         def vmid_conflict?
           return false unless status_code == 400 || status_code == 500
 
           response_body.match?(/already exists/i) ||
-            response_body.match?(/unable to create VM \d+/i)
+            response_body.match?(/unable to create VM \d+/i) ||
+            response_body.match?(/can't lock file.*lock-\d+/i)
+        end
+
+        # Returns true when the error indicates another process owns the VM
+        # (lost a VMID race — VM was started or configured by another clone).
+        def vmid_race_lost?
+          return false unless status_code == 400 || status_code == 500
+
+          response_body.match?(/already running/i) ||
+            response_body.match?(/hotplug problem/i) ||
+            response_body.match?(/does not exist/i) ||
+            response_body.match?(/can't lock file.*lock-\d+/i)
         end
       end
     end

data/lib/kitchen/driver/proxmox.rb

@@ -23,9 +23,12 @@ module Kitchen
       required_config :proxmox_token_id
       required_config :proxmox_token_secret
       default_config :node, nil
+      default_config :node_pool, nil
       default_config :template_id, nil
+      default_config :template_name, nil
 
       default_config :ssl_verify, true
+      default_config :connect_timeout, 10
       default_config :pool, nil
       default_config :vm_name_prefix, 'kitchen-'
       default_config :cpus, 1
@@ -36,10 +39,14 @@ module Kitchen
       default_config :start_timeout, 300
       default_config :ip_wait_timeout, 120
       default_config :clone_retries, 5
+      default_config :vmid_range_min, 900_000
+      default_config :vmid_range_max, 999_999
 
       def create(state)
         return if state[:vm_id]
 
+        resolve_node(state)
+        resolve_template(state)
         validate_config!
         clone_and_start(state)
       end
@@ -48,9 +55,10 @@ module Kitchen
         return unless state[:vm_id]
 
         vm_id = state[:vm_id]
+        node = state[:node] || config[:node]
         info("Destroying Proxmox VM #{state[:vm_name]} (#{vm_id})...")
-        safe_stop_vm(vm_id)
-        api_client.destroy_vm(node: config[:node], vm_id:)
+        safe_stop_vm(node, vm_id)
+        api_client.destroy_vm(node:, vm_id:)
         clear_state(state)
         info("Proxmox VM #{vm_id} destroyed.")
       end
@@ -59,27 +67,48 @@ module Kitchen
 
       def api_client
         @api_client ||= ApiClient.new(
-          base_url: config[:proxmox_url],
+          base_urls: Array(config[:proxmox_url]).map(&:to_s),
           token_id: config[:proxmox_token_id],
           token_secret: config[:proxmox_token_secret],
-          ssl_verify: config[:ssl_verify]
+          ssl_verify: config[:ssl_verify],
+          connect_timeout: config[:connect_timeout]
         )
       end
 
       def clone_and_start(state)
-        info("Creating Proxmox VM from template #{config[:template_id]}...")
+        retries = config[:clone_retries]
+        last_error = nil
+        node = state[:node]
+        template_id = state[:template_id] || config[:template_id]
 
-        vm_id, vm_name = allocate_and_clone
-        state[:vm_id] = vm_id
-        state[:vm_name] = vm_name
+        retries.times do |attempt|
+          info("Creating Proxmox VM from template #{template_id}...")
 
-        configure_hardware(vm_id)
-        start_and_wait_for_ip(state, vm_id)
+          vm_id, vm_name = allocate_and_clone(node, template_id)
+          state[:vm_id] = vm_id
+          state[:vm_name] = vm_name
+
+          begin
+            configure_hardware(node, vm_id)
+            start_and_wait_for_ip(state, node, vm_id)
+            info("Proxmox VM #{vm_name} (#{vm_id}) created.")
+            return
+          rescue ApiError => e
+            raise unless e.vmid_race_lost?
+
+            last_error = e
+            warn("VMID #{vm_id} race lost (attempt #{attempt + 1}/#{retries}): #{e.message}")
+            warn("Another process owns VM #{vm_id} — abandoning and retrying...")
+            clear_state(state)
+            state[:node] = node
+            sleep backoff_delay(attempt)
+          end
+        end
 
-        info("Proxmox VM #{vm_name} (#{vm_id}) created.")
+        raise last_error
       end
 
-      def allocate_and_clone
+      def allocate_and_clone(node, template_id)
         retries = config[:clone_retries]
         last_error = nil
 
@@ -88,7 +117,7 @@ module Kitchen
           vm_name = generate_vm_name(instance.name)
 
           begin
-            clone_template(vm_id, vm_name)
+            clone_template(node, vm_id, vm_name, template_id)
             return [vm_id, vm_name]
           rescue ApiError => e
             raise unless e.vmid_conflict?
@@ -107,26 +136,27 @@ module Kitchen
       end
 
       def allocate_vm_id
-        Integer(api_client.next_vm_id)
+        vm_id = rand(config[:vmid_range_min]..config[:vmid_range_max])
+        api_client.validate_vmid(vm_id)
+        vm_id
       end
 
       def generate_vm_name(suite_name)
         "#{config[:vm_name_prefix]}#{suite_name}-#{Time.now.to_i}"
       end
 
-      def clone_template(vm_id, vm_name)
-        node = config[:node]
+      def clone_template(node, vm_id, vm_name, template_id)
         upid = api_client.clone_vm(
-          node:, template_id: config[:template_id],
+          node:, template_id:,
           new_id: vm_id, name: vm_name,
           pool: config[:pool], storage: config[:storage]
         )
         api_client.wait_for_task(node:, upid:, timeout: config[:clone_timeout])
       end
 
-      def configure_hardware(vm_id)
+      def configure_hardware(node, vm_id)
         api_client.configure_vm(
-          node: config[:node],
+          node:,
           vm_id:,
           cpus: config[:cpus],
           memory: config[:memory],
@@ -134,30 +164,30 @@ module Kitchen
         )
       end
 
-      def start_and_wait_for_ip(state, vm_id)
-        api_client.start_vm(node: config[:node], vm_id:)
-        ip = wait_for_ip(vm_id)
+      def start_and_wait_for_ip(state, node, vm_id)
+        api_client.start_vm(node:, vm_id:)
+        ip = wait_for_ip(node, vm_id)
         state[:hostname] = ip
       end
 
-      def stop_vm(vm_id)
-        status = api_client.vm_status(node: config[:node], vm_id:)
+      def stop_vm(node, vm_id)
+        status = api_client.vm_status(node:, vm_id:)
         return unless status['status'] == 'running'
 
-        upid = api_client.stop_vm(node: config[:node], vm_id:)
-        api_client.wait_for_task(node: config[:node], upid:, timeout: 60)
+        upid = api_client.stop_vm(node:, vm_id:)
+        api_client.wait_for_task(node:, upid:, timeout: 60)
       end
 
-      def safe_stop_vm(vm_id)
-        stop_vm(vm_id)
+      def safe_stop_vm(node, vm_id)
+        stop_vm(node, vm_id)
       rescue ::StandardError => e
         warn("Failed to stop VM #{vm_id}: #{e.message}")
       end
 
-      def wait_for_ip(vm_id)
+      def wait_for_ip(node, vm_id)
         deadline = Time.now + config[:ip_wait_timeout]
         loop do
-          ip = fetch_ip(vm_id)
+          ip = fetch_ip(node, vm_id)
           return ip if ip
           raise "Timed out waiting for IP on VM #{vm_id}" if Time.now > deadline
 
@@ -165,11 +195,8 @@ module Kitchen
         end
       end
 
-      def fetch_ip(vm_id)
-        interfaces = api_client.agent_network_interfaces(
-          node: config[:node],
-          vm_id:
-        )
+      def fetch_ip(node, vm_id)
+        interfaces = api_client.agent_network_interfaces(node:, vm_id:)
         return nil unless interfaces.is_a?(Hash) && interfaces['result']
 
         extract_ipv4_from_interfaces(interfaces['result'])
@@ -190,39 +217,87 @@ module Kitchen
 
       def validate_config!
         errors = []
-        errors << validate_node if config[:node].nil?
-        errors << validate_template_id if config[:template_id].nil?
+        errors << 'Set template_id OR template_name, not both.' if config[:template_id] && config[:template_name]
+        errors << validate_template_id if config[:template_id].nil? && config[:template_name].nil?
         return if errors.empty?
 
         raise Kitchen::UserError, errors.join("\n\n")
       end
 
-      def validate_node
-        msg = "Missing required config: node\n"
-        begin
-          nodes = api_client.list_nodes
-          msg += "Available Proxmox nodes:\n"
-          nodes.each { |n| msg += "  - #{n['node']} (#{n['status']})\n" }
-        rescue ::StandardError
-          msg += "  (could not retrieve node list from Proxmox API)\n"
+      def resolve_template(state)
+        # Already resolved (e.g. from a previous create attempt)
+        return if state[:template_id]
+
+        # If template_id is set in config, use it directly
+        if config[:template_id]
+          state[:template_id] = config[:template_id]
+          return
         end
-        msg
+
+        # Resolve template_name to VMID
+        return unless config[:template_name]
+
+        templates = api_client.list_templates
+        matches = templates.select { |t| t['name'] == config[:template_name] }
+
+        if matches.empty?
+          msg = "Template '#{config[:template_name]}' not found.\n#{format_template_list_from(templates)}"
+          raise Kitchen::UserError, msg
+        end
+
+        # Prefer template on the target node
+        node = state[:node]
+        selected = matches.find { |t| t['node'] == node } || matches.first
+        state[:template_id] = selected['vmid']
+        info("Resolved template '#{config[:template_name]}' to VMID #{state[:template_id]}")
+      end
+
+      def resolve_node(state)
+        # Use pinned node from config
+        if config[:node]
+          state[:node] = config[:node]
+          return
+        end
+
+        # Use previously resolved node from state
+        return if state[:node]
+
+        # Auto-select: query cluster and pick least-loaded online node
+        nodes = api_client.list_nodes
+        candidates = nodes.select { |n| n['status'] == 'online' }
+
+        # Filter by node_pool if set
+        candidates = candidates.select { |n| config[:node_pool].include?(n['node']) } if config[:node_pool]
+
+        if candidates.empty?
+          statuses = nodes.map { |n| "  - #{n['node']} (#{n['status']})" }.join("\n")
+          raise Kitchen::UserError, "No online nodes available. Node statuses:\n#{statuses}"
+        end
+
+        # Select by least memory allocation ratio
+        selected = candidates.min_by { |n| n['mem'].to_f / n['maxmem'] }
+        state[:node] = selected['node']
+        info("Auto-selected node: #{state[:node]}")
       end
 
       def validate_template_id
-        msg = "Missing required config: template_id\n"
+        msg = "Missing required config: template_id or template_name\n"
         msg + format_template_list
       end
 
       def format_template_list
         templates = api_client.list_templates
+        format_template_list_from(templates)
+      rescue ::StandardError
+        "  (could not retrieve template list from Proxmox API)\n"
+      end
+
+      def format_template_list_from(templates)
         return "  No templates found on the Proxmox cluster.\n" if templates.empty?
 
         lines = "Available templates:\n"
         templates.each { |t| lines += "  - #{t['vmid']}: #{t['name']} (node: #{t['node']})\n" }
         lines
-      rescue ::StandardError
-        "  (could not retrieve template list from Proxmox API)\n"
       end
 
       def clear_state(state)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kitchen-proxmox
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Richard Nixon
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-03 00:00:00.000000000 Z
+date: 2026-05-04 00:00:00.000000000 Z
 dependencies: []
 description: A Test Kitchen driver for Proxmox VE. Manages VM lifecycle (create, destroy)
   via the Proxmox REST API. Supports cloning from templates.