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 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
- 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.