Merge pull request #35 from netboxlabs/features-2025.11.01

v2025.11.01 release

Author: netboxlabs-nvp

README.md

@@ -39,15 +39,11 @@ If you see errors like this...
 
  Try uninstalling `mkdocs` from your package manager, (e.g. `brew uninstall mkdocs`) and just using the version installed by `pip`. It seems that `mkdocs` doesn't like it when you've installed it using different methods.
 
-# What's New in 1.2.0
-  - Adds LXC support
-  - Adds the ability to define 'vmid' for both VM and LXC, rather than taking a default value from Proxmox
-  - Adds "discovery" of Proxmox VM and LXC disks and auto-creation of VM disk objects in NetBox
-  - Adds rudimentary Proxmox VM and LXC discovery through convenience script
-  - Adds AWX initial setup through convenience script (uses awxkit)
-  - Convenience script changes to accommodate LXC requirements
-  - Can dynamically build webhooks and event rules from current AWX state through convenience script
-  - Adds customization changes for LXC-specific requirements
+# What's New in 2025.11.01
+  - Switches to calendar (as opposed to semantic) versioning
+  - Adds Proxmox cluster and node(s) discovery through a new convenience script
+  - Adds Proxmox VM migration to alternate Proxmox node(s) through events
+  - Adds [NetBox Branching](https://netboxlabs.com/docs/extensions/branching/) support for Proxmox node and VM discovery
 
 # Developers
 - Nate Patwardhan <[email protected]>
@@ -56,9 +52,10 @@ If you see errors like this...
 
 ## Known Issues
 - *Only* supports SCSI disk types (this is possibly fine as Proxmox predomininantly provisions disks as SCSI)
-- Does not currently support Proxmox VM creation to a Proxmox cluster, but is only node-based
+- LXC migration is not supported for myriad reasons
+- Proxmox "tags" are not supported (seeking community feedback around use cases)
 
 ## Roadmap -- Delivery
+- Use of NetBox Custom Objects for NetBox > 4.4
+- DNS update support via gss-tsig (requires NetBox `netbox-dns` plugin)
 - Integration with NetBox Discovery/Assurance
-- DNS update support (requires NetBox `netbox-dns` plugin)
-- Maybe evolve into to a NetBox plugin for Proxmox

ansible-tasks/collect-proxmox-vm.yml

@@ -1,5 +1,5 @@
 proxmox_api_config:
-  node: pve # or your Proxmox node name
+  node: pve # or *a* Proxmox node name (even if clustered)
   api_host: proxmox-ip-or-hostname
   api_port: 8006
   api_user: proxmox_api_user
@@ -13,11 +13,20 @@ netbox_api_config:
   api_token: netbox_api_secret_token
   verify_ssl: false # or true, up to you
 proxmox:
-  cluster_name: proxmox-ve
+  cluster_name: name-of-proxmox-cluster #(no longer required as it will be discovered)
+  node_commands:
+    dmidecode_command: /usr/sbin/dmidecode # required: where dmidecode lives on your system
+    lshw_command: /usr/bin/lshw            # required: where lshw lives on your system
+    ethtool_command: /usr/sbin/ethtool     # required: where ethtool lives on your system
+    ipaddr_command: /usr/sbin/ip -br a     # required: where ip command lives on your system
 netbox:
-  cluster_role: Proxmox
-  vm_role: "Proxmox VM"
-  lxc_role: "Proxmox LXC"
+  branch: name-of-branch-where-you-want-to-import-data # optional
+  branch_timeout: integer-to-represent-seconds-for-branch-operation # optional
+  site: Home Lab # optional
+  cluster_role: Proxmox # required
+  device_role: "Proxmox node" # required
+  vm_role: "Proxmox VM" # required
+  lxc_role: "Proxmox LXC" # required
 automation_type: choices are ansible_automation or flask_application
 ansible_automation:
   host: name or ip of AWX/Tower/AAP host

conf.d/netbox_setup_objects.yml-sample

@@ -251,7 +251,8 @@ When you create *any* template in AWX for Proxmox automation, you will need to s
 | awx-proxmox-remove-vm-disk.yml | Removes a non-OS disk (i.e. not scsi0) from a Proxmox VM |
 | awx-proxmox-remove-vm.yml | Removes a Proxmox VM |
 | awx-proxmox-resize-vm-disk.yml | Resizes a Proxmox VM disk |
-| awx-proxmox-set-ipconfig0.yml | Sets ipconfig0 for Proxmox VM and adds ssh key|
+| awx-proxmox-set-ipconfig0.yml | Sets ipconfig0 for Proxmox VM and adds ssh key |
 | awx-proxmox-start-vm.yml | Starts Proxmox VM |
 | awx-proxmox-stop-vm.yml | Stops Proxmox VM |
+| awx-proxmox-migrate-vm.yml | Migrates Proxmox VM to an alternate Proxmox node |
 

docs/configure-awx-aap.md

@@ -22,7 +22,7 @@ Regardless of whether you are using a Flask (or other) application for Proxmox a
 
 ### Flask Application
 
-As noted [here](#initial-configuration-flask-application-python), you will need to have a running Flask application *before* you can start handling events (i.e. object changes) inside of NetBox.
+You will need to have a running Flask application *before* you can start handling events (i.e. object changes) inside of NetBox.
 
 #### Automated Webhook and Event Rules Configuration
 

docs/netbox-event-rules-and-webhooks-flask.md

@@ -0,0 +1,19 @@
+# NetBox and Proxmox Node Migration
+
+It is well known that Proxmox can support both clustering and single nodes.  When using a Proxmox cluster, one can select a respective virtual machine (VM) and migrate the VM to any available Proxmox nodes.
+
+As NetBox requires that virtual machines are assigned to a virtual cluster, this gives you the ability to migrate virtual machines between Proxmox nodes.  `netbox-proxmox-automation` 2025.11.01 implements an *experimental* feature that allows you to migrate Proxmox VMs between Proxmox nodes, simply when you make changes to the intended state of a Proxmox VM in NetBox.  This is done through event-driven automation in `netbox-proxmox-automation`, such that changing the assigned `proxmox_node` custom field in NetBox will trigger an event -- and this event will migrate the VM from the existing Proxmox node to a specified Proxmox node.  Whether you are using the included Flask application or are using AWX/Tower/AAP, both automation strategies should work for this purpose.
+
+*NOTE: LXC migration is not supported.  This is a technical blocker based on Proxmox currently.*
+
+*NOTE 2: This only works for NetBox (Proxmox) VMs that are in a state of 'active' or 'offline'*
+
+To do this, you must do three things before attempting to induce Proxmox VM migration by way of NetBox.
+
+1. you have a running Proxmox cluster or clusters
+2. you have created a `netbox-proxmox-automation` configuration for each of your Proxmox clusters
+3. you have created all custom fields with the `netbox_setup_objects_and_custom_fields.py` script
+4. you have defined your automation strategy and run the `netbox_setup_webhook_and_event_rules.py` script
+5. your NetBox is up to date with VM and customization information
+
+Once you have done the above, all that it takes to induce this automation is to select a Proxmox VM in NetBox, *edit* that object, toggle the name of the `proxmox_node` custom field, then click the Save button.  This will kick off the (node) migration in Proxmox.

docs/proxmox-and-node-migration.md

@@ -0,0 +1,51 @@
+# Discover Proxmox Clusters and Nodes
+
+Starting with `netbox-proxmox-automation` 2025.11.01, you are able to discover Proxmox cluster and nodes information by way of a convenience script, `netbox-discover-proxmox-cluster-and-nodes.py`.  `netbox-discover-proxmox-cluster-and-nodes.py` is located under the `setup` directory; you should run this script *before* attempting to "discover" VMs and/or LXCs and importing them into NetBox.
+
+*Note that you must follow the steps in [this document](./netbox-customization.md) before running this convenience script!*
+
+In NetBox, *all* virtual machines, or in the parlance of Proxmox (virtual machines and/or LXC), are required to be associated with a virtualization cluster in NetBox.  Therefore, whether you have a single-node Proxmox installation or have implemented a Proxmox cluster, *all* of your Proxmox installations will be reflected as clusters in NetBox.  Given that, `netbox-discover-proxmox-cluster-and-nodes.py` collects the following information about your Proxmox cluster and nodes.
+
+  - Make and manufacturer of underlying hardware that's running Proxmox
+  - CPU and memory information for each node that's running Proxmox
+  - Serial number
+  - Network interfaces (name, type, MAC address, enabled)
+  - IP addresses
+  - Proxmox version and release level, i.e. Platform
+
+*You will need the following commands to be installed on your Proxmox node(s) for this to work, and you'll need root access (direct or via sudo) for this to work*:
+
+  - dmidecode
+  - 'ethtool' command
+  - 'ip' command
+  - lshw
+
+After collecting this information, `netbox-discover-proxmox-cluster-and-nodes.py` turns around and creates the related objects in NetBox.
+
+  - Manufacturer
+  - Device Roles
+  - Platforms
+  - Device Types
+  - Devices
+  - IP Addresses (for Devices with interface mappings)
+  - Virtual Machine Cluster (with Device mappings)
+
+Once the Proxmox node(s) has/have been added to NetBox, you can start discovering VMs and LXCs in Proxmox.
+
+`netbox-proxmox-automation` has a sample config file under the `conf.d` directory that's called `netbox_setup_objects.yml-sample`.  Make a copy of `netbox_setup_objects.yml-sample` to the location of your choice.  Then run `./setup/netbox-discover-proxmox-cluster-and-nodes.py` as follows.
+
+```
+shell$ cd /path/to/netbox-proxmox-automation/setup
+
+shell$ deactivate
+
+shell$ python3 -m venv venv
+
+shell$ source venv/bin/activate
+
+shell$ pip install -r requirements.txt
+
+shell$ ./netbox-discover-proxmox-cluster-and-nodes.py --config ../path/to/your-config.yml
+```
+
+*Note that you will need one config file for each Proxmox cluster, or in the case of multiple, single Proxmox nodes, you will need a config file for each of those.*

docs/proxmox-discover-clusters-and-nodes.md

@@ -17,11 +17,11 @@ For LXC automation, `netbox-proxmox-automation` uses LXC (container images) on P
 
 NetBox models VMs in an intuitive way.  You can define roles for VMs, such as for Proxmox, and from there you can define both VM state (Staged, Active, Offline, etc) and other resources like vcpus, memory, network configuration, VM disks, and more (through customizations in NetBox).
 
-This automation is based on the premise(s) that:
+This automation *requires* that:
 
   1. You are using Python (version 3)
-  2. You are using NetBox 4.1.0 or newer (NetBox 3.7.x should also work)
-  3. You have a running Proxmox instance or cluster
+  2. You are using NetBox 4.3.7 or newer
+  3. You are running Proxmox 8.4.x single node or cluster (Proxmox 9.x is *not* tested)
   4. You have a running [AWX](https://github.com/ansible/awx) instance or are running [your own web application](https://github.com/netboxlabs/netbox-proxmox-automation/tree/main/netbox-event-driven-automation-flask-app) to handle webhooks and event rules
   5. You have converted a cloud-init image to a Proxmox VM template
   6. Your Promox VM template(s) has/have qemu-guest-agent installed, and that qemu-guest-agent has been enabled via cloud-init
@@ -31,7 +31,7 @@ This automation is based on the premise(s) that:
 
 ## What this implementation *is not*
 
-`netbox-proxmox-automation` is not currently a NetBox plugin, but this may change.
+`netbox-proxmox-automation` is not a NetBox plugin, and future aspirations of this implementation will employ [custom objects](https://github.com/netboxlabs/netbox-custom-objects).
 
 [ProxBox](https://github.com/netdevopsbr/netbox-proxbox) is a neat implementation of pulling information from Proxmox into NetBox.  ProxBox has its place, most certainly, but what it does is *not* the aim of `netbox-proxmox-automation`.