VMware Aria Operations

VMware Aria Operations MCP 技能

注意：在 VCF 9.0 及更高版本中，VMware Aria Operations 已更名为 VCF Operations。此技能可用于这两个名称——/suite-api/ REST 端点保持不变。

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

通过模型上下文协议（MCP），利用 AI 辅助 VMware Aria Operations（vRealize Operations）监控和容量规划。

升级到 2.0

2.0 重命名了 4 个 MCP 工具，使每个名称都以动词开头（例如，findings_list → list_findings、fleet_certificate_list → list_fleet_certificates、fleet_domain_list → list_fleet_domains）。完整的旧名称 → 新名称对照表见 RELEASE_NOTES.md。其他方面均无变化：工具、参数、安全门控和 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：它会将每条规则与新旧名称进行匹配，因此一个文件即可供两者使用。

概述

vmware-aria 提供 46 个 MCP 工具，可通过自然语言 AI Agent（Claude Code、Cursor、Goose 等）与 Aria Operations 交互：

类别	工具	类型
资源	列表、获取、指标、健康徽章、顶级使用者、指标键、属性、关系	只读（8）
警报	列表、获取、调查（警报→资源）、确认、取消、定义、备注（列表 / 添加）、建议	读取 + 3 个写入（9）
警报定义	症状定义、创建、启用/禁用、删除	读取 + 3 个写入（4）
容量	概览、剩余容量、剩余时间、适当调整规模	只读（4）
报告	定义、生成、列表、获取、删除	读取 + 2 个写入（5）
异常	列出异常、风险徽章	只读（2）
健康状况	平台健康状况、收集器组、Aria 节点内存/交换区/堆、适配器收集状态	只读（4）
维护	开始 / 结束资源维护、维护计划	读取 + 2 个写入（3）
Fleet / PromQL（VCF Ops 9.1）	Fleet 证书、密码账户、VCF 域、诊断发现项、实时 PromQL 查询	只读（5）
原始 API	搜索 API 操作索引、GET 一个已索引路径——用于读取上方工具未涵盖的内容	只读（2）

总计：46 个工具——36 个只读，10 个写入

快速开始

# Install
uv tool install vmware-aria

# Configure
mkdir -p ~/.vmware-aria
cat > ~/.vmware-aria/config.yaml << 'EOF'
targets:
  prod:
    host: aria-ops.example.com
    username: admin
    port: 443
    verify_ssl: true
    auth_source: LOCAL
default_target: prod
EOF

# Set password (never in config.yaml)
echo "VMWARE_ARIA_PROD_PASSWORD=your_password" > ~/.vmware-aria/.env
chmod 600 ~/.vmware-aria/.env

# Verify setup
vmware-aria doctor

离线 / 气隙环境安装（从源代码安装）

本项目使用现代 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-aria

CLI 示例

# List top CPU consumers
vmware-aria resource top --metric 'cpu|usage_average' --top 10

# Check active CRITICAL alerts
vmware-aria alert list --criticality CRITICAL

# Acknowledge an alert
vmware-aria alert acknowledge <alert-id>

# Fetch 4-hour CPU + memory metrics for a VM ("missing" says why a key has no points)
vmware-aria resource metrics <vm-id> --metrics 'cpu|usage_average,mem|usage_average' --hours 4

# Check cluster capacity
vmware-aria capacity remaining <cluster-id>
vmware-aria capacity time-remaining <cluster-id>

# Find rightsizing opportunities (vCPU / memory now → recommended, direction, actionable)
vmware-aria capacity rightsizing

# Check Aria platform health: HEALTHY / DEGRADED / DOWN / UNKNOWN, per service, plus version
vmware-aria health status
vmware-aria health collectors

# Is the Aria node short of memory? Which adapter stopped collecting?
vmware-aria health node
vmware-aria health adapters

# Look up the metric keys a VM reports before querying them
vmware-aria resource keys <vm-id> --filter 'mem|'

# Put a host in maintenance for 2 hours before planned work, then end it (asks once; --dry-run prints the API call)
vmware-aria maintenance start <host-id> --duration 120
vmware-aria maintenance end <host-id>

# Record who is handling an alert, and read what Aria recommends
vmware-aria alert note-add <alert-id> "Taking this: rebooting esx-03"
vmware-aria alert recommendations <alert-id>

MCP 设置（Claude Code）

运行 uv tool install vmware-aria 后，添加到 ~/.claude.json：

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

v1.5.15+ 使用单命令形式 vmware-aria mcp。为保持向后兼容，仍保留旧版 vmware-aria-mcp 控制台脚本。 如果必须使用 uvx --from vmware-aria vmware-aria mcp（无需安装），并在企业 TLS 代理后遇到 invalid peer certificate: UnknownIssuer，请设置 UV_NATIVE_TLS=true，或使用上面推荐的 vmware-aria mcp 形式。

然后使用自然语言：

• “显示当前 CPU 使用量最高的 10 个对象”
• “列出所有 CRITICAL 警报并确认它们”
• “生产集群还要多久会耗尽内存？”
• “哪些 VM 过度配置了？显示资源优化建议”
• “vm-web-01 上有异常吗？”

身份验证

Aria Operations 使用 vRealizeOpsToken 身份验证：

POST /suite-api/api/auth/token/acquire
{"username": "admin", "password": "...", "authSource": "LOCAL"}
→ {"token": "abc123", "validity": 1765182896000}  # validity = expiry epoch ms

Subsequent requests: Authorization: vRealizeOpsToken abc123

根据官方规范，令牌的滑动有效期为 6 小时（每次调用都会延长）；客户端会在令牌到期前 60 秒自动重新获取。validity 字段是以 epoch 毫秒表示的到期时间戳，而不是时长。

架构

User (natural language)
  ↓
AI Agent (Claude Code / Goose / Cursor)
  ↓  [reads SKILL.md]
vmware-aria MCP server (stdio transport)
  ↓  [HTTPS + vRealizeOpsToken]
Aria Operations Suite API
  ↓
VMs / Hosts / Clusters / Alerts / Capacity

配套技能

技能	范围	工具	安装
vmware-aiops ⭐ 入口	VM 生命周期、部署、来宾操作、集群	60	uv tool install vmware-aiops
vmware-monitor	只读监控、警报、事件、VM 信息	32	uv tool install vmware-monitor
vmware-nsx	NSX 网络：网段、网关、NAT、IPAM	33	uv tool install vmware-nsx-mgmt
vmware-nsx-security	DFW 微分段、安全组、Traceflow	22	uv tool install vmware-nsx-security
vmware-avi	AVI / NSX ALB 负载均衡、AKO K8s 操作	28	uv tool install vmware-avi
vmware-storage	数据存储、iSCSI、vSAN	12	uv tool install vmware-storage
vmware-vks	Tanzu 命名空间、TKC 集群生命周期	23	uv tool install vmware-vks
vmware-harden	合规基线、偏差检测	8	uv tool install vmware-harden

安全

• 从环境变量或 .env 文件加载密码，绝不从 config.yaml 加载
• 每次 MCP 工具调用以及每条访问 Aria 的 CLI 命令都会通过 vmware-policy 审计并记录到 ~/.vmware/audit.db；CLI 写入操作（确认/取消警报、警报备注、警报定义管理、生成/删除报告、开始/结束资源维护）还会追加记录到 ~/.vmware-aria/audit.log
• 对 API 响应进行清理（剥离控制字符，限制为 500 个字符），以防止提示词注入
• MCP 破坏性写入（确认/取消警报、删除警报定义和报告、开始/结束维护）需要 confirm（默认值为 false）：未设置 confirm=true 时，它们会返回将发生变更的 blast_radius，且不会进行任何变更；如果存在阻止条件（例如资源已处于维护状态）或字段不可读，则拒绝 confirm=true。旧别名 confirmed 已在 2.4.2 中移除；传入该参数的调用会因参数未知而被拒绝
• 默认启用 TLS 验证；使用私有 CA 时，请将 SSL_CERT_FILE 设置为包含该 CA 的证书包（参见设置指南）。verify_ssl: false 仅适用于隔离的自签名实验环境

Broadcom 官方参考资料

• REST API：https://developer.broadcom.com/xapis — VCF Operations API（原 Aria Operations suite-api）
• SDK：https://developer.broadcom.com/sdks — VCF Python SDK
• CLI 工具：https://developer.broadcom.com/tools — PowerCLI 9.1 包含“VCF Operations（原 vRealize Operations Manager）”cmdlet

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

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

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

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-aria 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-aria https://mcp.example.com:8443/mcp \
    --header "Authorization: Bearer $VMWARE_MCP_TOKEN"

{
  "mcpServers": {
    "vmware-aria": {
      "type": "http",
      "url": "https://mcp.example.com:8443/mcp",
      "headers": { "Authorization": "Bearer ${VMWARE_MCP_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；此请求无需令牌，只会返回 {"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-audit roles enable，然后为每个令牌分配一个角色（vmware-audit token create NAME --role reader，或在 roles.yaml 中配置角色并指定工具和目标；vmware-policy ≥ 1.24.0）。角色会限制令牌在此端点上可调用的内容，但不能授予超出账户已有权限的权限。请参阅 vmware-policy 的 README 中的 “Roles for network callers”。

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

vmware-aria mcp --expose read --allow-write acknowledge_alert
# or: VMWARE_ARIA_MCP_EXPOSE=read VMWARE_ARIA_MCP_ALLOW_WRITE=acknowledge_alert vmware-aria mcp

未提供的工具不会显示在客户端的工具列表中。值无效或写入工具未知时，服务会停止（退出代码 2）。这只会限制向客户端提供的工具；它不构成授权，因此账户本身应遵循最小权限原则。

详情：skills/vmware-aria/references/setup-guide.md（“Serving MCP over HTTPS”、“Limiting which tools are offered”）。

许可证

MIT — 参见 LICENSE