cluster-inventory

MCP-First Approach: This skill uses MCP tools from openshift-self-managed and openshift-ocm-managed servers. MCP tools have absolute priority.

CLI Tools Policy:

• ✅ ALWAYS use MCP tools when available
• ⚠️ Last resort only: CLI commands (oc, kubectl) may be attempted if no MCP alternative exists
• ⚠️ Assume unavailable: CLI tools are likely not installed in the execution environment

List and inspect OpenShift clusters across all types (OCP, SNO, ROSA, ARO, OSD).

Prerequisites

Required MCP Servers: openshift-self-managed, openshift-ocm-managed

Required MCP Tools:

• list_clusters (from both servers) - Lists clusters (auto-routes to correct API)
• cluster_info (from both servers) - Gets cluster details
• cluster_events (from openshift-self-managed only) - Gets events for self-managed clusters
• cluster_logs_download_url (from openshift-self-managed only) - Gets log download URL for diagnostics

Environment Variables: OFFLINE_TOKEN - Red Hat authentication token

Verification Steps:

1. Verify both MCP servers exist in mcps.json
2. Check OFFLINE_TOKEN is set: test -n "$OFFLINE_TOKEN" && echo "✓" || echo "✗"
3. If missing → Stop and report error with setup instructions

Prerequisite Failure Handling: If prerequisites fail, report the missing requirement and stop execution.

Security: Never display credential values.

When to Use This Skill

Use when:

• "List all clusters" / "Show my clusters" / "What clusters do I have?"
• User wants cluster status or installation progress
• User needs detailed cluster info (version, config, hosts)
• User wants to inspect cluster events for troubleshooting

Cluster Types: OCP, SNO, ROSA, ARO, OSD (all supported)

Do NOT use when:

• Create cluster → Use /cluster-creator skill
• Modify cluster → Use cluster management skills
• Delete cluster → Use cluster deletion skill

Filtering Capabilities

Optional Filters (apply when user requests):

• cluster_type: Filter by type - "all" (default), "self-managed", "managed", "rosa", "aro", "osd", "ocp", "sno"
• status_filter: Filter by status - "all" (default), "ready", "installed", "installing", "error", "pending-for-input"
• name_search: Partial match on cluster name (case-insensitive)

Examples:

• "List only ROSA clusters" → cluster_type="rosa"
• "Show clusters in error state" → status_filter="error"
• "Find clusters with 'prod' in name" → name_search="prod"

Query Strategy: ALWAYS query BOTH MCP servers by default unless user explicitly filters by cluster type.

Performance Guidance:

• >20 clusters: Display summary only, ask user before fetching detailed info for all
• Parallel calls: When fetching cluster_info for multiple clusters, limit to 5 concurrent calls
• Large accounts: Consider filtering by type or status to reduce output

Output Formatting

Summary Header (always first):

📊 Found X cluster(s): Y installed ✅, Z installing ⏳, ...

Single cluster (1): Detailed bullet list with all fields:

**Cluster: cluster-name**
- ID: full-uuid
- Status: ✅ ready
- Type: ROSA
- Version: 4.21.5
- Provider: AWS
- Region: us-east-1

Multiple clusters (≥2): Table format with full cluster IDs:

| Name | ID | Status | Type | Version | Provider | Region |
|------|----|-----------------------|------|---------|----------|--------|
| name | full-uuid | ✅ ready | ROSA | 4.21.5 | AWS | us-east-1 |

Status Icons: ✅ ready/installed, ⏳ installing, ⚠️ pending-for-input, ❌ error

Cluster Type Detection:

• OCM clusters: Check cloud_provider.id → aws=ROSA, azure=ARO, gcp=OSD
• Self-managed: Check platform → none+single_node=SNO, else=OCP

Sorting: Sort by type (OCP→ROSA→ARO→OSD→SNO), then by creation date (newest first)

Workflow

Step 1: List All Clusters

MCP Tools: Call BOTH in parallel (unless user explicitly filters by type)

• list_clusters (from openshift-self-managed) → Gets OCP, SNO clusters
• list_clusters (from openshift-ocm-managed) → Gets ROSA, ARO, OSD clusters

Parameters: None (MCP tools have no parameters)

Apply Filters (post-processing after fetching results):

• If user specified cluster_type: Filter results to matching types
• If user specified status_filter: Filter results to matching statuses
• If user specified name_search: Filter results containing search string (case-insensitive)

Expected Output: Combined list with name, ID, version, status, platform, creation date

Merge & Display:

1. Merge results from both APIs
2. Detect cluster type (see Output Formatting section)
3. Sort by type (OCP→ROSA→ARO→OSD→SNO), then date (newest first)
4. Display with summary header + list/table format

Error Handling:

• Both APIs fail → Verify OFFLINE_TOKEN and connectivity
• One API fails → Show partial results with note
• No clusters → Report "No clusters found"

Step 2: Get Detailed Cluster Information (Optional)

Execute when user requests details for specific cluster.

MCP Tool: cluster_info (from correct server based on cluster source) Parameters: cluster_id - UUID from list_clusters

Server Selection: Use cluster's source field from Step 1:

• source: "ocm" → Call via openshift-ocm-managed
• source: "assisted-installer" → Call via openshift-self-managed

Expected Output: Cluster details (ID, version, status, network config, hosts/nodes)

Error Handling:

• Cluster not found → Verify cluster exists
• Wrong MCP instance → Try other instance
• Permission denied → User lacks access

Step 3: Get Diagnostics (Optional - Self-Managed Only)

NOTE: Only for OCP/SNO clusters. ROSA/ARO/OSD use cloud provider consoles for events and logs.

Execute when user requests events, troubleshoots errors, or needs installation logs.

3a. Get Cluster Events

MCP Tool: cluster_events (from openshift-self-managed) Parameters: cluster_id - UUID of self-managed cluster

Expected Output: Chronological events with timestamps, severity, messages

When to use:

• Diagnosing installation failures
• Understanding cluster state transitions
• Investigating validation errors

Error Handling:

• Cluster not found → Verify exists
• No events → Report no history yet
• Permission denied → User lacks access

3b. Get Cluster Logs

MCP Tool: cluster_logs_download_url (from openshift-self-managed) Parameters: cluster_id - UUID of self-managed cluster

Expected Output: Presigned download URL for logs bundle (installation, validation, host discovery, diagnostics)

When to use:

• Cluster status is "error"
• Events don't provide enough detail
• Deep troubleshooting needed

Error Handling:

• Cluster not found → Verify exists
• Logs unavailable → Too early in lifecycle
• URL generation fails → Cluster not ready

Dependencies

Required MCP Servers

• openshift-self-managed - Assisted Installer service for OCP/SNO
• openshift-ocm-managed - OCM service for ROSA/ARO/OSD

Required MCP Tools

• list_clusters (from both servers) - Lists clusters (auto-routes to correct API)
• cluster_info (from both servers) - Gets cluster details (auto-routes to correct API)
• cluster_events (from openshift-self-managed only) - Gets events for self-managed clusters
• cluster_logs_download_url (from openshift-self-managed only) - Gets log download URL

Related Skills

• /cluster-creator - Create new clusters
• Future: cluster-installer, cluster-deletion

Reference Documentation

• troubleshooting.md - Cluster status and error diagnosis
• PVC Capacity Planning - Consult when cluster storage details show high PVC usage or approaching capacity
• Database Connection Management - Consult when cluster workloads include PostgreSQL with high connection usage
• Documentation Index - Complete guide to all ocp-admin documentation (consult for topics not explicitly referenced above)

Example Usage

Example 1: List All Clusters

User: "List all my OpenShift clusters"

Output:

📊 Found 5 cluster(s): 3 ready ✅, 1 installing ⏳, 1 pending ⚠️

| Name | ID | Status | Type | Version | Provider | Region |
|------|----|--------|------|---------|----------|--------|
| prod-ocp | 762df996-acba-4a42-9fe9-edb0a8ec8bee | ⏳ installing | OCP | 4.21.0 | Baremetal | - |
| dev-ocp | a1b2c3d4-e5f6-4789-a0b1-c2d3e4f5a6b7 | ✅ ready | OCP | 4.20.5 | vSphere | - |
| rosa-prod | 2o2gevtk4bohdu41ff4jps0dl8rrshb6 | ✅ ready | ROSA | 4.21.0 | AWS | us-east-1 |
| aro-dev | 20ekbvg1jkaqssc47mmc0irlvhf59c0p | ✅ ready | ARO | 4.20.0 | Azure | - |
| edge-01 | 8e5d3e45-77c6-440b-9cfa-9f88187535c6 | ⚠️ pending-for-input | SNO | 4.21.0 | Self-managed | - |

Example 2: List Single Cluster

User: "Show me my edge cluster"

Output:

📊 Found 1 cluster

**Cluster: edge-01**
- ID: 8e5d3e45-77c6-440b-9cfa-9f88187535c6
- Status: ⚠️ pending-for-input
- Type: SNO
- Version: 4.21.0
- Provider: Self-managed
- Region: -

Example 3: Filter by Type

User: "List only ROSA clusters"

Output:

📊 Found 2 ROSA cluster(s): 2 ready ✅

| Name | ID | Status | Type | Version | Provider | Region |
|------|----|--------|------|---------|----------|--------|
| rosa-prod | 2o2gevtk4bohdu41ff4jps0dl8rrshb6 | ✅ ready | ROSA | 4.21.0 | AWS | us-east-1 |
| rosa-dev | 2nm4er0dk4a8lcs23foq6ug50v4onsvs | ✅ ready | ROSA | 4.20.8 | AWS | us-west-2 |

Example 4: Get Cluster Details

User: "Show me details for prod-ocp"

Output:

**Cluster Details: prod-ocp**
- ID: 762df996-acba-4a42-9fe9-edb0a8ec8bee
- Version: 4.21.0
- Status: Installing (45% complete)
- Platform: Baremetal
- Hosts: 3/3 ready
- Network: API VIP configured, Ingress VIP configured