VMware Storage

[READ] List all datastores with capacity, usage percentage, and accessibility. Use this first for the datastore_name that browse_datastore and scan_datastore_images require. Returns the list envelope: 'items' holds one row per datastore, and 'returned'/'total'/'truncated' state whether the listing is complete. Every datastore is enumerated before limit is applied, so total is the real count and truncated is true only when limit cut rows off.

[READ] Which VMs take the space on one datastore, largest first. Use this for "is this datastore filling up, and who is using it?". datastore_name comes from list_all_datastores. Reads vCenter's own per-VM accounting (storage.perDatastoreUsage), so it is space on disk, not the provisioned VMDK sizes browse_datastore shows. Returns {datastore: {name, type, total_gb, used_gb, free_gb, usage_pct}, items, returned, total, truncated, attributed_gb, unattributed_gb, unmeasured_vms, note}. Each item: name, vm_id, template, committed_gb (on disk), uncommitted_gb (thin headroom it may still grow into), unshared_gb, measured_at. unattributed_gb is used space no VM accounts for: unregistered VMs, orphaned disks, ISOs; find those files with browse_datastore. unmeasured_vms list the datastore but have no usage row, so their space is unknown, not zero.

[READ] Search a datastore folder and all its subfolders for files. Use this for arbitrary files or a glob; prefer scan_datastore_images for deployable images. datastore_name comes from list_all_datastores. Returns the list envelope: 'items' holds one row per file, and 'returned'/'total'/'truncated' state whether the listing is complete. All matches are returned, so truncated is always false.

[READ] Scan a datastore for deployable images (OVA, ISO, OVF, VMDK). Use this for a live scan of one datastore; prefer list_cached_images for a cached answer. datastore_name comes from list_all_datastores. Returns the list envelope: 'items' holds one row per image, and 'returned'/'total'/'truncated' state whether the listing is complete. All patterns are browsed, so truncated is always false.

[READ] List deployable images (OVA/OVF/ISO/VMDK) from the local cache registry — instant, no vCenter connection or datastore I/O. Reads ~/.vmware-storage/image_registry.json, which scan_datastore_images fills; results may be stale, and are empty until a scan has run. For a live listing use scan_datastore_images instead. Returns the list envelope: 'items' holds {target, datastore, name, ds_path, size_mb, type, modified} and is empty if nothing matches, while 'returned'/'total'/'truncated' state whether the listing is complete. The whole registry is filtered in memory, so truncated is always false.

[WRITE] Enable the software iSCSI adapter (vmhba) on an ESXi host. Required prerequisite before add_iscsi_target. Without confirm=True this only previews: it returns blast_radius (the host, its current adapters, whether the software adapter already exists) and changes nothing. Show it to the user. Do not set confirm=True on your own because the user asked earlier — they have not seen the preview yet. Already enabled returns action "noop" with the HBA device and IQN. Non-disruptive (no reboot, no impact on existing datastores). Refused when the host's storage view cannot be read. Returns a dict; check state first with get_iscsi_status.

[READ] Get the software iSCSI adapter state and configured send targets for an ESXi host. Returns {host, enabled, hba_device, iqn, send_targets: [{address, port}]}; when the adapter is disabled, enabled=false with null device/IQN and an empty target list. Use this before enable_iscsi / add_iscsi_target / remove_iscsi_target to check prerequisites, and afterwards to verify the change took effect.

[WRITE] Add an iSCSI send (dynamic discovery) target to an ESXi host's software iSCSI adapter, then automatically rescan all HBAs and VMFS volumes to discover new LUNs. Without confirm=True this only previews: it returns blast_radius (the adapter, the send targets configured now, and the adapters the rescan touches) and changes nothing. Show it to the user. Do not set confirm=True on your own because the user asked earlier — they have not seen the preview yet. Refused when software iSCSI is not enabled (run enable_iscsi first) or the host's storage view cannot be read. A duplicate address:port returns action "noop". No separate rescan_storage call is needed afterwards. Returns a dict.

[WRITE] Remove an iSCSI send target from an ESXi host's software iSCSI adapter, then rescan all HBAs and VMFS volumes. Destructive: LUNs served only through this target become inaccessible after the rescan. Without confirm=True this only previews: it returns blast_radius (the static targets it discovered, the paths that go with them, the devices and VMFS datastores that lose all or some paths) and changes nothing. Show that to the user and get their explicit decision. Do not set confirm=True on your own because the user asked earlier — they have not seen what it cuts off yet. Refused when a datastore would lose every path (unmount it first), when the address:port is not configured or software iSCSI is disabled, and when any path or static target cannot be attributed. Reversible only by re-adding via add_iscsi_target. Returns a dict.

[WRITE] Rescan all HBAs and VMFS volumes on an ESXi host to discover newly presented LUNs and datastores. Use this when a storage array presents new LUNs, or after out-of-band SAN changes. Not needed after add_iscsi_target / remove_iscsi_target — those rescan automatically. Without confirm=True this only previews: it returns blast_radius (the host, every adapter the rescan touches, the mounted VMFS volumes) and changes nothing. Show it to the user. Do not set confirm=True on your own because the user asked earlier — they have not seen the preview yet. Deletes nothing, but it is I/O-visible on the host and may take a minute or two with many paths. Refused when the host's storage view cannot be read. Returns a dict.

[READ] Get vSAN overall health, per-check-group health, and per-host disk-group layout for a cluster. Returns {cluster_name, vsan_enabled, overall_health, overall_health_description, health_queried, health_not_queried_reason, health_checked_at, test_groups: [{group_id, group_name, group_health}], host_count, hosts_read, hosts_not_read: [{host, reason}], disk_groups_complete, disk_groups: [{host, cache_disk, cache_size_gb, capacity_disks}]}. overall_health is what vSAN reports — green / yellow / red, and sometimes "unknown", which is vSAN's own answer. When the health service could not be asked at all, overall_health is null and health_queried is false with the reason: a null is "not measured", never a measurement. health_checked_at is the age of vCenter's cached summary (the same one Skyline Health shows); this tool reads the cache rather than triggering a full health run. Check disk_groups_complete before treating disk_groups as the cluster's inventory: vCenter cannot read a disconnected or notResponding host, and an empty disk_groups on such a cluster does NOT mean it has none — the unread hosts are named in hosts_not_read and in the message. If vSAN is not enabled, returns vsan_enabled=false with a message rather than an error. Use get_vsan_capacity for space usage instead. No side effects.

[READ] Get space usage of a cluster's vSAN datastore for capacity planning. Returns {cluster_name, vsan_enabled, datastore_name, accessible, total_gb, used_gb, free_gb, usage_pct}. When the vSAN datastore is inaccessible (accessible=false) the four figures are null with a message, not 0 — vCenter answers 0 for a datastore it cannot reach, and 0 GB used reads as a healthy empty datastore. accessible=null means the summary did not say. If vSAN is not enabled on the cluster, returns vsan_enabled=false with an explanatory message rather than an error; errors only if the cluster name is not found. Use get_vsan_health for disk-group layout and host details; use list_all_datastores for non-vSAN (VMFS/NFS) datastore usage. No side effects.

[READ] Get vSAN data-efficiency (deduplication + compression) status for a cluster. Returns {cluster_name, vsan_enabled, dedup_enabled, compression_enabled}. Reads it via the vSAN Management SDK (VsanVcClusterConfigSystem), not base pyVmomi. When vSAN reports no data-efficiency config (space efficiency off, or an OSA cluster without it), dedup_enabled/compression_enabled come back null with a message rather than a fabricated false. Errors only if the cluster name is not found. Use get_vsan_capacity for space usage and get_vsan_health for disk-group layout. No side effects. Note: vSAN Global Deduplication and vSAN-to-vSAN replication are NOT exposed here — neither has a verified SDK object (global dedup has no distinct field; v2v replication lives in the separate vSAN Data Protection plane). Use the vCenter/vSAN UI for those.

[READ] List Fibre Channel HBAs (FC and FCoE) per ESXi host: vmhba, model, driver, status, port type, WWPN/WWNN and reported link speed. Use this for "which FC adapters does each host have" or to find a host's WWPNs; use list_storage_device_paths for devices and paths behind them. Scope with cluster OR host; with neither, every host on the target is read (only the adapter list is fetched, so this stays cheap). Returns the list envelope ('items', 'returned', 'total', 'truncated', 'next_offset') plus hosts_without_fc (read, no FC HBA) and hosts_not_read [{host, reason}]. A host in hosts_not_read was NOT read — never report it as having no FC adapters. speed_reported is the raw vSphere value: the API documents bits per second, but hosts commonly report Gbit/s, so it is not converted. Reads host config only; no rescans.

[READ] SCSI multipath state per device (NAA) across the hosts of one scope: which hosts see it, path counts and states, working paths, adapters, target WWPN, PSP/SATP policy, and the VMFS datastores on it. Use for: "does datastore X have dead or disabled paths on any host" (datastore=X), "which hosts see naa.… and through which adapters" (cluster + device), "do hosts see different numbers of paths" (cluster + only_differences=true), "which devices and datastores depend on vmhba2" (host + adapter). Exactly one of cluster, host or datastore is required — this tool will not read every host at once. Per device: shared (reached over FC/iSCSI or seen by 2+ hosts), seen_by, not_seen_on (hosts that WERE read and do not see a shared device; a disk inside one host is never listed), path_count_differs, states_needing_attention (dead/disabled only) and per-host {paths_total, by_state, working_paths, policy, satp, adapters}; with adapter set, also paths_via_adapter and only_paths_via_adapter (matched by vmhba name, which can be a different card on each host of a cluster). Per-path detail is included when device or datastore is given. Devices needing attention sort first; 'summary' counts the whole result, not just this page. Gotchas: hosts in hosts_not_read were NOT read (refused, not connected — vCenter's copy of a lost host's config may be stale — or missing from the reply) and are never in not_seen_on — when complete is false, say which hosts are unknown instead of concluding a device is missing. States are as vSphere reports them: 'standby' can be normal (active/passive arrays), and a path count does not prove independent fabrics. NFS/vSAN/vVol datastores have no SCSI paths (scope_note says so). NVMe-oF namespaces may not appear. No rescans.

[READ] Which account this server uses, and whether it holds each tool's vSphere privileges. Use this when a tool fails with NoPermission, or before a write, to check what the configured account may do. Asks vCenter/ESXi about the current session (needs only System.View, so any account can ask about itself). Returns target, account, the privilege states, and for one tool its requires/verdict/meaning; without tool, every tool grouped by verdict. Gotchas: privileges are checked on the root folder only. A verdict of not_granted_at_root is NOT "no access" — the privilege may be granted on a specific cluster, host or datastore, where the tool then works. undetermined means vCenter did not answer; never read it as granted.