inventory-tool-guide

name	inventory-tool-guide
description	Guide for querying MTV provider inventory with TSL. Covers available resources per provider, output formats, TSL syntax, common pitfalls, and using inventory for network/storage mapping. Use when querying provider inventory.

Inventory Tool Guide

Use mtv_read with get inventory RESOURCE to query provider inventory. Use mtv_help for unfamiliar commands.

For field references and ready-to-use queries, load the appropriate per-provider skill: inventory-vsphere, inventory-ovirt, inventory-openstack, inventory-ec2, inventory-ova, inventory-hyperv, inventory-openshift.

---

Common Pitfalls

1. flags must be a JSON object — never pass it as a string.
   • Correct: "flags": {"namespace": "mtv", "output": "markdown"}
   • Wrong: "flags": "{namespace: mtv, output: markdown}"
2. fields is a top-level parameter, not a flag — use it on mtv_read directly (not inside flags) to limit response to specific top-level JSON keys (e.g. fields: ["metadata", "spec"]). Run mtv_help to see valid flags.
3. Discovering fields — use "output": "json" with "query": "limit 1" to inspect one object and see all available field names.
4. oVirt disk types live on a standalone resource — query get inventory disk, not the VM's diskAttachments, to find storageType = 'lun'.
5. EC2 and OVA use PascalCase field names — unlike vSphere/oVirt/OpenStack which use camelCase.

---

Provider Field Differences

Concept	vSphere	oVirt	OpenStack	EC2	OVA	HyperV	OpenShift
Power	powerState	status	status	State.Name	N/A	powerState	N/A (k8s)
Memory	memoryMB	memory (bytes!)	via flavorId	via InstanceType	memoryMB	memoryMB	N/A (k8s)
CPU	cpuCount	cpuSockets * cpuCores	via flavorId	via InstanceType	cpuCount	cpuCount	N/A (k8s)
Disks on VM	disks[*]	diskAttachments[*]	attachedVolumes[*]	BlockDeviceMappings	disks[*]	disks[*]	N/A
Standalone	N/A	get inventory disk	get inventory volume	get inventory volume	get inventory disk	get inventory disk	get inventory pvc
LUN/RDM	disks[*].rdm	disk.storageType + lunStorage	N/A	N/A	N/A	N/A	N/A
Field case	camelCase	camelCase	camelCase	PascalCase (AWS)	PascalCase (OVF)	camelCase	k8s objects

---

Resource Availability Matrix

Resource	vSphere	oVirt	OpenStack	EC2	OVA	HyperV	OpenShift
vm	Y	Y	Y	Y (ec2-instance)	Y	Y	Y
network	Y	Y	Y	Y (ec2-network)	Y	Y	Y (NAD)
storage	Y (datastore)	Y (storageDomain)	Y (volumeType)	Y (ec2-volume-type)	Y	Y	Y (storageClass)
disk	--	Y	--	--	Y	Y	--
volume	--	--	Y	Y (ec2-volume)	--	--	--
host	Y	Y	--	--	--	--	--
cluster	Y	Y	--	--	--	--	--
datacenter	Y	Y	--	--	--	--	--
folder	Y	--	--	--	--	--	--
resource-pool	Y	--	--	--	--	--	--
disk-profile	--	Y	--	--	--	--	--
nic-profile	--	Y	--	--	--	--	--
flavor	--	--	Y	--	--	--	--
image	--	--	Y	--	--	--	--
project	--	--	Y	--	--	--	--
subnet	--	--	Y	--	--	--	--
snapshot	--	--	Y	--	--	--	--
volumetype	--	--	Y	--	--	--	--
namespace	--	--	--	--	--	--	Y
pvc	--	--	--	--	--	--	Y
data-volume	--	--	--	--	--	--	Y

---

Output Formats

Format	Use when
markdown	Presenting results to the user (default).
json	Parsing results or discovering fields.
table	Compact display.
yaml	Structured output.
planvms	Export for create plan --vms @file.

---

TSL Query Syntax

Use the query flag to filter, sort, and project results. use pipe output to jq, grep, or other post-processing tools only in cases --query does not handle. The query flag handles filtering, field selection, sorting, and limiting natively.

TSL (Tree Search Language) supports four optional clauses, in this order:

[select <field>, ...] [where <condition>] [order by <field> [asc|desc]] [limit N]

All clauses are optional and can be combined freely.

select -- choose which fields to return

Use select to project only the fields you need (like SQL SELECT):

select name, cpuCount, memoryMB
select name, powerState, len(disks) as diskCount
select name, disks[*].capacity as diskSizes

where -- filter rows

where name ~= 'prod-.*'
where powerState = 'poweredOn' and memoryMB > 4096
where cpuCount > 4 and len(disks) > 1
where any(concerns[*].category = 'Critical')
where name in ['vm1', 'vm2', 'vm3']
where memoryMB between 2048 and 8192
where not (powerState = 'poweredOff')
where name is not null

order by -- sort results

order by name asc
order by memoryMB desc
order by cpuCount desc

limit -- cap the number of results

limit 10
limit 5

Combining clauses

select name, cpuCount, memoryMB where powerState = 'poweredOn' order by memoryMB desc limit 10
where name like '%web%' order by memoryMB desc limit 10
select name, powerState where cpuCount > 4 order by name asc
where memoryMB > 4096 limit 5
select name where any(concerns[*].category = 'Critical') order by name asc limit 20

Operators

• Comparison: =, !=, <>, <, <=, >, >=
• String: like (% wildcard), ilike (case-insensitive), ~= (regex), ~! (regex not)
• Logical: and, or, not
• Set: in [...], not in [...], between X and Y
• Null: is null, is not null

Array Functions

• len(field) -- array length: where len(disks) > 1
• any(field[*].sub = 'val') -- any element matches: where any(concerns[*].category = 'Critical')
• all(field[*].sub >= N) -- all elements match
• sum(field[*].sub) -- sum of values: where sum(disks[*].capacity) > 100Gi

Array Access

• field[0] -- index access
• field[*].sub -- wildcard across elements
• field.sub -- implicit traversal (same as field[*].sub)

SI Units

Ki (1024), Mi (1024^2), Gi (1024^3), Ti (1024^4)

---

Using Inventory for Mapping

Network mapping

1. List source networks: get inventory network with source provider
2. List target NADs: get inventory network with provider: "host"
3. Match by name, use in create mapping network

mtv_read { "command": "get inventory network", "flags": { "provider": "<SOURCE>", "namespace": "<NS>", "output": "json" } }

Storage mapping

1. List source datastores: get inventory datastore with source provider
2. List target StorageClasses: get inventory storage with provider: "host"
3. Match by name, use in create mapping storage

mtv_read { "command": "get inventory datastore", "flags": { "provider": "<SOURCE>", "namespace": "<NS>", "output": "json" } }