VMware Storage

Disclaimer: This is a community-maintained open-source project and is not affiliated with, endorsed by, or sponsored by VMware, Inc. or Broadcom Inc. "VMware" and "vSphere" are trademarks of Broadcom. Source code is publicly auditable at github.com/vmware-skills/VMware-Storage under the MIT license.

VMware vSphere storage management — 14 MCP tools for datastores, iSCSI, vSAN, and Fibre Channel / multipath diagnostics.

Split from vmware-aiops for lighter context and local model compatibility. Companion skills: vmware-aiops (VM lifecycle), vmware-monitor (read-only monitoring), vmware-vks (Tanzu Kubernetes), vmware-nsx (NSX networking), vmware-nsx-security (DFW/firewall), vmware-aria (metrics/alerts/capacity), vmware-avi (AVI/ALB/AKO), vmware-harden (compliance baselines). | vmware-pilot (workflow orchestration) | vmware-policy (audit/policy)

What This Skill Does

Quick Install

uv tool install vmware-storage==2.1.0
vmware-storage init      # guided setup: writes config + .env (chmod 600, password grep-safe), then verifies
vmware-storage doctor

When to Use This Skill

• Browse datastore files or scan for deployable images (OVA/ISO/VMDK)
• Configure iSCSI: enable adapter, add/remove send targets, rescan storage
• Check vSAN cluster health and capacity
• Fibre Channel: list HBAs and WWPNs, find dead/disabled paths, compare path counts across a cluster, map a datastore to its devices
• Any storage-focused VMware operation

Use companion skills for:

• VM lifecycle, deployment, guest ops → vmware-aiops
• Inventory, health, alarms, events → vmware-monitor
• Tanzu Kubernetes → vmware-vks
• Load balancing, AVI/ALB, AKO, Ingress → vmware-avi

Related Skills — Skill Routing

Common Workflows

Set Up iSCSI Storage on a Host

Pre-flight (judgment):

• Network reachability: vmkping <iscsi-target-ip> from the ESXi host must succeed BEFORE adding the target. Adding an unreachable target leaves the host in a degraded state, retrying forever.
• Adapter sanity: iscsi status first — if already enabled, do not "re-enable"; just add the target.
• Idempotency: add-target is idempotent (re-adding same IP is a no-op), but remove-target is not safely reversible mid-IO. Always verify no LUNs from this target are in use before removing.
• Existing targets: list them first; some sites add targets one-per-host while others use cluster-wide. Check site convention.

Steps:

1. iscsi status esxi-01 → confirm adapter state and existing targets
2. iscsi enable esxi-01 --dry-run then real (skip if already enabled)
3. iscsi add-target esxi-01 <ip> --dry-run then real (auto-rescans on success)
4. iscsi status esxi-01 again → confirm target listed AND devices appearing
5. If devices missing 30+ sec after add: iscsi rescan esxi-01 once more, then check ESXi-side vmkping and target ACL

Find Deployable Images Across Datastores

Judgment: image search is read-only and safe, but blind scanning of every datastore is slow on large estates. Filter first.

1. datastore list → get the inventory; ignore datastores marked inaccessible or low free space
2. datastore scan-images <ds> on the datastore most likely to hold images (typically named iso-*, templates, or central nfs-shared)
3. If unsure where images live: scan multiple in parallel via separate calls; results are cached in the local registry
4. datastore browse <ds> --pattern "*.iso" for ad-hoc searches; pattern is glob, not regex
5. If datastore not found: name is case-sensitive. datastore list --target <vc> to verify exact spelling.

For filtered queries against the cache: use list_cached_images MCP tool with image_type and datastore parameters — avoids re-scanning.

vSAN Health Assessment

Judgment: vSAN problems often masquerade as vSphere problems and vice-versa. Check both planes — if vSAN is healthy but VMs are slow, the issue is at the compute or network layer, not storage.

1. vsan health <cluster> → look beyond green/red — check disk group state, network partitioning, and cluster member counts. A "yellow" disk group is the early warning of a failure.
2. vsan capacity <cluster> → utilization > 70% triggers slack-space risk; > 80% impedes resync; never let prod cross 80%.
3. Cross-check vmware-monitor health alarms for vSAN-related alarms (HCL warnings, network anomalies)
4. If vSAN not enabled on this cluster: check cluster type via vmware-monitor inventory clusters; vSAN is opt-in, not default
5. For deep investigation, follow references/investigation-protocol.md (in companion skill) — vSAN issues frequently fail the Mechanism criterion (capacity is correlated, not causal)

Check Fibre Channel Paths

Judgment: report what vSphere observed, not a verdict. standby paths are normal on active/passive arrays, and equal path counts do not prove two independent fabrics. Zoning, array masking and switch health are out of scope.

1. paths devices --datastore <ds> → dead/disabled paths behind one datastore, per host (devices needing attention sort first)
2. paths devices --cluster <c> --only-differences → shared devices some hosts do not see, or see through a different number of paths; each host's paths_total shows which has fewer
3. paths devices --host <h> --adapter vmhba2 → what depends on one HBA; only_paths_via_adapter: true means that host has no other path to the device
4. paths fc-adapters --cluster <c> → WWPNs to hand to the SAN team
5. If complete is false: hosts in hosts_not_read were not read (the reason says NoPermission or the connection state). Name them as unknown — never report them as missing the device
6. If "Scope required": pass exactly one of --cluster, --host or --datastore; this tool does not read every host at once

Multi-Target Operations

All commands accept --target <name> to operate against a specific vCenter or ESXi host from your config:

# Default target (first in config.yaml)
vmware-storage datastore list

# Specific target
vmware-storage datastore list --target prod-vcenter
vmware-storage iscsi status esxi-lab --target lab-esxi

Usage Mode

MCP Tools (14 — 10 read, 4 write)

All MCP tools accept an optional target parameter to select which vCenter/ESXi to connect to. The 4 write tools take confirm (default false): without it they change nothing and return blast_radius — the host and adapters touched, and for remove_iscsi_target the paths, devices and datastores behind the target. Show it to the user; pass confirm: true only after they decide. dry_run is a deprecated alias.

The four Datastore read tools return the family list envelope — {items, returned, limit, total, truncated, hint} — rather than a bare array. Read the rows from items; truncated says whether the listing is complete, so it never has to be guessed from the row count. All four enumerate their collection in full, so total is the real count and truncated is always false.

Read/write split: 10 tools are read-only, 4 modify state. Write tools require explicit parameters (host name, IP address), preview unless confirm: true, refuse when a datastore would lose every path or the host's storage view cannot be read, and are audit-logged. remove_iscsi_target is classified risk:high (destructive — LUNs can become inaccessible) and goes through the policy confirmation gate.

Running with local or small models? See references/agent-guardrails.md.

CLI Quick Reference

# Datastore
vmware-storage datastore list [--target <name>]
vmware-storage datastore browse <ds_name> [--path <subdir>] [--pattern "*.ova"]
vmware-storage datastore scan-images <ds_name> [--target <name>]

# iSCSI
vmware-storage iscsi enable <host> [--dry-run]
vmware-storage iscsi status <host>
vmware-storage iscsi add-target <host> <ip> [--port 3260] [--dry-run]
vmware-storage iscsi remove-target <host> <ip> [--port 3260] [--dry-run]
vmware-storage iscsi rescan <host> [--dry-run]

# vSAN
vmware-storage vsan health <cluster> [--target <name>]
vmware-storage vsan capacity <cluster> [--target <name>]

# Fibre Channel / multipath (read-only)
vmware-storage paths fc-adapters [--cluster <c> | --host <h>]
vmware-storage paths devices (--cluster <c> | --host <h> | --datastore <ds>) [--device <naa>] [--adapter <vmhba>] [--only-differences]

# Diagnostics
vmware-storage doctor [--skip-auth]

Full CLI reference with all options and output formats: see references/cli-reference.md

Troubleshooting

iSCSI enable fails with "already enabled"

Not an error. The software iSCSI adapter is already active on that host. The response includes the current HBA device name and IQN. Run iscsi status to see configured send targets.

"Datastore not found" when browsing

Datastore names are case-sensitive. Run vmware-storage datastore list to get the exact name. Common mistakes: Datastore1 vs datastore1, trailing spaces.

get_vsan_health returns overall_health: null

null means the health service was not asked, and health_not_queried_reason says why. It is deliberately not the string "unknown" — vSAN returns that itself, so using it for "we did not ask" made the two impossible to tell apart (on one VCF 9.1 cluster it stood in for red). A string in overall_health is always vSAN's own answer.

The usual cause is a standalone ESXi target: VsanVcClusterHealthSystem runs in vCenter's vSAN Health Service, so connect to the vCenter that manages the cluster. Otherwise read it in the vCenter UI under Cluster > Monitor > vSAN > Skyline Health.

health_checked_at is the age of vCenter's cached summary. This tool reads that cache — the same one Skyline Health shows — rather than triggering a full health run, which takes minutes and loads the cluster.

Rescan doesn't discover new LUNs

After adding iSCSI targets, the storage subsystem may need 10-30 seconds to enumerate new LUNs. Steps to resolve:

1. Verify the target IP is reachable from the ESXi host (vmkping from ESXi shell)
2. Check that the iSCSI target is correctly configured: vmware-storage iscsi status <host>
3. Wait 15-30 seconds, then rescan again: vmware-storage iscsi rescan <host>

"Password not found" error

The password environment variable is missing. Variable names follow the pattern VMWARE_<TARGET_NAME_UPPER>_PASSWORD where hyphens become underscores. Example: target my-vcenter needs VMWARE_MY_VCENTER_PASSWORD. Check your ~/.vmware-storage/.env file.

Doctor reports ".env permissions too open"

The .env file contains passwords and must have owner-only permissions:

chmod 600 ~/.vmware-storage/.env

Connection timeout to vCenter

The doctor command tests connectivity with a 5-second TCP timeout. If your vCenter is on a high-latency network, the check may fail even though the connection works. Use --skip-auth to bypass both connectivity and auth checks, then test manually.

invalid peer certificate: UnknownIssuer when starting MCP via uvx

Corporate TLS proxies inject certificates that uv's bundled CA store doesn't trust. Use the recommended vmware-storage mcp form (no PyPI re-resolve), or set export UV_NATIVE_TLS=true to make uv use system CAs.

Safety

• No VM operations: This skill cannot power on/off, create, delete, or modify VMs — that scope belongs to vmware-aiops
• Read-heavy: 10 of 14 tools are read-only (list, browse, scan, cached images, status, health, capacity, efficiency, FC adapters, device paths)
• Audit logging: All operations (including reads) are logged to ~/.vmware/audit.db (SQLite WAL, via vmware-policy) with timestamp, user, target, operation, parameters, and result
• Double confirmation: CLI write commands (iSCSI enable, add/remove target) require two separate "Are you sure?" prompts before executing
• Dry-run mode: All write commands support --dry-run to preview API calls without executing
• Input validation: IP addresses validated via ipaddress.ip_address(), ports checked for 1-65535 range, host/cluster/datastore names looked up before operations
• Prompt injection defense: Datastore file names and paths from vSphere are sanitized via _sanitize() — strips control characters (C0/C1), truncates to 500 chars — preventing malicious file names from injecting instructions into downstream LLM agents
• Credential safety: Passwords loaded only from environment variables (.env file), never from config.yaml; .env permissions are checked at startup
• L5 auto-remediation patterns (PoC): The patterns/ directory hosts L5 auto-remediation candidate patterns under the Enterprise Harness Engineering framework. First PoC: patterns/iscsi-target-stale-rescan.yaml — iSCSI HBA rescan classified as risk:low + reversible:true + repeatable:true. Schema only; not yet enforced by the runtime. See references/capabilities.md § Automation Level Reference for the full L1–L5 table.

Full security details: see references/setup-guide.md

Setup

uv tool install vmware-storage==2.1.0
mkdir -p ~/.vmware-storage
cp config.example.yaml ~/.vmware-storage/config.yaml
# Edit config.yaml with your vCenter/ESXi targets

# Add to ~/.vmware-storage/.env (create if missing, chmod 600):
# VMWARE_MY_VCENTER_PASSWORD=<your-password>
chmod 600 ~/.vmware-storage/.env

vmware-storage doctor

All tools are automatically audited via vmware-policy. Audit logs: vmware-audit log --last 20

Full setup guide with multi-target config, MCP server setup, and Docker: see references/setup-guide.md

Architecture

User (natural language)
  ↓
AI Agent (Claude Code / Goose / Cursor)
  ↓ reads SKILL.md
vmware-storage CLI or MCP server (stdio transport)
  ↓ pyVmomi (vSphere SOAP API)
vCenter Server / ESXi
  ↓
Datastores / iSCSI / vSAN

The MCP server uses stdio transport (local only, no network listener). Connections to vSphere use SSL/TLS on port 443.

Audit & Safety

All operations are automatically audited via vmware-policy (@vmware_tool decorator):

• Every tool call logged to ~/.vmware/audit.db (SQLite, framework-agnostic)
• Policy rules enforced via ~/.vmware/rules.yaml (deny rules, maintenance windows, risk levels)
• Risk classification: each tool tagged as low/medium/high/critical
• View recent operations: vmware-audit log --last 20
• View denied operations: vmware-audit log --status denied

vmware-policy is automatically installed as a dependency — no manual setup needed.

License

MIT — github.com/vmware-skills/VMware-Storage