opm-troubleshooting

OPM Troubleshooting Plugin

Claude Code plugin for OLM catalog bundle inspection and operator troubleshooting with pure Go implementation.

Overview

The opm-troubleshooting plugin provides AI-powered commands for diagnosing OLM (Operator Lifecycle Manager) operator issues in OpenShift environments. It replaces traditional shell toolchains (opm render + jq + skopeo) with a pure Go implementation that integrates seamlessly with Claude Code workflows.

Key Features:

• 🔍 Bundle Inspection: Resolve channel-head bundles and extract commit metadata
• 📊 Batch Validation: Validate 100+ operators efficiently with single catalog render
• 🔧 Channel Resolution: Discover available channels and upgrade paths
• 🤖 AI Agents: Automated troubleshooting workflows with intelligent diagnosis
• 🚀 Pure Go: No external dependencies on opm, jq, or skopeo binaries

Architecture

flowchart LR
  subgraph cli [CLI]
    flags["--catalog --package --channel"]
    env_var["DOCKER_CONFIG env"]
  end

  subgraph internal_catalog [internal/catalog]
    render["action.Render"]
    resolve["ResolveChannelHead"]
  end

  subgraph internal_image [internal/image]
    inspect["remote.Image + ConfigFile"]
  end

  flags --> render
  env_var --> render
  env_var --> inspect
  render --> resolve
  resolve --> inspect
  inspect --> out["stdout: package/bundle/version/commit/url"]

Installation

Option 1: Download Pre-built Binaries

Pre-built binaries are available for multiple architectures from GitHub Actions artifacts and releases.

From GitHub Releases (Recommended)

Download the latest release for your platform:

# For Linux AMD64
curl -L -o catalog-bundle-inspect.tar.gz \
  https://github.com/midu16/opm-troubleshooting/releases/latest/download/catalog-bundle-inspect-linux-amd64.tar.gz

# For Linux ARM64
curl -L -o catalog-bundle-inspect.tar.gz \
  https://github.com/midu16/opm-troubleshooting/releases/latest/download/catalog-bundle-inspect-linux-arm64.tar.gz

# Extract and install
tar -xzf catalog-bundle-inspect.tar.gz
sudo mv catalog-bundle-inspect-linux-* /usr/local/bin/catalog-bundle-inspect
chmod +x /usr/local/bin/catalog-bundle-inspect

# Verify installation
catalog-bundle-inspect --help

Verify Checksums

# Download checksum file
curl -L -o catalog-bundle-inspect.tar.gz.sha256 \
  https://github.com/midu16/opm-troubleshooting/releases/latest/download/catalog-bundle-inspect-linux-amd64.tar.gz.sha256

# Verify
sha256sum -c catalog-bundle-inspect.tar.gz.sha256

Available Architectures

• linux-amd64 (x86_64)
• linux-arm64 (aarch64)
• linux-386 (x86 32-bit)

Option 2: Claude Code Plugin

Prerequisites

1. Claude Code CLI installed (v0.1.0+)
2. Network access to pull OCI images (catalog indexes and bundles)
3. Registry credentials (for private catalogs): Set DOCKER_CONFIG environment variable

Add Plugin Marketplace

# Add the ai-helpers marketplace (if not already added)
/plugin marketplace add midu16/opm-troubleshooting

# Install the opm-troubleshooting plugin
/plugin install opm-troubleshooting@opm-troubleshooting

Verify Installation

# List available commands
/plugin list

# Should show:
# - opm-troubleshooting:inspect-bundle
# - opm-troubleshooting:resolve-channel
# - opm-troubleshooting:batch-validate

Quick Start

Example 1: Inspect an Operator Bundle

/opm-troubleshooting:inspect-bundle \
  --catalog quay.io/prega/prega-operator-index:v4.22-latest \
  --package kubernetes-nmstate-operator \
  --channel stable

Output:

package: kubernetes-nmstate-operator
bundle:  registry.redhat.io/openshift4/kubernetes-nmstate-operator-bundle@sha256:abc123...
version: v4.22.0-202606071943
commit:  a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0
url:     https://github.com/nmstate/kubernetes-nmstate/commit/a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0

Example 2: List Available Channels

/opm-troubleshooting:resolve-channel \
  --catalog registry.redhat.io/redhat/redhat-operator-index:v4.22 \
  --package odf-operator

Output:

package: odf-operator
defaultChannel: stable-4.22

Available channels:
- stable-4.21 (15 bundles)
- stable-4.22 (8 bundles)

Example 3: Batch Validate Operators

Create operators.txt:

odf-operator stable-4.22
kubernetes-nmstate-operator stable
cluster-logging stable-5.9

Run validation:

/opm-troubleshooting:batch-validate \
  --catalog registry.redhat.io/redhat/redhat-operator-index:v4.22 \
  --list operators.txt

Output:

OK     odf-operator                    stable-4.22    version=v4.22.5 commit=5d1e5bd5
PARTIAL kubernetes-nmstate-operator   stable         version=v4.22.0 commit="" url=""
OK     cluster-logging                 stable-5.9     version=v5.9.8 commit=def67890

Total: 2 OK, 1 PARTIAL, 0 FAIL

Commands

inspect-bundle