VMware Aria Operations#

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 "Aria" are trademarks of Broadcom. Source code is publicly auditable at github.com/vmware-skills/VMware-Aria under the MIT license.

VMware Aria Operations (vRealize Operations 8.x, VCF Operations 9.x) AI-assisted monitoring — 46 MCP tools, by category below.

Know the version first: vmware-aria health status (MCP get_aria_health) names the product line. Fleet, findings and PromQL exist only on VCF Operations 9.0+ (PromQL uses the 9.1 VODAP service); on 8.x they return a "requires 9.0 or newer" error, not data. Companion skills: vmware-monitor (real-time vSphere), vmware-aiops (VM lifecycle), vmware-nsx (networking), vmware-avi (AVI/ALB/AKO), vmware-harden (compliance), vmware-pilot (approval workflows), vmware-policy (audit/policy).

What This Skill Does#

CategoryToolsCountResourceslist, get details, metrics, health badge, top consumers, metric keys, properties, relationships8Alertslist, get details, investigate (alert→resource), acknowledge, cancel, list definitions, list/add notes, recommendations9Alert Definitionslist symptoms, create definition, enable/disable, delete4Capacitycluster overview, remaining capacity, time remaining, rightsizing4Reportslist templates, generate, list, get status+download URL, delete5Anomalylist anomalies, risk badge2HealthAria platform health, collector group status, Aria node memory/swap/heap, adapter collection state4Maintenancestart / end resource maintenance, list maintenance schedules3Fleet / PromQL (VCF Ops 9.1)fleet certificates, password accounts, VCF domains, diagnostic findings, real-time PromQL query5Raw APIsearch the API operation index; GET one indexed path (read-only escape hatch)2

Total: 46 tools (36 read-only + 10 write)

Quick Install#

bash

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

When to Use This Skill#

• Lookup: which metric keys a resource reports (name, unit) before querying them, its properties, its parents and children
• Performance: VM contention (CPU Ready, balloon, swap), time-series metrics, top consumers, anomaly counts and risk badges
• Alerts: list, investigate, acknowledge or cancel alerts; read or add notes (who is handling it); read the alert's prioritized recommendations; list, create, enable/disable or delete alert definitions (post-RCA)
• Capacity: cluster headroom, time until full, VM rightsizing
• Reports: generate, poll, download and delete reports
• Maintenance: put a resource in maintenance before planned work (timed or until ended), end it, list maintenance schedules
• Anything else the API reads: when no tool answers, search_api_operations then one get_api_path (GET of an indexed path only)
• Platform: is Aria Operations itself healthy (DEGRADED vs DOWN, which service), which version and product line, collector groups, whether the Aria node is short of memory, which adapter stopped collecting

For VM changes, NSX, vSphere alarms, storage or load balancing, route with the table below.

Related Skills — Skill Routing#

User IntentRecommended SkillAria Operations monitoring, alerts, capacityvmware-aria ← this skillVM lifecycle, deployment, guest opsvmware-aiopsNSX networking: segments, gateways, NAT, routingvmware-nsxRead-only vSphere inventory, events, alarmsvmware-monitorStorage: iSCSI, vSAN, datastoresvmware-storageMulti-step workflows with approvalvmware-pilotCompliance baselines (CIS / 等保 / PCI-DSS), drift detection, LLM remediation advisorvmware-harden ( uv tool install vmware-harden)Load balancer, AVI, ALB, AKO, Ingressvmware-avi ( uv tool install vmware-avi)Audit log queryvmware-policy ( vmware-audit CLI)

Common Workflows#

Troubleshooting paths: step-by-step playbooks for a DEGRADED platform, alert triage, VM contention, empty metrics, pre-resize checks and planned maintenance — references/ops-playbooks.md.

Diagnostic investigations: before any "why is X slow / failing / down" report, follow references/investigation-protocol.md — four root-cause criteria and up to three deepening rounds; never stop at a partial conclusion.

Daily VM Health Check (Proactive Ops)#

Judgment: don't chase the highest CPU consumer — chase the highest contention consumer. A VM at 90% CPU on a quiet host is healthy; a VM at 30% CPU but 15% Ready is starving. Key metrics: CPU Ready, Memory Balloon, Disk Latency.

1. Find top CPU consumers → vmware-aria resource top --metric 'cpu|usage_average' --top 20 (this is the starting set, not the answer)
2. Check CPU Ready on hot VMs → vmware-aria resource metrics <vm-id> --metrics 'cpu|readyPct' --hours 24

   • 5% = warning, >10% = problem, >20% = critical

3. Check memory pressure → vmware-aria resource metrics <vm-id> --metrics 'mem|balloonPct,mem|swapped_average' --hours 24
   • Balloon >0 = ESXi reclaiming memory; Swap >0 = severe — act immediately
   • If a key comes back under missing instead of metrics, it is not a zero: not_collected_for_resource means a wrong key for this resource (use similar_keys), no_data_in_window means widen --hours
4. List active CRITICAL/IMMEDIATE alerts → vmware-aria alert list --criticality CRITICAL
5. Check anomaly counts → vmware-aria anomaly list
6. Cross-validate against the investigation protocol before reporting any "root cause" — high consumption is rarely the root, usually a downstream symptom

Capacity Planning#

1. List clusters → vmware-aria resource list --kind ClusterComputeResource

2. Get remaining capacity → vmware-aria capacity remaining <cluster-id>

3. Predict time until full → vmware-aria capacity time-remaining <cluster-id>

4. Get capacity overview → vmware-aria capacity overview <cluster-id>

5. Find rightsizing candidates → vmware-aria capacity rightsizing — act only on rows with Act. yes; read each VM's caveats and the vendor minimum size before reducing

   • If a yellow properties_note prints under the table, the VM property read failed: power state and current size are unknown and no row is actionable — retry, do not resize from it

Post-Incident: Create Detection Alert (RCA Follow-up)#

After an incident, create an early-warning alert. Alert definition management is MCP-only:

1. Find matching symptom definitions → MCP list_symptom_definitions (filter by name_filter / resource_kind)
2. Create alert definition referencing symptoms → MCP create_alert_definition with name, resource_kind, symptom_definition_ids, criticality (any one symptom firing triggers the alert)
3. Verify it appears in definitions → vmware-aria alert definitions --name "Gold VM CPU" (criticality shown is the max severity across the definition's states)
4. Enable or disable later → MCP set_alert_definition_state

Generate Capacity Report#

1. Find report template → vmware-aria report definitions --name "Capacity"
2. Trigger report generation → vmware-aria report generate <definition-id> --resources <resource-id> (the Report API requires at least one resource UUID)
3. Poll until completed → vmware-aria report get <report-id> (repeat until status == COMPLETED)
4. Download via the returned download_url (PDF) or csv_url
5. Clean up → vmware-aria report delete <report-id>

Usage Mode#

ScenarioRecommendedWhyLocal/small models (Ollama, Qwen)CLI~2K tokens vs ~8K for MCPCloud models (Claude, GPT-4o)EitherMCP gives structured JSON I/OAutomated pipelinesMCPType-safe parameters, structured output

Running vmware-aria with a local or small model? See references/agent-guardrails.md for tool-calling guardrails (alert-to-resource correlation and Aria data fidelity).

Every command accepts --target <name> (every MCP tool target) to pick the Aria Operations instance.

MCP Tools (46 — 36 read, 10 write)#

All MCP tools accept an optional target. The six destructive writes take confirm: without confirm=true they return a blast_radius and change nothing — show it to the user first.

CategoryToolTypeDescriptionResourcelist_resourcesReadList VMs, hosts, clusters by resource kind (or all); collection_status finds objects not receiving dataget_resourceReadGet resource details with health, risk, efficiency badgesget_resource_metricsReadTime-series stats; interval_type=DAYS for long windows; summary=true gives min/max/avg/latest; missing explains absentget_resource_healthReadBadge scores; service objects add service.available (a badge is not service state)get_top_consumersReadRank by last-hour average value ( latest_value = newest point)list_metric_keysReadKeys a resource reports with name/unit and definition, or a kind's defined keys — look up before queryingget_resource_propertiesReadCurrent property values (power state, parent host, extraConfig)get_resource_relationshipsReadRelated resources with direction; relationship_type ALL / PARENT / CHILDAlertslist_alertsReadList active alerts with criticality, resource ID, name and kind ( resource_name: null = unknown, see resource_names_note)get_alertReadAlert details: named symptoms, the object each is on (e.g. the down service), ISO-8601 timesinvestigate_alertReadResolve an alert to its confirmed affected resource in one call — returns both UUIDs explicitly labelled plus the vmware-monitor handoffacknowledge_alertWriteMark an alert as acknowledged (does not close it)cancel_alertWriteCancel (dismiss) an active alertlist_alert_definitionsReadList alert templates configured in Aria Opslist_alert_notesReadNotes on an alert (who is handling it, what was done)add_alert_noteWriteAdd a note; does not change the alert's status (low risk, not idempotent)get_alert_recommendationsReadPrioritized recommendations from the alert's definition; status found / partial / none_defined / unknownAlert Defslist_symptom_definitionsReadList symptom definitions — use IDs when creating alert defscreate_alert_definitionWriteCreate new alert definition from symptom definition IDsset_alert_definition_stateWriteEnable or disable an alert definitiondelete_alert_definitionWriteDelete an alert definition permanentlyCapacityget_capacity_overviewReadGroup-level remaining % + per-dimension headroom and days-until-fullget_remaining_capacityReadRemaining CPU, memory, disk before hitting limitsget_time_remainingReadDays until cluster capacity is exhaustedlist_rightsizing_recommendationsReadPer-VM recommended size (raw MHz/KB/GB; use recommended_vcpus), direction, power state, recommendation_stable / recommendation_range (7-day movement), actionable, caveats, properties_note, history_noteReportslist_report_definitionsReadList available report definition templatesgenerate_reportWriteTrigger report generation (async; returns report_id)list_reportsReadList generated reports, optionally by definitionget_reportReadPoll report status + get PDF/CSV download URLsdelete_reportWriteDelete a generated reportAnomalylist_anomaliesReadPer-resource anomaly counts (System Attributes|total_alarms metric)get_resource_riskbadgeReadRisk score (0–100): likelihood of future problemsHealthget_aria_healthReadPlatform assessment (HEALTHY/DEGRADED/DOWN/UNKNOWN), per-service health, product versionlist_collector_groupsReadCollector agents status and connectivityget_aria_node_resourcesReadAria node memory/swap/heap and watchdog restarts; memory pressure NORMAL / ELEVATED / HIGH / UNKNOWNlist_adaptersReadAdapter instances, last collection age, staleMaintenancestart_resource_maintenanceWriteTimed ( duration_minutes / end_time_ms) or manual maintenance; before/after state; undo = endend_resource_maintenanceWriteEnd maintenance; refuses a resource not known to be in maintenancelist_maintenance_schedulesReadRecurring maintenance schedules, optionally for one resource_idFleet / PromQL (VCF Ops 9.1)list_fleet_certificatesReadCertificate status/expiry across the VCF fleetlist_fleet_password_accountsReadManaged password-account status (read-only; does not rotate)list_fleet_domainsReadSDDC/workload domains behind one registered VCF integrationlist_findingsReadOperations diagnostic findings (not compliance — see vmware-harden)promql_queryReadReal-time PromQL instant query via the VODAP service (base path INFERRED, unverified on real hardware)Raw APIsearch_api_operationsReadSearch the shipped 8.6 / 9.1 operation index; marks GET operationsget_api_pathReadGET one indexed path ( {id} filled in, query in params); sanitized, capped at 30,000 chars ( truncated)

Read/write split: 36 read-only, 10 write. All write operations are audit-logged to ~/.vmware/audit.db (via vmware-policy).

List results are envelopes — read truncated before you summarise#

List tools return {items, returned, limit, total, truncated, hint}, not a bare array. Rows are under items; truncated: true means more rows exist — never call it the complete set; total: null means the API gave no size. Full rules, per-tool total sources and list_anomalies' scan fields: references/capabilities.md.

CLI Quick Reference#

bash

# Resources
vmware-aria resource list [--kind VirtualMachine|HostSystem|ClusterComputeResource|all] [--name <filter>] [--collection-status NO_DATA_RECEIVING]
vmware-aria resource get <resource-id>
vmware-aria resource metrics <resource-id> --metrics 'cpu|usage_average,mem|usage_average' --hours 4
vmware-aria resource metrics <vm-id> --metrics 'cpu|readyPct,mem|balloonPct' --hours 24 --summary
vmware-aria resource health <resource-id>
vmware-aria resource top --metric 'cpu|usage_average' --kind VirtualMachine --top 10
vmware-aria resource keys <resource-id> [--filter 'mem|']   # or --kind VirtualMachine
vmware-aria resource properties <resource-id> [--name 'summary|']
vmware-aria resource relationships <resource-id> [--type PARENT]

# Alerts
vmware-aria alert list [--criticality CRITICAL|IMMEDIATE|WARNING|INFORMATION] [--json]
vmware-aria alert get <alert-id>
vmware-aria alert acknowledge <alert-id>
vmware-aria alert cancel <alert-id>
vmware-aria alert definitions [--name <filter>]
vmware-aria alert notes <alert-id>
vmware-aria alert note-add <alert-id> "Taking this: rebooting esx-03"
vmware-aria alert recommendations <alert-id>

# Alert definitions and symptom lookup are MCP-only (no CLI subcommands).

# Capacity
vmware-aria capacity overview <cluster-id>
vmware-aria capacity remaining <resource-id>
vmware-aria capacity time-remaining <resource-id>
vmware-aria capacity rightsizing [--resource-id <vm-id>]

# Reports (async: generate → poll get → download → delete)
vmware-aria report definitions [--name <filter>]
vmware-aria report generate <definition-id> --resources <id1,id2>   # at least one resource UUID required
vmware-aria report list [--definition-id <id>]
vmware-aria report get <report-id>        # poll until status == COMPLETED; shows download_url
vmware-aria report delete <report-id>

# Anomaly
vmware-aria anomaly list [--resource-id <id>]
vmware-aria anomaly risk <resource-id>

# Health
vmware-aria health status
vmware-aria health collectors
vmware-aria health node [--hours 24]        # Aria node memory pressure, watchdog restarts
vmware-aria health adapters [--kind VMWARE] # stale = last collection older than max(3 x interval, 15 min)

# Maintenance (writes ask once; --yes skips, --dry-run prints the API call without connecting)
vmware-aria maintenance start <resource-id> --duration 60   # neither --duration nor --end = until `maintenance end`
vmware-aria maintenance end <resource-id>
vmware-aria maintenance schedules [--resource-id <id>]

# Raw API (read-only: GET of an indexed path only)
vmware-aria api search "resource properties" [--limit 20]
vmware-aria api get /api/resources/<id>/properties [--param pageSize=20]

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

Key Metric Names (for resource metrics command)#

MetricAPI KeyUnitWhat It MeansCPU Readycpu|readyPct%vCPU waiting for a physical core; >5% = warningCPU Usagecpu|usagemhz_averageMHzCPU actually usedCPU Demandcpu|demandmhzMHzCPU the VM requestedMemory Consumedmem|consumed_averageKBFootprint on host (capacity)Memory Balloonmem|balloonPct%>0 = ESXi reclaiming memoryMemory Swappedmem|swapped_averageKB**>0 = severe pressure**Memory Contentionmem|host_contentionPct%Contention for host memoryDisk ThroughputvirtualDisk|read_average, virtualDisk|write_averageKBpsRead / write rateDisk LatencyvirtualDisk|peak_vDisk_readLatency, virtualDisk|peak_vDisk_writeLatencymsHighest across the VM's virtual disksNetworknet|received_average, net|transmitted_averageKBpsReceive / transmit rate

VirtualMachine keys and units as defined on Aria Operations 8.18.7; other resource kinds use different keys. Unreported keys come back under missing.

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

Troubleshooting#

"Token not found" error after setup#

Token acquisition failed. Verify:

1. Aria Ops is reachable: vmware-aria doctor
2. The auth_source in config matches your environment (LOCAL, LDAP, AD)
3. The password env var follows the naming convention: VMWARE_ARIA_<TARGET>_PASSWORD

Resources appear missing from list_resources#

A collector may be offline: list_collector_groups shows DOWN ones. Restart it in the Aria Ops UI (Administration > Collector Groups).

Metrics return empty data#

Read missing[].reason: not_collected_for_resource (wrong key for this resource — try similar_keys), no_data_in_window (widen --hours, check collectors), resource_reports_no_stat_keys, or undetermined. Never report a missing key as zero.

health status says OFFLINE (HTTP 503) but data still flows#

The node flag is OFFLINE whenever any one service is not running. Read assessment: DEGRADED means some services are OK and others are not — not an outage. Seen on Aria Operations 8.18.7 with only LOCATOR not OK; services_not_ok names the failed ones.

"Password not found" error#

Set VMWARE_ARIA_<TARGET_NAME_UPPER>_PASSWORD (hyphens become underscores; target prod → VMWARE_ARIA_PROD_PASSWORD) in ~/.vmware-aria/.env.

invalid peer certificate: UnknownIssuer when running uvx (corporate TLS proxy)#

uvx re-resolves from PyPI on every launch, and a TLS-intercepting proxy breaks that. Run vmware-aria mcp after uv tool install vmware-aria==2.3.0 (no network on launch), or set UV_NATIVE_TLS=true to use the system cert store.

Audit & Safety#

1. Source code: github.com/vmware-skills/VMware-Aria (MIT).
2. Config and credentials: config.yaml holds hosts and usernames only; passwords live in ~/.vmware-aria/.env (chmod 600) as VMWARE_ARIA_<TARGET>_PASSWORD and are never logged.
3. No webhooks: no outbound calls besides the Aria Operations REST API over HTTPS 443; the MCP server is local stdio.
4. TLS: verification on by default; for a private CA set SSL_CERT_FILE rather than verify_ssl: false (isolated labs only).
5. Prompt-injection defense: API text is sanitized (control characters stripped, length capped) before it reaches the agent.
6. Least privilege: use an Aria Operations account with read-only roles unless the write tools (alert acknowledge/cancel, alert notes, alert definitions, reports, resource maintenance) are needed.

Every tool call goes through vmware-policy ( @vmware_tool): audited to ~/.vmware/audit.db, subject to ~/.vmware/rules.yaml deny rules and maintenance windows, each tool risk-tagged. View with vmware-audit log --last 20 or --status denied. The suite-api token is re-acquired automatically before it expires. Setup, multiple targets, MCP clients and Docker: references/setup-guide.md.

License#

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