# napalm-vmware NAPALM drivers for VMware vSphere, speaking the vSphere API through [pyVmomi](https://pypi.org/project/pyvmomi/): | Driver | Endpoint | Device in netOrk | |---|---|---| | `vmware_esxi` | one ESXi host, addressed directly | the host: its vmnics, vmkernel NICs, sensors, VMs | | `vmware_vcenter` | a vCenter Server | the vCenter: every VM it manages, with the ESXi host as the VM's `node` | Both declare the `hypervisor` role from [napalm-device-types](https://git.netork.io/NAPALM/napalm-device-types). ## Status Tested against govmomi's **vcsim** simulator, in both ESXi and vCenter mode, including real power and snapshot tasks. **Not yet tested against real hardware**: see [Harvesting fixtures](#harvesting-fixtures). | Method | ESXi | vCenter | Source | |---|---|---|---| | `get_facts` | ✅ | ✅ | host hardware + product / `about` | | `get_interfaces`, `get_interfaces_ip` | ✅ | `{}` | vmnics + vmks | | `get_lldp_neighbors` | ✅ | `{}` | `QueryNetworkHint` (LLDP, else CDP) | | `get_environment` | ✅ | ✅ (per host) | quick stats + hardware sensors | | `get_vms` | ✅ | ✅ | VMs, templates excluded | | `get_vm_config` | ✅ | ✅ | virtual hardware | | `start_vm`, `stop_vm`, `reboot_vm`, `suspend_vm` | ✅ | ✅ | power tasks / VMware Tools | | `get_vm_snapshots`, `create/delete/rollback_vm_snapshot` | ✅ | ✅ | snapshot tree | | `get_vm_storage_pools` | ✅ | ✅ | datastores | | `get_virtual_networks` | ✅ | ✅ (+ dvPortgroups) | port groups | | `get_hypervisor_hosts` | ✅ | ✅ | connection state, maintenance mode, config issues, managing vCenter | | `get_licenses` | ✅ | ✅ | license manager: name and edition key, never the key | | `get_clusters` | ✅ (the host, a cluster of one) | ✅ (each cluster and standalone host) | compute resources, hosts, datastores, port groups | | `reboot_host` | ✅ (maintenance mode only) | — | `RebootHost_Task` | | `create_vm_from_cloud_init`, `destroy_vm`, `get_vm_status` | ✅ | ✅ | see [Provisioning](#provisioning) | | `get_network_targets`, `get_image_storages` | ✅ | ✅ | port groups, datastores | | VIBs, updates | — | — | not yet | Unverified assumptions, to be checked against real hardware: - the HTTP fingerprints (`vmware esxi` on the Host Client page, `vcenter` on the vSphere Client page) - the free vSphere Hypervisor license reporting `editionKey` `esxBasic` ## Requirements - HTTPS (443) to the host or vCenter. No SSH. - An account that may read the inventory. For power and snapshot actions it also needs *Virtual machine → Interaction → Power on/off/Reset/Suspend* and *Virtual machine → Snapshot management*. - For provisioning: `qemu-img` (package `qemu-utils`) where the driver runs, and HTTPS from there to every ESXi host that may receive a VM -- through a vCenter the disk upload goes straight to the host, not via the vCenter. - **A paid license for any write.** On the free vSphere Hypervisor license the API is read-only; the driver reports `vmware_api_read_only` and turns the refusal into a readable error. ## Install Python 3.12 or later. ```bash pip install napalm-vmware ``` ## Usage ```python from napalm_vmware import VmwareEsxiDriver driver = VmwareEsxiDriver( "esx01.example.lan", "root", "secret", optional_args={"verify_ssl": False} ) driver.open() print(driver.get_facts()) for vm in driver.get_vms(): print(vm["name"], vm["status"], vm["vmid"]) driver.close() ``` `optional_args`: `port` (default 443), `verify_ssl` / `ssl_verify` (default `True`; ESXi ships a self-signed certificate), `image_cache_dir` (where converted cloud images are kept; default a directory under the system temp dir). Other keys are ignored. VMs are addressed by name, by `vmid`, or by MoRef (`vm-42`). A name shared by two VMs is refused rather than guessed. ## Tests The rules are in [STANDARDS.md](https://git.netork.io/NAPALM/driver-standard/src/branch/main/STANDARDS.md). ```bash python -m venv .venv && .venv/bin/pip install -e ".[dev]" .venv/bin/pytest --cov # unit tests, no network docker run -d --rm -p 127.0.0.1:8989:8989 vmware/vcsim -l 0.0.0.0:8989 docker run -d --rm -p 127.0.0.1:8990:8989 vmware/vcsim -esx -l 0.0.0.0:8989 VCSIM_VCENTER_PORT=8989 VCSIM_ESXI_PORT=8990 pytest -m vcsim ``` ## Harvesting fixtures ```bash tools/harvest.py esx01.example.lan root esxi8-dell # prompts for the password tools/sanitize.py tools/harvest-out/esxi8-dell.json > tests/fixtures/esxi8-dell.json ``` `harvest.py` reads exactly the property paths in `napalm_vmware/paths.py`, the ones the drivers read. `tools/harvest-out/` is gitignored. Read the sanitised file before committing it. ## Provisioning `create_vm_from_cloud_init` takes the same cloud images netOrk's catalog offers for Proxmox (qcow2/raw): 1. The image is downloaded where the driver runs, its checksum verified (one retry), and converted with `qemu-img` to a streamOptimized VMDK. The VMDK is cached by URL in `image_cache_dir`; the download is not kept. 2. A host is chosen that is connected, not in maintenance mode, and sees the datastore and every requested port group (the named datastore, or the one with the most free space). `node` names the host to use; one that does not exist or does not qualify is refused with ValueError before the download. 3. The VM is created from a minimal OVF descriptor (PVSCSI disk, VMXNET3 NICs) and the disk streamed in over NFC. 4. Requested MACs are pinned, the disk grown to `disk_resize_gb`, and a NoCloud seed ISO (user-data, meta-data, network-config) uploaded next to the VM's files and attached as a CD-ROM on a new SATA controller. 5. The VM is powered on. Any failure after step 3 removes the VM again. A port group fixes its VLAN, so `get_network_targets` reports each one with `kind="portgroup"`, `vlan_aware=False` and its `fixed_vlan_tag`; a NIC asking for a different `vlan_tag` is refused. The guest agent netOrk installs is `open-vm-tools` (`GUEST_AGENTS`), which reports the IP address back. Only Linux guests are provisioned; `guest_os` other than `"linux"` is refused (BSD guests on VMware: NetOrk/netork#801). Unverified until #305: that each distribution's cloud kernel carries the PVSCSI and VMXNET3 drivers. ## Design notes **One seam.** Every read goes through `Inventory.collect(type, paths)`, a PropertyCollector query with explicit paths, and every result is converted by `to_plain()` into dicts, lists and scalars (managed objects become their MoRef, data objects get a `_type`). The parsers in `napalm_vmware/parse/` only ever see that plain form, so a harvested JSON file and a live host feed them identically. Lazy attribute access on pyVmomi objects is avoided on purpose: it fails on some servers where the individual paths work. **`vmid` is the instance UUID** (`config.instanceUuid`). It survives vMotion and re-registration and is unique within a vCenter; a MoRef is none of those. The MoRef is reported alongside as `moref`. **The vCenter device has no interfaces.** The hosts' NICs belong to the hosts. Reporting them on the vCenter would attach their MACs to the wrong device. Add a host with `vmware_esxi` to see its NICs. **Facts, not warnings.** The driver names no warnings. `get_hypervisor_hosts()` and `get_licenses()` report what the endpoint says; whether a host in maintenance mode or the free `esxBasic` edition is a problem is the caller's to decide. The ESXi driver reports `connected` as `None` (a disconnected host could not have answered) and the managing vCenter's address as `managed_by`; under the vCenter driver `managed_by` is `None`, since every host names it.