diff --git a/README.md b/README.md index ff7e25e..5eddebf 100644 --- a/README.md +++ b/README.md @@ -1,36 +1,66 @@ # NetBox VMware Importer -NetBox plugin zum Synchronisieren von VMware vSphere/vCenter VMs nach NetBox. +Synchronise virtual machines from VMware vSphere / vCenter into NetBox. -## Kompatibilitaet +| | | +|---|---| +| **Plugin name** | `netbox_vmware_importer` | +| **Package** | `netbox-vmware-importer` | +| **NetBox** | `4.6.5` – `4.7.1` | +| **Python** | `>=3.12` | +| **Repository** | | -Version `0.3.1` ist fuer NetBox `4.6.5` bis `4.6.8` freigegeben. +## Features -## Funktionen +- Manage vCenter/ESXi endpoints directly in the NetBox web UI +- Tenant, site and NetBox cluster per endpoint +- Manual synchronisation via button +- Optional automatic synchronisation on a minute interval +- Imports VM name, status, vCPU, RAM, disk, platform, interfaces, MAC addresses and IPs +- MAC addresses are created as NetBox MAC address objects on the VM interface and set as primary MAC +- Virtual disks are documented as NetBox virtual disks with size and backing info +- Primary IPv4/IPv6 is set from the first guest IP found +- Multi-tenant-safe VM matching via `name + cluster` -- vCenter/ESXi-Ziele direkt in der NetBox-Weboberflaeche pflegen -- Pro Ziel Tenant, Site und NetBox-Cluster hinterlegen -- Manuelle Synchronisation per Button -- Optionale automatische Synchronisation ueber ein Minutenintervall -- Import von VM-Name, Status, vCPU, RAM, Disk, Plattform, Interfaces, MAC-Adressen und IPs -- MAC-Adressen werden als NetBox MAC Address Objekte am VM-Interface angelegt und als primaere MAC gesetzt -- Virtuelle Festplatten werden als NetBox Virtual Disks mit Groesse und Backing-Info dokumentiert -- Primaere IPv4/IPv6 wird anhand der ersten gefundenen Gast-IP gesetzt -- Multi-Tenant-sicherer VM-Abgleich ueber `name + cluster` +The plugin intentionally does **not** delete orphaned VMs, interfaces or IP +addresses. This keeps rollouts conservative and avoids data loss when VMware +guest data is incomplete. -Das Plugin loescht bewusst keine verwaisten VMs, Interfaces oder IP-Adressen. Damit bleibt der erste Rollout konservativ und vermeidet Datenverlust, wenn VMware-Gastdaten unvollstaendig sind. +## Compatibility + +- NetBox `4.6.5` – `4.7.1` +- Python `>=3.12` +- Dependencies installed automatically: `pyvmomi`, `cryptography` ## Installation -Im Python-Environment der NetBox-Installation: +All paths assume a standard installation under `/opt/netbox`. + +### 1. Install the package ```bash -pip install git+https://git.mrblake.cc/MrBlake/NetBox-VM-Import.git +/opt/netbox/venv/bin/pip install --upgrade --force-reinstall \ + "git+https://git.mrblake.cc/MrBlake/NetBox-VM-Import.git@main" ``` -NetBox selbst ist keine `pip`-Dependency des Plugins. Das Plugin wird im vorhandenen NetBox-Virtualenv installiert und bringt nur externe Bibliotheken wie `pyvmomi` und `cryptography` mit. +For reproducible production installs, replace `main` with a release tag or a +full commit ID. -In `configuration.py` aktivieren: +### 2. Add the plugin to `local_requirements.txt` + +This makes `upgrade.sh` reinstall the plugin automatically on every NetBox upgrade: + +```bash +grep -qxF "git+https://git.mrblake.cc/MrBlake/NetBox-VM-Import.git@main" /opt/netbox/local_requirements.txt \ + || echo "git+https://git.mrblake.cc/MrBlake/NetBox-VM-Import.git@main" | sudo tee -a /opt/netbox/local_requirements.txt +``` + +If the repository is private, the NetBox server needs a read-only deploy token +or an SSH key. Do not store credentials in `local_requirements.txt`. + +### 3. Enable the plugin + +In `/opt/netbox/netbox/netbox/configuration.py`: ```python PLUGINS = [ @@ -38,37 +68,85 @@ PLUGINS = [ ] ``` -Danach Migrationen anwenden und NetBox/RQ neu starten: +If other plugins are already configured, add `netbox_vmware_importer` to the +existing list. + +### 4. Apply migrations, collect static files, restart ```bash -python manage.py migrate netbox_vmware_importer +cd /opt/netbox/netbox +/opt/netbox/venv/bin/python manage.py migrate netbox_vmware_importer +/opt/netbox/venv/bin/python manage.py collectstatic --no-input sudo systemctl restart netbox netbox-rq ``` -## Upgrade-Hinweis +## Update -Version `0.3.1` behebt instabile Django-Migration-Dependencies aus frueheren Releases. Wenn `python manage.py migrate` mit `InconsistentMigrationHistory` fuer `netbox_vmware_importer.0001_initial` fehlschlaegt, zuerst das Plugin auf `0.3.1` aktualisieren und danach `python manage.py migrate --plan` sowie `python manage.py migrate` normal ausfuehren. Manuelle Aenderungen an `django_migrations` oder `--fake` sollten nicht notwendig sein. +```bash +/opt/netbox/venv/bin/pip install --upgrade --force-reinstall \ + "git+https://git.mrblake.cc/MrBlake/NetBox-VM-Import.git@main" -## Nutzung +cd /opt/netbox/netbox +/opt/netbox/venv/bin/python manage.py migrate netbox_vmware_importer +/opt/netbox/venv/bin/python manage.py collectstatic --no-input +sudo systemctl restart netbox netbox-rq +``` -1. In NetBox unter `VMware Import > Endpoints` ein Ziel anlegen. -2. vCenter/ESXi Host, Port, Benutzername und Passwort eintragen. -3. Tenant, Site und Cluster fuer den Kunden auswaehlen. -4. Optional Regex-Filter und Sync-Intervall setzen. -5. Auf der Detailseite `Sync jetzt starten` ausfuehren. +`--force-reinstall` makes pip pick up branch changes even if the package +version has not been bumped. -Wenn `Sync interval minutes` gesetzt ist, prueft ein Systemjob alle fuenf Minuten, welche VMware-Endpoints faellig sind, und stellt die eigentlichen Sync-Jobs in die Queue. +When NetBox itself is upgraded, `upgrade.sh` reinstalls the plugin from +`local_requirements.txt` and runs migrations and `collectstatic`: -## Legacy-Proxmox-Endpoints +```bash +sudo /opt/netbox/upgrade.sh +sudo systemctl restart netbox netbox-rq +``` -Proxmox-Unterstuetzung wurde entfernt. Alte Proxmox-Endpoints aus frueheren Plugin-Versionen bleiben in der Liste und Detailansicht sichtbar, damit sie geloescht werden koennen. Sie koennen nicht mehr bearbeitet, neu angelegt oder synchronisiert werden. +### Upgrade note for 0.3.1 -## Sicherheit +Version `0.3.1` fixes unstable Django migration dependencies from earlier +releases. If `migrate` fails with `InconsistentMigrationHistory` for +`netbox_vmware_importer.0001_initial`, first update the plugin to `0.3.1`, then +run `manage.py migrate --plan` and `manage.py migrate` normally. Manual changes +to `django_migrations` or `--fake` should not be necessary. -Das Endpoint-Passwort wird verschluesselt in der Plugin-Tabelle gespeichert. Der Schluessel wird aus `SECRET_KEY` abgeleitet. Wenn `SECRET_KEY` rotiert wird, muessen die Secrets in den Endpoints erneut gesetzt werden. +## Uninstall -Fuer sehr strenge Umgebungen ist ein externer Secret-Store wie Vault als naechster sinnvoller Ausbaupunkt vorgesehen. +1. Remove `"netbox_vmware_importer"` from `PLUGINS`. +2. Remove the line from `/opt/netbox/local_requirements.txt`. +3. Uninstall the package and restart NetBox: -## Datenqualitaet +```bash +/opt/netbox/venv/bin/pip uninstall netbox-vmware-importer +sudo systemctl restart netbox netbox-rq +``` -IP-Adressen kommen aus den VMware Guest Tools. Ohne laufende bzw. aktuelle Guest Tools koennen Interfaces und IPs fehlen oder veraltet sein. +## Usage + +1. In NetBox, create an endpoint under **VMware Import > Endpoints**. +2. Enter the vCenter/ESXi host, port, username and password. +3. Select tenant, site and cluster for the customer. +4. Optionally set regex filters and a sync interval. +5. On the detail page, click **Start sync now**. + +If **Sync interval minutes** is set, a system job checks every five minutes +which endpoints are due and enqueues the actual sync jobs. + +### Legacy Proxmox endpoints + +Proxmox support has been removed. Old Proxmox endpoints from earlier versions +remain visible in the list and detail view so they can be deleted; they can no +longer be edited, created or synchronised. + +## Security + +The endpoint password is stored encrypted in the plugin table. The key is +derived from `SECRET_KEY`; if `SECRET_KEY` is rotated, the endpoint secrets must +be set again. For very strict environments, an external secret store such as +Vault is the next planned extension. + +## Data quality + +IP addresses come from VMware Guest Tools. Without running or current Guest +Tools, interfaces and IPs may be missing or outdated.