# Vmware Storage > > - **Type:** Skill - **Install:** `agentstack add skill-zw008-vmware-storage-vmware-storage` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [zw008](https://agentstack.voostack.com/s/zw008) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [zw008](https://github.com/zw008) - **Source:** https://github.com/zw008/VMware-Storage/tree/main/skills/vmware-storage ## Install ```sh agentstack add skill-zw008-vmware-storage-vmware-storage ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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 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 - 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 ` 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 --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 ` 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 --pattern "*.iso"` for ad-hoc searches; pattern is glob, not regex 5. **If datastore not found**: name is case-sensitive. `datastore list --target ` 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 ` → 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 ` → 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/vmware-aria/references/investigation-protocol.md) (in companion skill) — vSAN issues frequently fail the Mechanism criterion (capacity is correlated, not causal) ### Multi-Target Operations All commands accept `--target ` to operate against a specific vCenter or ESXi host from your config: ```bash # 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 | Scenario | Recommended | Why | |----------|:-----------:|-----| | Local/small models (Ollama, Qwen) | **CLI** | ~2K tokens vs ~8K for MCP | | Cloud models (Claude, GPT-4o) | Either | MCP gives structured JSON I/O | | Automated pipelines | **MCP** | Type-safe parameters, structured output | ## MCP Tools (11 — 7 read, 4 write) All MCP tools accept an optional `target` parameter to select which vCenter/ESXi to connect to. The 4 write tools also accept `dry_run: true` to preview the change without executing it. 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`. | Category | Tool | Type | Description | |----------|------|:----:|-------------| | Datastore | `list_all_datastores` | Read | List datastores with capacity, usage %, VM count | | | `browse_datastore` | Read | Browse files with optional path and glob pattern | | | `scan_datastore_images` | Read | Find OVA/ISO/OVF/VMDK in a datastore | | | `list_cached_images` | Read | Query local image registry with type/datastore filters | | iSCSI | `storage_iscsi_status` | Read | Show adapter status, HBA device, IQN, send targets | | | `storage_iscsi_enable` | Write | Enable software iSCSI adapter on a host | | | `storage_iscsi_add_target` | Write | Add iSCSI send target (IP + port) and rescan | | | `storage_iscsi_remove_target` | Write | Remove iSCSI send target and rescan | | | `storage_rescan` | Write | Rescan all HBAs and VMFS volumes | | vSAN | `vsan_health` | Read | Cluster health summary and disk group details | | | `vsan_capacity` | Read | Total/used/free capacity in GB and usage % | **Read/write split**: 7 tools are read-only, 4 modify state. Write tools require explicit parameters (host name, IP address), support `dry_run`, and are audit-logged. `storage_iscsi_remove_target` is classified `risk:high` (destructive — LUNs can become inaccessible) and goes through the policy confirmation gate. ## Read-Only Mode If a write tool described above is absent from `list_tools()`, this deployment is in read-only mode: `VMWARE_READ_ONLY=true` (or `VMWARE_STORAGE_READ_ONLY`, or `read_only: true` in config.yaml) withholds all 4 write tools at start-up. That is a deliberate lockdown, not a fault — do not retry, and do not look for another tool that achieves the same change. Name the operation that is blocked and say an operator must clear the switch and restart the server. The 7 read tools are unaffected. `vmware-storage doctor` reports the current state and its source. ## CLI Quick Reference ```bash # Datastore vmware-storage datastore list [--target ] vmware-storage datastore browse [--path ] [--pattern "*.ova"] vmware-storage datastore scan-images [--target ] # iSCSI vmware-storage iscsi enable [--dry-run] vmware-storage iscsi status vmware-storage iscsi add-target [--port 3260] [--dry-run] vmware-storage iscsi remove-target [--port 3260] [--dry-run] vmware-storage iscsi rescan [--dry-run] # vSAN vmware-storage vsan health [--target ] vmware-storage vsan capacity [--target ] # 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. ### vSAN health shows "unknown" status vSAN health checks require a **vCenter connection** (not standalone ESXi). The full VsanVcClusterHealthSystem runs via vCenter's vSAN Health Service. If connected to a standalone ESXi host, vSAN queries will fail or return limited info. ### 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 ` 3. Wait 15-30 seconds, then rescan again: `vmware-storage iscsi rescan ` ### "Password not found" error The password environment variable is missing. Variable names follow the pattern `VMWARE__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: ```bash 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. ### Warning: "ran against a target that declares no environment" Add `environment:` to that target in `~/.vmware-storage/config.yaml`: ```yaml targets: - name: my-vcenter host: vcenter.example.com environment: production # production | staging | lab | ``` Policy scopes its rules by environment, not by the target's name — an unlabelled target matches none of them. **Today** an undeclared write (`iscsi enable`, `iscsi add-target`, `iscsi remove-target`, `rescan`) still runs and logs this warning. **The next major release refuses it** with: > `'storage_iscsi_enable' changes state, but its target does not declare which environment it is. Add 'environment: ' (e.g. production, staging, lab) to that target's entry in the skill's config.yaml, then retry.` Declaring it now makes that upgrade a no-op. Read-only operations (`datastore list`, `browse`, `iscsi status`, `vsan health`) are never affected. Check what is in force with `vmware-audit policy`. ### `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**: 7 of 11 tools are read-only (list, browse, scan, cached images, status, health, capacity) - **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/`](../../patterns/) directory hosts L5 auto-remediation **candidate** patterns under the Enterprise Harness Engineering framework. First PoC: [`patterns/iscsi-target-stale-rescan.yaml`](../../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 ```bash uv tool install vmware-storage 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= 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): - Ev … ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [zw008](https://github.com/zw008) - **Source:** [zw008/VMware-Storage](https://github.com/zw008/VMware-Storage) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-zw008-vmware-storage-vmware-storage - Seller: https://agentstack.voostack.com/s/zw008 - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.