vmware-storage

# 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/zw008/VMware-Storage](https://github.com/zw008/VMware-Storage) under the MIT license.

VMware vSphere storage management — 11 MCP tools for datastores, iSCSI, and vSAN.

> Split from vmware-aiops for lighter context and local model compatibility.
> **Companion skills**: [vmware-aiops](https://github.com/zw008/VMware-AIops) (VM lifecycle), [vmware-monitor](https://github.com/zw008/VMware-Monitor) (read-only monitoring), [vmware-vks](https://github.com/zw008/VMware-VKS) (Tanzu Kubernetes), [vmware-nsx](https://github.com/zw008/VMware-NSX) (NSX networking), [vmware-nsx-security](https://github.com/zw008/VMware-NSX-Security) (DFW/firewall), [vmware-aria](https://github.com/zw008/VMware-Aria) (metrics/alerts/capacity), [vmware-avi](https://github.com/zw008/VMware-AVI) (AVI/ALB/AKO), [vmware-harden](https://github.com/zw008/VMware-Harden) (compliance baselines).
> | [vmware-pilot](../vmware-pilot/SKILL.md) (workflow orchestration) | [vmware-policy](../vmware-policy/SKILL.md) (audit/policy)

## What This Skill Does

| Category | Tools | Count |
|----------|-------|:-----:|
| **Datastore** | list all datastores, browse files, scan for OVA/ISO/OVF/VMDK images, list cached images | 4 |
| **iSCSI** | enable adapter, show status, add target, remove target, rescan HBAs | 5 |
| **vSAN** | cluster health summary, capacity overview (total/used/free) | 2 |

## Quick Install

```bash
uv tool install vmware-storage
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
- 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

| User Intent | Recommended Skill |
|-------------|-------------------|
| Read-only monitoring, alarms, events | **vmware-monitor** |
| Storage: iSCSI, vSAN, datastores | **vmware-storage** ← this skill |
| VM lifecycle, deployment, guest ops | **vmware-aiops** |
| Tanzu Kubernetes (vSphere 8.x+) | **vmware-vks** |
| NSX networking: segments, gateways, NAT | **vmware-nsx** |
| NSX security: DFW rules, security groups | **vmware-nsx-security** |
| Aria Ops: metrics, alerts, capacity planning | **vmware-aria** |
| Multi-step workflows with approval | **vmware-pilot** |
| Compliance baselines (CIS / 等保 / PCI-DSS), drift detection, LLM remediation advisor | **vmware-harden** (`uv tool install vmware-harden`) |
| Load balancer, AVI, ALB, AKO, Ingress | **vmware-avi** (`uv tool install vmware-avi`) |
| Audit log query | **vmware-policy** (`vmware-audit` CLI) |

## 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`](../vmware-aria/skills/vmwa