MrBlake/NetBox-VM-Import
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: rewrite README in English with standard structure

Browse Source 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
MrBlake
2026-09-30 13:36:48 +02:00
co-authored by Claude Opus 5.5
parent a474f79f40
commit d739e91339
1 changed files with 114 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+114 -36
View File
@@ -1,36 +1,66 @@
# NetBox VMware Importer # 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** | <https://git.mrblake.cc/MrBlake/NetBox-VM-Import> |
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 The plugin intentionally does **not** delete orphaned VMs, interfaces or IP
- Pro Ziel Tenant, Site und NetBox-Cluster hinterlegen addresses. This keeps rollouts conservative and avoids data loss when VMware
- Manuelle Synchronisation per Button guest data is incomplete.
- 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`
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 ## Installation
Im Python-Environment der NetBox-Installation: All paths assume a standard installation under `/opt/netbox`.
### 1. Install the package
```bash ```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 ```python
PLUGINS = [ 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 ```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 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. `--force-reinstall` makes pip pick up branch changes even if the package
2. vCenter/ESXi Host, Port, Benutzername und Passwort eintragen. version has not been bumped.
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.
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.