kitchen-proxmox 0.3.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8592a8c21a5245c5517893fb3de6c2c2a9cae921cdb8c499fd3a7bcfcc8dc35a
-  data.tar.gz: eb18680f687a41ef9a5a5c2f4b290e586e867de4795cdc5733998189fb3b4e85
+  metadata.gz: fa03e257c553dacbc24d63abaa1a21b0bdf7be8dd2434afef6d304b2925bd23e
+  data.tar.gz: eea6142b73c7f1b0d82ec61f628b0aae64fca365df598c815c282e37c47dbaaf
 SHA512:
-  metadata.gz: 8da473dbe9ddf5891bff39a77fe3a55db3fd263a4413592e0c55d826387dbde2e60f77287516f31dd5083200d8d5c962ceaf811f43ad0b89e1a794311ece678b
-  data.tar.gz: c93d6729fa61fbc286cdd6b64e03febad2ea3995c1a29e346e5c35037f51339f84aef79370c90443ce96f4ec94fb494225fbf05a3ad27942378c97b54e2d9e36
+  metadata.gz: 4c558a3b1e537092dcc396e610f42a7695d088c316ae1cb3bfceacd1dbaab918c2b1751adc1123bf2e5855407bd2e840e7e698c34739b2524a8e9de3a43ff987
+  data.tar.gz: c59edb23fa7d0f06bc247db4c10a93b6c82c29402d3138e9477e6f815538bcaae5235651f058c914928626aeb11eaeaeba511f4c1e3ec3cc3884ef6b8a51cdaa

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,14 +13,39 @@ 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
@@ -33,7 +58,8 @@ module Kitchen
 
         def clone_vm(node:, template_id:, new_id:, **options)
           full = options.fetch(:full, true)
-          body = { newid: new_id, full: full ? 1 : 0, target: node }
+          target = options.fetch(:target, node)
+          body = { newid: new_id, full: full ? 1 : 0, target: }
           body[:name] = options[:name] if options[:name]
           body[:pool] = options[:pool] if options[:pool]
           body[:storage] = options[:storage] if options[:storage]
@@ -82,9 +108,7 @@ module Kitchen
             status = task_status(node:, upid:)
             if status['status'] == 'stopped'
               exitstatus = status['exitstatus'].to_s
-              unless exitstatus == 'OK'
-                raise ProxmoxErrors::ApiError.new(500, exitstatus)
-              end
+              raise ProxmoxErrors::ApiError.new(500, exitstatus) unless exitstatus == 'OK'
 
               return status
             end
@@ -107,6 +131,10 @@ module Kitchen
           resources.select { |r| r['template'] == 1 }
         end
 
+        def list_storage(node:)
+          get("/api2/json/nodes/#{node}/storage")
+        end
+
         private
 
         def get(path)
@@ -122,32 +150,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

@@ -33,6 +33,12 @@ module Kitchen
             response_body.match?(/does not exist/i) ||
             response_body.match?(/can't lock file.*lock-\d+/i)
         end
+
+        # Returns true when clone fails because the template uses local storage
+        # and cannot be cloned to a different node.
+        def local_storage_conflict?
+          response_body.match?(/uses local storage/i)
+        end
       end
     end
   end

data/lib/kitchen/driver/proxmox.rb

@@ -23,9 +23,13 @@ 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 :clone_type, 'auto'
 
       default_config :ssl_verify, true
+      default_config :connect_timeout, 10
       default_config :pool, nil
       default_config :vm_name_prefix, 'kitchen-'
       default_config :cpus, 1
@@ -42,7 +46,10 @@ module Kitchen
       def create(state)
         return if state[:vm_id]
 
+        resolve_node(state)
+        resolve_template(state)
         validate_config!
+        resolve_clone_strategy(state)
         clone_and_start(state)
       end
 
@@ -50,9 +57,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
@@ -61,27 +69,32 @@ 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)
         retries = config[:clone_retries]
         last_error = nil
+        node = state[:node]
+        template_id = state[:template_id] || config[:template_id]
+        template_node = state[:template_node] || node
+        full_clone = state[:full_clone]
 
         retries.times do |attempt|
-          info("Creating Proxmox VM from template #{config[:template_id]}...")
+          info("Creating Proxmox VM from template #{template_id}...")
 
-          vm_id, vm_name = allocate_and_clone
+          vm_id, vm_name = allocate_and_clone(node, template_id, template_node, full_clone)
           state[:vm_id] = vm_id
           state[:vm_name] = vm_name
 
           begin
-            configure_hardware(vm_id)
-            start_and_wait_for_ip(state, vm_id)
+            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
@@ -91,6 +104,7 @@ module Kitchen
             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
@@ -98,7 +112,7 @@ module Kitchen
         raise last_error
       end
 
-      def allocate_and_clone
+      def allocate_and_clone(node, template_id, template_node, full_clone)
         retries = config[:clone_retries]
         last_error = nil
 
@@ -107,7 +121,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, template_node, full_clone)
             return [vm_id, vm_name]
           rescue ApiError => e
             raise unless e.vmid_conflict?
@@ -135,19 +149,34 @@ module Kitchen
         "#{config[:vm_name_prefix]}#{suite_name}-#{Time.now.to_i}"
       end
 
-      def clone_template(vm_id, vm_name)
-        node = config[:node]
+      def clone_template(target_node, vm_id, vm_name, template_id, template_node, full_clone)
         upid = api_client.clone_vm(
-          node:, template_id: config[:template_id],
+          node: template_node, template_id:,
           new_id: vm_id, name: vm_name,
+          target: target_node, full: full_clone,
           pool: config[:pool], storage: config[:storage]
         )
-        api_client.wait_for_task(node:, upid:, timeout: config[:clone_timeout])
+        api_client.wait_for_task(node: template_node, upid:, timeout: config[:clone_timeout])
+      rescue ApiError => e
+        raise local_storage_error(template_id, template_node, target_node) if e.local_storage_conflict?
+
+        raise
+      end
+
+      def local_storage_error(template_id, template_node, target_node)
+        Kitchen::UserError.new(
+          "Cannot clone template #{template_id} from node '#{template_node}' to node '#{target_node}' " \
+          "because the template uses local storage.\n\n" \
+          "To fix this, either:\n" \
+          "  - Move the template disk to shared storage (e.g. NFS, Ceph, iSCSI)\n" \
+          "  - Pin the node to '#{template_node}' in .kitchen.yml: node: #{template_node}\n" \
+          "  - Create a copy of the template on '#{target_node}'"
+        )
       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],
@@ -155,30 +184,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
 
@@ -186,11 +215,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'])
@@ -209,41 +235,164 @@ module Kitchen
         nil
       end
 
+      def resolve_clone_strategy(state)
+        return if state[:full_clone] != nil # rubocop:disable Style/NonNilCheck
+
+        # Can't determine strategy without a template
+        template_id = state[:template_id] || config[:template_id]
+        return unless template_id
+
+        case config[:clone_type]
+        when 'full'
+          state[:full_clone] = true
+        when 'linked'
+          state[:full_clone] = false
+        else
+          detect_clone_strategy(state)
+        end
+      end
+
+      def detect_clone_strategy(state)
+        template_id = state[:template_id] || config[:template_id]
+        template_node = state[:template_node] || state[:node]
+        storage_info = template_storage_info(template_node, template_id)
+        shared = storage_info && storage_info['shared'] == 1
+        supports_linked = shared && linked_clone_capable_type?(storage_info['type'])
+
+        if supports_linked
+          state[:full_clone] = false
+        elsif shared
+          # Shared but doesn't support linked clones (e.g. plain LVM)
+          state[:full_clone] = true
+          warn("Storage '#{storage_info['storage']}' (type: #{storage_info['type']}) does not support linked clones. " \
+               'Using full clone. For faster clones, use lvmthin, ZFS, Ceph RBD, or file-based storage (NFS/dir).')
+        else
+          # Local storage — full clone and pin to template node
+          state[:full_clone] = true
+          pin_to_template_node(state, template_node)
+        end
+      end
+
+      LINKED_CLONE_STORAGE_TYPES = %w[lvmthin nfs dir cephfs rbd zfspool btrfs].freeze
+
+      def linked_clone_capable_type?(type)
+        LINKED_CLONE_STORAGE_TYPES.include?(type.to_s)
+      end
+
+      def template_storage_info(template_node, template_id)
+        vm_conf = api_client.vm_config(node: template_node, vm_id: template_id)
+        storage_name = extract_storage_name(vm_conf)
+        return nil unless storage_name
+
+        storages = api_client.list_storage(node: template_node)
+        storages.find { |s| s['storage'] == storage_name }
+      end
+
+      def extract_storage_name(vm_conf)
+        # Find the first real disk field (scsi0, virtio0, ide0, sata0, etc.)
+        disk_field = vm_conf.find do |k, v|
+          k.match?(/^(scsi|virtio|ide|sata)\d+$/) && !v.start_with?('none')
+        end
+        return nil unless disk_field
+
+        # Format: "StorageName:disk-name,option=val,..."
+        disk_field[1].split(':').first
+      end
+
+      def pin_to_template_node(state, template_node)
+        return if state[:node] == template_node
+
+        warn("Template uses local storage on node '#{template_node}' — " \
+             "pinning clone target to '#{template_node}'. " \
+             'Move template to shared storage for cross-node flexibility.')
+        state[:node] = template_node
+      end
+
       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
+
+        # 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']
+        state[:template_node] = selected['node']
+        info("Resolved template '#{config[:template_name]}' to VMID #{state[:template_id]} " \
+             "on node #{state[:template_node]}")
+      end
+
+      def resolve_node(state)
+        # Use pinned node from config
+        if config[:node]
+          state[:node] = config[:node]
+          return
         end
-        msg
+
+        # 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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kitchen-proxmox
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.5.0
 platform: ruby
 authors:
 - Richard Nixon