VMware Storage

[READ] Browse files in a datastore directory. Use this for arbitrary files or a glob; prefer scan_datastore_images for deployable images. ds_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] 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 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] List all datastores with capacity, usage percentage, and accessibility. Use this first for the ds_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. Enumerated in one pass, 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, populated by prior datastore scans; results may be stale or empty if no scan has run. For a live listing use scan_datastore_images instead. Returns the list envelope: 'items' holds {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.

[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. ds_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] 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.

[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 storage_iscsi_enable first) or the host's storage view cannot be read. A duplicate address:port returns action "noop". No separate storage_rescan call is needed afterwards. Returns a dict.

[WRITE] Enable the software iSCSI adapter (vmhba) on an ESXi host. Required prerequisite before storage_iscsi_add_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 storage_iscsi_status.

[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 storage_iscsi_add_target. Returns a dict.

[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 storage_iscsi_enable / storage_iscsi_add_target / storage_iscsi_remove_target to check prerequisites, and afterwards to verify the change took effect.

[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 storage_iscsi_add_target / storage_iscsi_remove_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 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 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 vsan_capacity for space usage and 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] 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 vsan_capacity for space usage instead. No side effects.