M-PACT

Must-gather Parser, Analyzer & Comparator Tool

M-PACT is a Python-based tool designed to analyze and compare OpenShift must-gather archives. It extracts, parses, and presents critical cluster information in a structured and readable format, making it easier to troubleshoot OpenShift clusters and compare configurations across different environments.

Features

• 🔍 Comprehensive Analysis: Extracts and analyzes key cluster information including:

  • Cluster version and update status
  • Network configuration (SDN/OVN)
  • Node information and resource allocation
  • Machine config pools
  • Infrastructure configuration
  • OLM operators and ClusterServiceVersions
  • Persistent volumes and volume attachments
  • Metrics data
  • Monitoring stack information

• 📊 Structured Output: Presents data in formatted tables for easy reading

• 🔄 Comparison Mode: Compare two must-gather archives side-by-side to identify differences

• ⚡ Performance Optimized: Optimized file filtering to process large archives efficiently

• 📦 Multiple Format Support: Works with .tar.gz, .tgz, .zip archives, or uncompressed directories

• 🎯 Flexible Usage: Interactive mode or command-line mode for automation

Requirements

• Python 3.8 or higher
• Required packages (see requirements.txt):
  • pandas >= 2.0.0
  • tabulate >= 0.9.0
  • PyYAML >= 6.0.0

Installation

Using a Virtual Environment (Recommended)

1. Clone the repository:

   git clone https://github.com/joseorpa/M-PACT.git
   cd M-PACT

2. Create a virtual environment:

   python3 -m venv venv

3. Activate the virtual environment:

   On Linux/macOS:

   source venv/bin/activate

   On Windows:

   venv\Scripts\activate

4. Install dependencies:

   pip install -r requirements.txt

5. Verify installation:

   python3 m-pact.py --help

Direct Installation (Alternative)

If you prefer not to use a virtual environment:

pip install -r requirements.txt

Usage

Interactive Mode

Simply run the script without arguments to enter interactive mode:

python3 m-pact.py

The tool will prompt you for:

• Path to the must-gather archive or directory
• Configuration options

Command-Line Mode

Analyze a Single Must-Gather Archive

Analyze a compressed archive:

python3 m-pact.py -f /path/to/must-gather.tar.gz

Analyze a ZIP archive:

python3 m-pact.py -f /path/to/must-gather.zip

Analyze an uncompressed directory:

python3 m-pact.py -f /path/to/must-gather-directory/

Compare Two Must-Gather Archives

Compare two compressed archives:

python3 m-pact.py -c must-gather-before.tar.gz must-gather-after.tar.gz

Compare two directories:

python3 m-pact.py -c must-gather-dir1/ must-gather-dir2/

Mix archive and directory:

python3 m-pact.py -c must-gather.tar.gz must-gather-dir/

Command-Line Options

Option	Description
-f, --file <path>	Path to must-gather archive or directory to analyze
-c, --compare <source1> <source2>	Compare two must-gather sources
--no-optimizations	Disable performance optimizations (process all files)
-h, --help	Show help message and exit

What Does M-PACT Analyze?

M-PACT extracts and presents the following information from must-gather archives:

1. Cluster Version

• OpenShift version
• Kubernetes version
• Update channel and available updates
• Cluster operators status
• Cluster conditions

2. Network Configuration

• Network type (OpenShift SDN or OVN-Kubernetes)
• Cluster network CIDR
• Service network CIDR
• Host prefix
• Network MTU
• Plugin-specific configuration

3. Node Information

• Node count and status
• CPU and memory allocations
• Instance types
• Operating system details
• Kernel versions
• Reserved resources percentage

4. Machine Config Pools

• Master and worker pool status
• Configuration versions
• Machine counts
• Update status

5. Infrastructure

• Platform type (AWS, Azure, GCP, bare metal, etc.)
• Platform-specific configuration
• API server URLs

6. OLM Operators

• Installed operators
• ClusterServiceVersions (CSVs)
• Operator versions and phases
• OLM configuration
• Operator groups

7. Storage

• Persistent Volumes (PVs)
• Volume Attachments
• Storage classes
• Volume status and capacity

8. Monitoring & Metrics

• Prometheus configuration
• Alertmanager status
• etcd health information
• Key metrics data

Example Output

When analyzing a must-gather archive, you'll see output like:

OpenShift Archive Analyzer
==================================================
Starting analysis of /path/to/must-gather.tar.gz
🔍 Archive type detection: Detected must-gather archive (found 5 must-gather indicators)
⚡ Performance optimizations enabled for must-gather archive
Found 15234 files in tar.gz archive
📊 Pre-filtering: 487 candidates from 15,234 files (3.2% efficiency)

==================================================
CLUSTER VERSION
==================================================
OpenShift Version: 4.14.8
Kubernetes Version: v1.27.8+4fab27b
...

==================================================
NODES SUMMARY
==================================================
┌─────────────┬────────────┬───────────────┬───────────────┬─────────┐
│ Node Name   │ CPU Alloc  │ Memory Alloc  │ Instance Type │ Status  │
├─────────────┼────────────┼───────────────┼───────────────┼─────────┤
│ master-0    │ 8 cores    │ 32Gi          │ m5.2xlarge    │ Ready   │
│ worker-0    │ 16 cores   │ 64Gi          │ m5.4xlarge    │ Ready   │
└─────────────┴────────────┴───────────────┴───────────────┴─────────┘
...

Performance Tips

• Use optimizations (default): The tool filters files to focus on relevant data
• Disable optimizations only when needed: Use --no-optimizations if you need to examine all files
• For large archives: The optimization can reduce processing time from minutes to seconds

Comparison Mode

When comparing two must-gather archives, M-PACT will:

• Analyze both archives independently
• Identify differences in:
  • Cluster versions
  • Node configurations
  • Operator installations
  • Network settings
  • And more...

This is particularly useful for:

• Before/after upgrade comparisons
• Troubleshooting configuration drift
• Validating cluster changes
• Comparing production vs. staging environments

Troubleshooting

ImportError: Missing Dependencies

If you see import errors:

pip install -r requirements.txt

Permission Denied

Make sure the script is executable:

chmod +x m-pact.py

Archive Not Recognized

Ensure your must-gather archive contains standard OpenShift must-gather directory structures. The tool looks for:

• cluster-scoped-resources/
• namespaces/
• monitoring/
• Other must-gather specific directories

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

See the LICENSE file for details.

---

Note: This tool is designed specifically for OpenShift must-gather archives. For best results, use must-gather archives generated with:

oc adm must-gather