VMware Storage

VMware 存储

作者：Wei Zhou，VMware by Broadcom — [email protected] 这是由 VMware 工程师发起的社区项目，并非 VMware 官方产品。 VMware 官方开发工具请参阅 developer.broadcom.com。

English | 中文

VMware vSphere 存储管理：数据存储、iSCSI、vSAN，以及只读的光纤通道／多路径诊断——16 个 MCP 工具，专注领域且轻量。

从 vmware-aiops 拆分而来，可减轻上下文负担并兼容本地模型。

升级到 2.0

2.0 重命名了其中 10 个 MCP 工具（除 4 个原本就以动词开头的工具外），使所有名称都以动词开头（例如，fc_adapter_list → list_fc_adapters、storage_device_paths → list_storage_device_paths、storage_iscsi_add_target → add_iscsi_target）。完整的旧名称 → 新名称对照表见 RELEASE_NOTES.md。此外，有 3 个工具更改了参数：browse_datastore 和 scan_datastore_images 使用 datastore_name（原为 ds_name，现在与 vmware-aiops 的 browse_datastore 一致），而 list_all_datastores 新增了一个 可选的 limit（与 vmware-monitor 一致）。其他一切保持不变：工具、安全防护和 CLI 命令均相同（CLI 仍像以前一样使用数据存储名称）。如果 Agent 提示词、脚本或 ~/.vmware/rules.yaml 中指定了某个工具，请更新相应名称——不过，使用旧名称编写的拒绝 规则仍可在 vmware-policy ≥ 1.18 中正常工作（vmware-audit policy 会列出重命名后规则覆盖范围有所扩大的情况），而 vmware-pilot ≥ 1.13 会转换已保存工作流中的旧名称。 如果低于 2.0 的安装与其共用该 rules.yaml，也请将它升级到 vmware-policy ≥ 1.18.2：该版本会 将每条规则同时与旧名称和新名称匹配，因此一个文件即可供两者使用。

配套技能

快速安装

# Via PyPI
uv tool install vmware-storage

# Or pip
pip install vmware-storage

离线／隔离网络环境安装（从源代码）

本项目使用现代 PEP 517 构建系统（hatchling），因此有意不提供 setup.py——这是预期行为，并非文件缺失。如果你克隆了 源代码，并遇到 ERROR: File "setup.py" or "setup.cfg" not found ... editable mode currently requires a setuptools-based build，说明你的 pip 版本低于 21.3，无法使用非 setuptools 后端进行 可编辑（-e）安装。可编辑模式是为开发者提供的便利，并非运行工具所必需——可选择以下方式之一：

# From the source tree — a normal (non-editable) install builds a wheel:
pip install .              # NOT  pip install -e .

# ...or upgrade pip first, and editable works too:
pip install --upgrade pip && pip install -e .

对于真正与网络隔离的主机，请在联网的计算机上构建 wheel，并将其复制过去——目标主机无需联网：

# On a connected machine, collect this package + its dependencies as wheels:
pip wheel . -w dist        # → dist/*.whl   (or: uv build, for just this package)

# Copy dist/ to the air-gapped host, then install offline:
pip install --no-index --find-links dist vmware-storage

配置

mkdir -p ~/.vmware-storage
cp config.example.yaml ~/.vmware-storage/config.yaml
# Edit with your vCenter/ESXi credentials

echo "VMWARE_MY_VCENTER_PASSWORD=your_password" > ~/.vmware-storage/.env
chmod 600 ~/.vmware-storage/.env

# Verify
vmware-storage doctor

MCP 工具（16 个）

自动修复模式（PoC）

patterns/ 目录收录了 Enterprise Harness Engineering 框架中的 L5 自动修复候选模式。首个 PoC 模式 patterns/iscsi-target-stale-rescan.yaml 将 iSCSI HBA 重新扫描描述为一种低风险、可逆且可重复的操作。模式架构仅在此处记录——目前尚未接入运行时强制执行，因此这是一份参考设计，而非生产环境中的自动修复方案。

常见工作流

在主机上设置 iSCSI 存储

1. 启用 iSCSI 适配器：vmware-storage iscsi enable esxi-01
2. 添加目标：vmware-storage iscsi add-target esxi-01 10.0.0.100
3. 验证：vmware-storage iscsi status esxi-01

add-target 命令会自动重新扫描存储。执行任何写入命令前，可先使用 --dry-run 预览。

查找各数据存储中的可部署镜像

1. 列出所有数据存储：vmware-storage datastore list
2. 扫描镜像：vmware-storage datastore scan-images datastore01
3. 按模式浏览：vmware-storage datastore browse datastore01 --pattern "*.iso"

vSAN 健康评估

1. 检查运行状况：vmware-storage vsan health Cluster-Prod
2. 检查容量：vmware-storage vsan capacity Cluster-Prod
3. 如果发现问题，使用 vmware-monitor 调查警报和事件

检查光纤通道路径

1. 检查数据存储下失效或已禁用的路径：vmware-storage paths devices --datastore ds-fc-01
2. 查找通过与同级主机不同数量的路径（或完全没有路径）访问共享设备的主机：vmware-storage paths devices --cluster Cluster-Prod --only-differences
3. 获取 SAN 团队所需的 WWPN：vmware-storage paths fc-adapters --cluster Cluster-Prod

无法读取的主机会列在 hosts_not_read 中，绝不会被报告为缺少设备。路径状态按 vSphere 的报告结果显示——standby 不会被标记。

命令行

# Datastore
vmware-storage datastore list
vmware-storage datastore browse datastore01
vmware-storage datastore scan-images datastore01

# iSCSI
vmware-storage iscsi status esxi-01
vmware-storage iscsi enable esxi-01
vmware-storage iscsi add-target esxi-01 192.168.1.100
vmware-storage iscsi remove-target esxi-01 192.168.1.100
vmware-storage iscsi rescan esxi-01

# vSAN
vmware-storage vsan health Cluster-Prod
vmware-storage vsan capacity Cluster-Prod

# Fibre Channel / multipath (read-only)
vmware-storage paths fc-adapters --cluster Cluster-Prod
vmware-storage paths devices --datastore ds-fc-01

# Diagnostics
vmware-storage doctor

MCP 服务

安装 vmware-storage 后，只需一条命令即可启动 MCP 服务（v1.5.15+）：

# Recommended — single command, no network re-resolve
vmware-storage mcp

# With a custom config path
VMWARE_STORAGE_CONFIG=/path/to/config.yaml vmware-storage mcp

# Or via Docker
docker compose up -d

Agent 配置

将以下内容添加到 AI Agent 的 MCP 配置中：

{
  "mcpServers": {
    "vmware-storage": {
      "command": "vmware-storage",
      "args": ["mcp"],
      "env": {
        "VMWARE_STORAGE_CONFIG": "~/.vmware-storage/config.yaml"
      }
    }
  }
}

# Run without installing (requires PyPI access each launch)
uvx --from vmware-storage vmware-storage mcp

# Legacy entry point (still works, kept for backward compatibility)
vmware-storage-mcp

为什么要单独拆分一个技能？

vmware-aiops 有 61 个 MCP 工具，对本地大模型（7B-14B）来说过于庞大。将存储拆分为独立技能后：

• 16 个工具 — 可轻松放入小型模型的上下文窗口
• 专注领域 — 存储管理员只需使用所需工具
• 最小权限 — 可使用仅具备存储只读权限的 vCenter 服务账户运行
• 可组合 — 可按需与 vmware-monitor 或 vmware-aiops 搭配使用

版本兼容性

Python：3.10+（自 v1.5.27 起——此前为 3.11+）。已在 3.10 / 3.11 / 3.12 上测试。

Broadcom 官方参考资料

• SDK：https://developer.broadcom.com/sdks — VCF Python SDK、vSAN Management SDK（内置于 pyVmomi）
• REST API：https://developer.broadcom.com/xapis — vSAN Management API、VCF API
• CLI 工具：https://developer.broadcom.com/tools — PowerCLI 9.1、ESXCLI

安全性

故障排除

远程访问（HTTPS）和限制工具

默认情况下，vmware-storage mcp 通过 stdio 与一个本地客户端通信，并提供所有工具。两种选项可以改变这一行为 （vmware-policy ≥ 1.21.0）。

通过 HTTPS 提供服务，让其他机器上的客户端也能连接。每个调用方都需要一个 bearer token：

vmware-audit token create alice          # prints the token once; give it to alice
vmware-audit token list                  # names only
vmware-audit token revoke alice          # refused from its next request, no restart
vmware-storage mcp --transport https --host 0.0.0.0 --port 8443 \
    --cert /etc/vmware-mcp/server.pem --key /etc/vmware-mcp/server-key.pem \
    --public-name mcp.example.com

连接客户端（此处以 Claude Code 为例；任何支持可流式 HTTP 和自定义标头的 MCP 客户端均可）：

claude mcp add --transport http vmware-storage https://mcp.example.com:8443/mcp \
    --header "Authorization: Bearer $VMWARE_MCP_TOKEN"

{
  "mcpServers": {
    "vmware-storage": {
      "type": "http",
      "url": "https://mcp.example.com:8443/mcp",
      "headers": { "Authorization": "Bearer ${VMWARE_MCP_TOKEN}" }
    }
  }
}

• 没有 token 时，服务不会启动；它会拒绝 --public-name 以外的 Host/Origin 值，并在绑定前检查未通过身份验证的请求是否会收到 401。请使用客户端信任的、适用于这些名称的证书。
• 如果在同一台机器上使用终止 TLS 的反向代理，请使用 --transport http --host 127.0.0.1 --public-name mcp.example.com，并透传 Authorization 标头。
• 如果负载均衡器或网关位于另一台机器上，请保留 --transport https（自签名证书也可以），在 --public-name 中列出负载均衡器发送的 Host 主机名，并让它转发 Authorization。其健康探测可使用 GET /healthz，该请求无需 token，且只返回 {"status": "ok"}（vmware-policy ≥ 1.23.0）。
• 每个请求都发送 traceparent 或 X-Request-ID，以便将其存入审计记录；随后运行 vmware-audit log --correlation-id ID，即可查找某个平台请求背后的调用。
• 审计日志会将每个调用方记录为 token:<name>。调用会并行执行，即使针对同一目标也一样：服务会为每个目标保留最多 VMWARE_MCP_POOL_SIZE（默认值为 2）个会话，每个会话都使用该目标上的一个登录；调用等待空闲会话的时间最长为 300 s（vmware-policy ≥ 1.22.0）。
• 任何能够访问此端点的人都将以此服务的账户身份操作。 Token 用于识别调用方；它们不会授予平台权限。每个权限级别应运行一个端点。vmware-storage access-info 会显示该账户及其可执行的操作。
• **一个端点供多人或多个角色使用：**运行一次 vmware-audit roles enable，然后为每个 token 分配一个角色（vmware-audit token create NAME --role reader，或在 roles.yaml 中定义一个列出工具和目标的角色；vmware-policy ≥ 1.24.0）。角色会限制 token 在此端点上可调用的内容；它不能授予超出账户权限的权限。请参阅 vmware-policy 的 README 中的“网络调用方的角色”。

仅提供只读工具，以及你选择的写入工具：

vmware-storage mcp --expose read --allow-write enable_iscsi
# or: VMWARE_STORAGE_MCP_EXPOSE=read VMWARE_STORAGE_MCP_ALLOW_WRITE=enable_iscsi vmware-storage mcp

未提供的工具不会出现在客户端的工具列表中。无效值或未知的写入工具会导致服务停止（exit 2）。这只限制提供给客户端的工具；它不属于授权机制，因此账户本身应遵循最小权限原则。

详情：skills/vmware-storage/references/setup-guide.md（“通过 HTTPS 提供 MCP 服务”“限制提供的工具”）。

许可证

MIT