kitchen-proxmox 0.0.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e90a80692b09f43b76dcfe31d232c387bc40900248143b15e4bffedb797430b7
+  data.tar.gz: 5ac6f95f78c6d89bc8f2e5d74d8931d0b02be08e4c17b3eea001955022c3de0c
+SHA512:
+  metadata.gz: f4448ddcc9d0760db69e454565d57f77fc5d2dd8af23af7f380d32d23b6b4c36c3a8a48628b6a1ba557579cd11b86562a0baeec96dedfed5a86d6b4010732aaf
+  data.tar.gz: 0af5563d6925584dc91fe2e5ac54bed521fa5ece39ca22de87f912ea44390fc9b9073cd2b8d8a70ec6ffa481f21bbb864b5d034e6b722330addfd6af7dbd8059

data/LICENSE

@@ -0,0 +1,17 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+Copyright 2025 Richard Nixon
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/README.md

@@ -0,0 +1,131 @@
+# kitchen-proxmox
+
+A [Test Kitchen](https://kitchen.ci/) driver for [Proxmox VE](https://www.proxmox.com/en/proxmox-virtual-environment/overview). Creates and destroys VMs by cloning templates via the Proxmox REST API.
+
+## Requirements
+
+- [Chef Workstation](https://docs.chef.io/workstation/) (provides Ruby, Test Kitchen, and all dependencies)
+- Proxmox VE 7+ with API token authentication
+- A VM template to clone (with `qemu-guest-agent` installed for IP detection)
+
+## Installation
+
+```sh
+chef exec gem install kitchen-proxmox
+```
+
+## Configuration
+
+Add the driver to your `.kitchen.yml`:
+
+```yaml
+driver:
+  name: proxmox
+  proxmox_url: https://proxmox.example.com:8006
+  proxmox_token_id: kitchen@pam!kitchen-token
+  proxmox_token_secret: 00000000-0000-0000-0000-000000000000
+  node: pve
+  template_id: 9000
+```
+
+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
+driver:
+  name: proxmox
+  proxmox_url: https://proxmox.example.com:8006
+  proxmox_token_id: <%= ENV['PROXMOX_TOKEN_ID'] %>
+  proxmox_token_secret: <%= ENV['PROXMOX_TOKEN_SECRET'] %>
+  node: pve
+  template_id: 9000
+```
+
+Then export the variables before running Kitchen:
+
+```sh
+export PROXMOX_TOKEN_ID='kitchen@pam!kitchen-token'
+export PROXMOX_TOKEN_SECRET='00000000-0000-0000-0000-000000000000'
+kitchen converge
+```
+
+You can also put the exports in a `.envrc` (if using [direnv](https://direnv.net/)) or a `.env` file sourced by your shell. Add these files to `.gitignore` so secrets are never committed.
+
+### Required Settings
+
+| Key | Description |
+|---|---|
+| `proxmox_url` | Proxmox API URL (e.g. `https://host:8006`) |
+| `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 |
+
+### Optional Settings
+
+| Key | Default | Description |
+|---|---|---|
+| `ssl_verify` | `true` | Verify TLS certificates |
+| `pool` | `nil` | Proxmox resource pool |
+| `vm_name_prefix` | `kitchen-` | Prefix for generated VM names |
+| `cpus` | `1` | Number of CPU cores |
+| `memory` | `1024` | Memory in MB |
+| `storage` | `nil` | Target storage for the clone |
+| `network_bridge` | `vmbr0` | Network bridge for the VM |
+| `clone_timeout` | `300` | Seconds to wait for clone task |
+| `start_timeout` | `300` | Seconds to wait for VM start |
+| `ip_wait_timeout` | `120` | Seconds to wait for guest IP |
+
+## Proxmox Setup
+
+### Create a Role
+
+1. Go to **Datacenter → Permissions → Roles** and click **Create**.
+2. Name the role (e.g. `KitchenDriver`).
+3. Select these privileges:
+   - `VM.Allocate`, `VM.Clone`, `VM.Audit`, `VM.PowerMgmt`
+   - `VM.Config.CPU`, `VM.Config.Memory`, `VM.Config.Disk`, `VM.Config.Network`
+   - `Datastore.AllocateSpace`, `Datastore.Audit`
+   - `Pool.Allocate` (only if you use the `pool` config option)
+4. Click **Create**.
+
+### Create a User (optional)
+
+You can use an existing user or create a dedicated one:
+
+1. Go to **Datacenter → Permissions → Users** and click **Add**.
+2. Set **User name** (e.g. `kitchen`), **Realm** to `pam` or `pve`, and a password.
+3. Click **Add**.
+
+### Create an API Token
+
+1. Go to **Datacenter → Permissions → API Tokens** and click **Add**.
+2. Select the user, set a **Token ID** (e.g. `kitchen-token`).
+3. **Uncheck** "Privilege Separation" — the token inherits the user's permissions.
+4. Click **Add** and copy the displayed secret. It is shown only once.
+
+The resulting token ID for `.kitchen.yml` is `kitchen@pam!kitchen-token`.
+
+### Assign Permissions
+
+1. Go to **Datacenter → Permissions** and click **Add → User Permission**.
+2. Set **Path** to `/` (or scope to `/vms` and `/storage` as needed).
+3. Select the user and the `KitchenDriver` role.
+4. Check **Propagate**.
+5. Click **Add**.
+
+### Template
+
+The template VM must have `qemu-guest-agent` installed and enabled. The driver uses the guest agent to detect the VM's IP address after boot.
+
+## Development
+
+```sh
+make spec    # run tests
+make style   # run rubocop
+make         # run both
+make install # build and install the gem
+```
+
+## License
+
+Apache-2.0

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

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'uri'
+require 'openssl'
+require 'kitchen'
+
+module Kitchen
+  module Driver
+    class Proxmox < Kitchen::Driver::Base
+      # HTTP client for the Proxmox VE REST API.
+      # Authenticates via API tokens. Provides convenience
+      # methods for VM lifecycle operations.
+      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('/')
+          @token_id = token_id
+          @token_secret = token_secret
+          @ssl_verify = ssl_verify
+        end
+
+        def next_vm_id
+          get('/api2/json/cluster/nextid')
+        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 }
+          body[:name] = options[:name] if options[:name]
+          body[:pool] = options[:pool] if options[:pool]
+          body[:storage] = options[:storage] if options[:storage]
+          post("/api2/json/nodes/#{node}/qemu/#{template_id}/clone", body)
+        end
+
+        def configure_vm(node:, vm_id:, cpus: nil, memory: nil, network_bridge: nil)
+          body = {}
+          body[:cores] = cpus if cpus
+          body[:memory] = memory if memory
+          body[:net0] = "virtio,bridge=#{network_bridge}" if network_bridge
+          return nil if body.empty?
+
+          put("/api2/json/nodes/#{node}/qemu/#{vm_id}/config", body)
+        end
+
+        def start_vm(node:, vm_id:)
+          post("/api2/json/nodes/#{node}/qemu/#{vm_id}/status/start")
+        end
+
+        def stop_vm(node:, vm_id:)
+          post("/api2/json/nodes/#{node}/qemu/#{vm_id}/status/stop")
+        end
+
+        def destroy_vm(node:, vm_id:, purge: true)
+          params = purge ? { purge: 1 } : {}
+          delete("/api2/json/nodes/#{node}/qemu/#{vm_id}", params)
+        end
+
+        def vm_status(node:, vm_id:)
+          get("/api2/json/nodes/#{node}/qemu/#{vm_id}/status/current")
+        end
+
+        def vm_config(node:, vm_id:)
+          get("/api2/json/nodes/#{node}/qemu/#{vm_id}/config")
+        end
+
+        def task_status(node:, upid:)
+          encoded = URI.encode_www_form_component(upid)
+          get("/api2/json/nodes/#{node}/tasks/#{encoded}/status")
+        end
+
+        def wait_for_task(node:, upid:, timeout: 300, interval: 2)
+          deadline = Time.now + timeout
+          loop do
+            status = task_status(node:, upid:)
+            return status if status['status'] == 'stopped'
+            raise "Task timeout after #{timeout}s: #{upid}" if Time.now > deadline
+
+            sleep interval
+          end
+        end
+
+        def agent_network_interfaces(node:, vm_id:)
+          get("/api2/json/nodes/#{node}/qemu/#{vm_id}/agent/network-get-interfaces")
+        end
+
+        def list_nodes
+          get('/api2/json/nodes')
+        end
+
+        def list_templates
+          resources = get('/api2/json/cluster/resources?type=vm')
+          resources.select { |r| r['template'] == 1 }
+        end
+
+        private
+
+        def get(path)
+          request(Net::HTTP::Get, path)
+        end
+
+        def post(path, body = {})
+          request(Net::HTTP::Post, path, body)
+        end
+
+        def put(path, body = {})
+          request(Net::HTTP::Put, path, body)
+        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))
+        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)
+          end
+
+          handle_response(http.request(req))
+        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
+        end
+
+        def apply_headers(req)
+          req['Authorization'] = "PVEAPIToken=#{token_id}=#{token_secret}"
+          req['Accept'] = 'application/json'
+        end
+
+        def handle_response(response)
+          raise "Proxmox API error #{response.code}: #{response.body}" unless response.is_a?(Net::HTTPSuccess)
+
+          JSON.parse(response.body)['data']
+        end
+      end
+    end
+  end
+end

data/lib/kitchen/driver/proxmox.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require 'kitchen'
+require 'securerandom'
+require_relative 'proxmox_version'
+require_relative 'proxmox/api_client'
+
+module Kitchen
+  module Driver
+    # Proxmox VE driver for Test Kitchen.
+    #
+    # Manages VM lifecycle via the Proxmox REST API:
+    # - create: clone a template, configure hardware, start, wait for IP
+    # - destroy: stop and delete the VM
+    class Proxmox < Kitchen::Driver::Base
+      kitchen_driver_api_version 2
+
+      plugin_version Kitchen::Driver::PROXMOX_VERSION
+
+      required_config :proxmox_url
+      required_config :proxmox_token_id
+      required_config :proxmox_token_secret
+      default_config :node, nil
+      default_config :template_id, nil
+
+      default_config :ssl_verify, true
+      default_config :pool, nil
+      default_config :vm_name_prefix, 'kitchen-'
+      default_config :cpus, 1
+      default_config :memory, 1024
+      default_config :storage, nil
+      default_config :network_bridge, 'vmbr0'
+      default_config :clone_timeout, 300
+      default_config :start_timeout, 300
+      default_config :ip_wait_timeout, 120
+
+      def create(state)
+        return if state[:vm_id]
+
+        validate_config!
+        clone_and_start(state)
+      end
+
+      def destroy(state)
+        return unless state[:vm_id]
+
+        vm_id = state[:vm_id]
+        info("Destroying Proxmox VM #{state[:vm_name]} (#{vm_id})...")
+        safe_stop_vm(vm_id)
+        api_client.destroy_vm(node: config[:node], vm_id:)
+        clear_state(state)
+        info("Proxmox VM #{vm_id} destroyed.")
+      end
+
+      private
+
+      def api_client
+        @api_client ||= ApiClient.new(
+          base_url: config[:proxmox_url],
+          token_id: config[:proxmox_token_id],
+          token_secret: config[:proxmox_token_secret],
+          ssl_verify: config[:ssl_verify]
+        )
+      end
+
+      def clone_and_start(state)
+        info("Creating Proxmox VM from template #{config[:template_id]}...")
+
+        vm_id = allocate_vm_id
+        vm_name = generate_vm_name(instance.name)
+
+        clone_template(vm_id, vm_name)
+        configure_hardware(vm_id)
+        start_and_wait_for_ip(state, vm_id)
+
+        state[:vm_id] = vm_id
+        state[:vm_name] = vm_name
+
+        info("Proxmox VM #{vm_name} (#{vm_id}) created.")
+      end
+
+      def allocate_vm_id
+        Integer(api_client.next_vm_id)
+      end
+
+      def generate_vm_name(suite_name)
+        "#{config[:vm_name_prefix]}#{suite_name}-#{SecureRandom.hex(4)}"
+      end
+
+      def clone_template(vm_id, vm_name)
+        node = config[:node]
+        upid = api_client.clone_vm(
+          node:, template_id: config[: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)
+        api_client.configure_vm(
+          node: config[:node],
+          vm_id:,
+          cpus: config[:cpus],
+          memory: config[:memory],
+          network_bridge: config[:network_bridge]
+        )
+      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)
+        state[:hostname] = ip
+      end
+
+      def stop_vm(vm_id)
+        status = api_client.vm_status(node: config[: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)
+      end
+
+      def safe_stop_vm(vm_id)
+        stop_vm(vm_id)
+      rescue ::StandardError => e
+        warn("Failed to stop VM #{vm_id}: #{e.message}")
+      end
+
+      def wait_for_ip(vm_id)
+        deadline = Time.now + config[:ip_wait_timeout]
+        loop do
+          ip = fetch_ip(vm_id)
+          return ip if ip
+          raise "Timed out waiting for IP on VM #{vm_id}" if Time.now > deadline
+
+          sleep 3
+        end
+      end
+
+      def fetch_ip(vm_id)
+        interfaces = api_client.agent_network_interfaces(
+          node: config[:node],
+          vm_id:
+        )
+        return nil unless interfaces.is_a?(Hash) && interfaces['result']
+
+        extract_ipv4_from_interfaces(interfaces['result'])
+      rescue ::StandardError
+        nil
+      end
+
+      def extract_ipv4_from_interfaces(interfaces)
+        interfaces.each do |iface|
+          next if iface['name'] == 'lo'
+
+          (iface['ip-addresses'] || []).each do |addr|
+            return addr['ip-address'] if addr['ip-address-type'] == 'ipv4'
+          end
+        end
+        nil
+      end
+
+      def validate_config!
+        errors = []
+        errors << validate_node if config[:node].nil?
+        errors << validate_template_id if config[:template_id].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"
+        end
+        msg
+      end
+
+      def validate_template_id
+        msg = "Missing required config: template_id\n"
+        msg + format_template_list
+      end
+
+      def format_template_list
+        templates = api_client.list_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)
+        state.delete(:vm_id)
+        state.delete(:vm_name)
+        state.delete(:hostname)
+      end
+    end
+  end
+end

data/lib/kitchen/driver/proxmox_version.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Kitchen
+  module Driver
+    PROXMOX_VERSION = begin
+      # When loaded from a git checkout, derive the version from git tags.
+      # When installed as a gem, git isn't available so fall back to the
+      # version baked into the gemspec at build time.
+      dir = File.expand_path('../../..', __dir__)
+      if File.directory?(File.join(dir, '.git'))
+        tag = `git -C #{dir} describe --tags --match 'v*' 2>/dev/null`.strip
+        tag.empty? ? '0.0.0' : tag.sub(/^v/, '').sub(/-(\d+)-g/, '.\1.dev.')
+      else
+        Gem.loaded_specs['kitchen-proxmox']&.version&.to_s || '0.0.0'
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: kitchen-proxmox
+version: !ruby/object:Gem::Version
+  version: 0.0.3
+platform: ruby
+authors:
+- Richard Nixon
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-03-30 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.
+email:
+- richard.nixon@btinternet.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/kitchen/driver/proxmox.rb
+- lib/kitchen/driver/proxmox/api_client.rb
+- lib/kitchen/driver/proxmox_version.rb
+homepage: https://github.com/trickyearlobe-chef/kitchen-proxmox
+licenses:
+- Apache-2.0
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/trickyearlobe-chef/kitchen-proxmox
+  bug_tracker_uri: https://github.com/trickyearlobe-chef/kitchen-proxmox/issues
+  changelog_uri: https://github.com/trickyearlobe-chef/kitchen-proxmox/blob/main/CHANGELOG.md
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.27
+signing_key: 
+specification_version: 4
+summary: Test Kitchen driver for Proxmox VE
+test_files: []