Skills
skills/rhecosystemappeng/agentic-collections/vm-inventory

vm-inventory

SKILL.md

/vm-inventory Skill

List and inspect virtual machines in OpenShift Virtualization clusters. This skill provides read-only access to VM information without making any modifications.

Prerequisites

Required MCP Server: openshift-virtualization (OpenShift MCP Server)

Required MCP Tools:

  • resources_list (from openshift-virtualization) - List Kubernetes resources including VirtualMachines
  • resources_get (from openshift-virtualization) - Get specific Kubernetes resource details

Fallback CLI Commands (if MCP tools unavailable):

  • oc get virtualmachines / oc get vm - List VirtualMachines
  • oc get vm <name> -n <namespace> -o yaml - Get VM details

Required Environment Variables:

  • KUBECONFIG - Path to Kubernetes configuration file with cluster access

Required Cluster Setup:

  • OpenShift cluster (>= 4.19)
  • OpenShift Virtualization operator installed
  • ServiceAccount with RBAC permissions to list and get VirtualMachine resources

Prerequisite Verification

Before executing:

  1. Check openshift-virtualization exists in .mcp.json → If missing, report setup
  2. Verify KUBECONFIG is set (presence only, never expose value) → If missing, report
  3. (Optional) Test basic connectivity to cluster → If fails, report connection error

Human Notification Protocol: ❌ Cannot execute vm-inventory: MCP server not available. Setup: Add to .mcp.json, set KUBECONFIG, restart Claude Code. Docs: https://github.com/openshift/openshift-mcp-server

⚠️ SECURITY: Never display KUBECONFIG path or credential values.

Note on Fallback: If MCP server unavailable but KUBECONFIG set, offer CLI fallback with user confirmation.

When to Use This Skill

Trigger when:

  • User explicitly invokes /vm-inventory command
  • User wants to see all VMs or VMs in a specific namespace
  • User asks about VM status or health
  • User needs to find a VM by name
  • User wants details about a specific VM configuration

User phrases:

  • "List all VMs"
  • "Show VMs in production namespace"
  • "What VMs are running?"
  • "Get details of VM web-server"
  • "Show me the status of database-vm"
  • "/vm-inventory" (explicit command)

Do NOT use when:

  • User wants to create a VM → Use /vm-create skill instead
  • User wants to start/stop VMs → Use /vm-lifecycle-manager skill instead
  • User wants to modify VM configuration → Different operation (not inventory)

Workflow

CRITICAL EXECUTION PATTERN:

  1. ALWAYS attempt MCP server tools FIRST - Try resources_list or resources_get
  2. If MCP tools fail - Propose CLI commands (oc get vm) with user confirmation
  3. Never skip MCP attempt - Always try them first

Tool Execution Priority: MCP tools (primary) → CLI commands (fallback with confirmation)

Workflow A: List All VMs (Across All Namespaces)

Step 1: Query VirtualMachine Resources Using MCP Tool

MCP Tool: resources_list (apiVersion="kubevirt.io/v1", kind="VirtualMachine", allNamespaces=true)

Errors: Tool not found/connection error → Report, offer CLI fallback: oc get virtualmachines -A -o json

Step 2: Get Resource Details for Running VMs

CRITICAL: To display complete VM information, query VirtualMachineInstance (VMI) resources:

MCP Tool: resources_list (apiVersion="kubevirt.io/v1", kind="VirtualMachineInstance")

For each VMI, extract:

  • .spec.domain.cpu.sockets and .spec.domain.memory.guest - Resources column ("X vCPU, YGi")
  • .status.volumeStatus[].persistentVolumeClaimInfo.capacity.storage - Storage column (sum all PVC volumes, exclude container disks/cloudinit)
  • .status.guestOSInfo.prettyName or .status.guestOSInfo.name + version - Guest OS column
  • .status.interfaces[0].ipAddress - IP column (primary interface)
  • .status.nodeName - Node column
  • .status.conditions[] - Conditions column (Ready, AgentConnected, LiveMigratable)

Stopped VMs: Use VirtualMachine spec for Resources only; Storage/Guest OS/IP/Conditions show "-"

Step 3: Format and Display Results

ALWAYS display in table format ordered by namespace and status:

## 📋 Virtual Machines (All Namespaces)

| Namespace | VM Name | Status | Age | Resources | Storage | Guest OS | Node | IP | Conditions |
|-----------|---------|--------|-----|-----------|---------|----------|------|----|------------|
| development | debug-vm | ⚠ Pending | 2d | 2 vCPU, 4Gi | 30Gi | - | - | - | ⚠ Not Ready |
| development | test-vm | ✓ Running | 5d | 2 vCPU, 4Gi | 30Gi | Ubuntu 24.04 | worker-03 | 10.131.0.20 | ✓ Ready, ✓ Live Migration |
| production | database-vm | ✗ Stopped | 30d | 8 vCPU, 16Gi | - | - | - | - | - |
| production | web-server-01 | ✓ Running | 15d | 4 vCPU, 8Gi | 100Gi | RHEL 9.7 | worker-01 | 10.131.0.15 | ✓ Ready, ✓ Agent, ✗ Live Migration |
| production | web-server-02 | ✓ Running | 15d | 4 vCPU, 8Gi | 100Gi | RHEL 9.7 | worker-02 | 10.131.0.16 | ✓ Ready, ✓ Agent, ✗ Live Migration |

**Summary:**
- **Total VMs**: 5
- **Running**: 3
- **Stopped**: 1
- **Pending**: 1

Table Ordering Rules:

  1. Primary sort: Namespace (alphabetical)
  2. Secondary sort: Status (Running → Pending → Stopped → Failed/Error)
  3. Tertiary sort: VM Name (alphabetical within same namespace and status)

Status Indicators:

  • ✓ Running/Ready
  • ✗ Stopped/Halted
  • ⚠ Pending/Starting/Terminating
  • ❌ Failed/Error

Resources Column Format: MUST show "X vCPU, YGi" (query VMI .spec.domain.cpu.sockets and .spec.domain.memory.guest), NOT instance type names (e.g., NOT "u1.medium")

Workflow B: List VMs in Specific Namespace

Step 1: Gather Namespace

Ask user for namespace if not provided.

Step 2: Query VMs in Namespace Using MCP Tool

MCP Tool: resources_list (apiVersion="kubevirt.io/v1", kind="VirtualMachine", namespace=<namespace>)

Errors: Tool fails → Report, offer CLI fallback: oc get virtualmachines -n <namespace> -o json

Step 3: Get Resource Details and Display

Follow same format rules as Workflow A Step 2-3. Use namespace-specific header:

## 📋 Virtual Machines in '<namespace>'

| Name | Status | vCPU | Memory | Age | Node |
|------|--------|------|--------|-----|------|
| web-server-01 | Running | 4 | 8Gi | 15d | worker-01 |
| web-server-02 | Running | 4 | 8Gi | 15d | worker-02 |
| database-vm | Stopped | 8 | 16Gi | 30d | - |

**Summary**: 3 VMs (2 running, 1 stopped)

Workflow C: Get Details of Specific VM

Step 1: Gather VM Information

Required: VM name, Namespace (ask if not provided)

Step 2: Retrieve VM Resource Details Using MCP Tool

MCP Tool: resources_get (apiVersion="kubevirt.io/v1", kind="VirtualMachine", namespace=<namespace>, name=<vm-name>)

Errors: Tool fails → Report, offer CLI fallback: oc get vm <vm-name> -n <namespace> -o yaml

Step 3: Interpret Status and Conditions (Optional)

OPTIONAL: If VM has error status (ErrorUnschedulable, ErrorDataVolumeNotReady, CrashLoopBackOff), consult troubleshooting/INDEX.md using Read tool. Output: "Consulted INDEX.md to interpret status."

When to consult: VM status is Error/Warning or stuck state (CrashLoopBackOff, Terminating) When NOT to consult: VM status is normal (Running, Stopped, Provisioning)

Step 4: Display Detailed Information

## 🖥️ Virtual Machine Details

### Basic Information
- **Name**: `web-server-01`
- **Namespace**: `production`
- **Status**: Running
- **Created**: 15 days ago

### Configuration
- **Instance Type**: u1.medium
- **Workload**: Fedora
- **Run Strategy**: Always (auto-restart on crash)

### Resources
- **vCPU**: 4 cores
- **Memory**: 8Gi
- **Storage**: 50Gi
- **Storage Class**: ocs-storagecluster-ceph-rbd

### Network
- **Primary**: default (pod network)
- **Secondary**: vlan100 (multus - 192.168.100.5)

### Volumes
- **rootdisk**: 50Gi (DataVolume/PVC)

### Current State
- **Phase**: Running
- **Ready**: True
- **Node**: worker-01
- **Pod IP**: 10.129.2.45
- **Guest OS Uptime**: 12 days

### Conditions
- ✓ Ready
- ✓ LiveMigratable
- ✓ AgentConnected

### Labels
- app: web
- env: production
- tier: frontend

Workflow D: Filter VMs by Criteria

Step 1: Query VMs with Filters Using MCP Tool

MCP Tool: resources_list (apiVersion="kubevirt.io/v1", kind="VirtualMachine", allNamespaces=true, labelSelector=<selector>)

Filtering options:

  • By Labels (via labelSelector): "app=web", "app=web,env=production", "tier in (frontend,backend)"
  • By Status (post-processing): Filter results by status.printableStatus field
  • By Resource Size (post-processing): Parse instance type or VMI resource specs

Errors: Tool fails → Report, offer CLI fallback: oc get virtualmachines -A -l <labelSelector> -o json

Step 2: Display Filtered Results

Display with explanation: ## 📋 VMs with label 'app=web' + list/table using Workflow A format

Common Issues

Issue 1: No VMs Found

Error: Empty list | Causes: No VMs exist, wrong namespace, insufficient RBAC | Response: Report no VMs found, suggest create VM (vm-create), list namespaces, check permissions

Issue 2: Permission Denied

Error: "Forbidden: User cannot list VirtualMachines" | Solution: Verify KUBECONFIG has list/get permissions, contact admin

Issue 3: Cluster Connection Error

Error: "Unable to connect to cluster" | Solution: Verify KUBECONFIG valid, check oc cluster-info, verify network, check credentials expiry

Output Formatting Guidelines

Use consistent status indicators:

  • ✓ Running/Healthy/Ready
  • ✗ Stopped/Halted
  • ⚠ Warning/Pending/Migrating
  • ❌ Critical/Failed/Error

Include key information always:

  • VM name and namespace
  • Current status
  • Resource allocation (vCPU, memory)
  • Age/creation time
  • Node placement (for running VMs)

Organize by namespace when showing multiple VMs for logical grouping and clear separation.

Provide actionable next steps: How to start stopped VMs, get more details, when to use other skills

Integration with Other Skills

Before creating a VM (vm-create): Use vm-inventory to check if VM name exists, verify namespace has capacity Before lifecycle operations (vm-lifecycle-manager): Check current VM status, verify VM exists For troubleshooting: Get VM overview with vm-inventory first, then use vm-troubleshooter for deep diagnostics

Dependencies

Required MCP Servers

Required MCP Tools (PRIMARY - Always try first)

  • resources_list - List resources (apiVersion, kind, namespace optional, allNamespaces optional, labelSelector optional)
  • resources_get - Get resource details (apiVersion, kind, namespace, name)

CLI Fallback Commands (Use only if MCP tools fail)

  • oc get virtualmachines / oc get vm - List VirtualMachines
  • oc get vm <name> -n <namespace> - Get specific VM
  • oc get vm -A - List VMs across all namespaces
  • oc get vm -n <namespace> - List VMs in specific namespace
  • oc get vm -l <selector> - Filter VMs by label selector

Important: Always attempt MCP tools first. Only use CLI commands after MCP tool failure and with user confirmation.

Related Skills

  • vm-create - Create VMs after checking inventory
  • vm-lifecycle-manager - Manage VMs discovered in inventory
  • vm-troubleshooter (planned) - Diagnose problematic VMs from inventory

Reference Documentation

Critical: Human-in-the-Loop Requirements

Not applicable - This skill performs read-only operations and does not modify any cluster resources. No user confirmation required.

Read-only operations:

  • Listing VirtualMachines across namespaces or in specific namespaces
  • Retrieving VM details, status, and resource configurations
  • Displaying VM health conditions and resource usage
  • Filtering VMs by labels or field selectors
  • Viewing VM network, storage, and node placement information

No modifications performed:

  • ✓ Does not change VM state (start/stop/restart)
  • ✓ Does not modify VM configuration
  • ✓ Does not delete VMs or resources
  • ✓ Does not consume cluster resources

Security Considerations

  • Read-only operations - no modifications to VMs
  • Respects Kubernetes RBAC permissions
  • Only shows VMs in namespaces user has access to
  • KUBECONFIG credentials never exposed in output
  • No sensitive VM configuration details displayed by default
  • All queries audited in Kubernetes API logs

Example Usage

Example 1: List all VMs (table format)

User: "List all VMs"
Agent: [MCP: resources_list(apiVersion="kubevirt.io/v1", kind="VirtualMachine", allNamespaces=true)]
       [Queries VMI resources for CPU/memory]
       [Displays table format from Workflow A Step 3]

Example 2: CLI fallback when MCP unavailable

User: "List all VMs"
Agent: [MCP tool fails]
       ⚠️ MCP tool 'resources_list' not available. Use CLI: `oc get virtualmachines -A`?
User: "yes"
Agent: [Executes: oc get virtualmachines -A -o json]
       [Displays table format]

Example 3: Get specific VM details

User: "Show me details of web-server-01 in production"
Agent: [MCP: resources_get(kind="VirtualMachine", namespace="production", name="web-server-01")]
       [Displays VM Details format from Workflow C Step 4]

Example 4: Filter running VMs

User: "Show me all running VMs"
Agent: [Lists all VMs, filters by status.printableStatus == "Running"]
       ## ✓ Running Virtual Machines
       ### production: web-server-01 (4 vCPU, 8Gi, worker-01) | web-server-02 (4 vCPU, 8Gi, worker-02)
       ### development: test-vm (2 vCPU, 4Gi, worker-03)
       **Total**: 3 running VMs
Weekly Installs
1
Repository
rhecosystemappe…lections
GitHub Stars
4
First Seen
7 days ago
Security Audits
Gen Agent Trust HubPass
SocketPass
SnykPass
Installed on
claude-code1