# OpenShift OVN-Kubernetes Benchmark MCP Server

A comprehensive benchmarking and performance monitoring solution for OpenShift clusters using OVN-Kubernetes networking, built with FastMCP and AI-powered analysis.

## Architecture Overview

## Topology

<img width="859" height="572" alt="ovnk-benchmark-mcp-architecture-topology" src="https://github.com/user-attachments/assets/f741b136-40d2-4a60-ba02-ca660c3abbaa" />

## Web UI

<img width="1726" height="951" alt="ovnk-benchmark-mcp-web-ui" src="https://github.com/user-attachments/assets/54aab83b-f65e-458d-aa3e-ea59d023cd62" />


## Features

### 🔧 Core Capabilities
- **Automated Authentication**: Discovers and authenticates with OpenShift/Kubernetes clusters
- **Multi-Source Monitoring**: Collects metrics from Prometheus, Kubernetes API, and cluster resources
- **AI-Powered Analysis**: Uses LangGraph and OpenAI for intelligent insights and recommendations
- **Comprehensive Reporting**: Generates Excel and PDF reports with visualizations
- **Historical Tracking**: Stores performance data in DuckDB for trend analysis

### 📊 Monitored Components
- **Kubernetes API Server**: Request latency, throughput, and error rates
- **Multus CNI**: Resource usage and pod networking performance
- **OVN-Kubernetes Pods**: Control plane and node performance
- **OVN Containers**: Database sizes, memory usage, and sync performance
- **OVS Components**: CPU and memory usage of OVS processes
- **General Cluster Info**: NetworkPolicies, AdminNetworkPolicies, EgressFirewalls

### 🤖 AI Features
- Automated performance trend analysis
- Intelligent alert correlation
- Proactive recommendations
- Risk assessment and health scoring
- Natural language insights

## Quick Start

### Prerequisites

- Python 3.9+
- OpenShift/Kubernetes cluster access
- KUBECONFIG file
- OpenAI API key (for AI features)

### Installation

1. **Clone and Setup**
   ```bash
   git clone <repository>
   cd ocp-benchmark-mcp
   chmod +x ovnk_benchmark_mcp_command.sh
   ./ovnk_benchmark_mcp_command.sh setup
   ```

2. **Test Configuration**
   ```bash
   ./ovnk_benchmark_mcp_command.sh -k ~/.kube/config test
   ```

### Usage

#### Start MCP Server
```bash
# Start server (runs on port 8000)
./ovnk_benchmark_mcp_command.sh -k ~/.kube/config server
```

#### Collect Performance Data
```bash
# Collect data for 10 minutes
./ovnk_benchmark_mcp_command.sh -k ~/.kube/config -d 10m collect
```

#### Generate Reports
```bash
# Generate report for last 7 days
./ovnk_benchmark_mcp_command.sh -o sk-your-openai-key -p 7 report
```

#### Full Workflow
```bash
# Collect data and generate report
./ovnk_benchmark_mcp_command.sh -k ~/.kube/config -o sk-your-openai-key full
```

## Project Structure

```
ocp-benchmark-mcp/
├── README.md                                    # This file
├── pyproject.toml                              # Python project configuration
├── ovnk_benchmark_mcp_server.py               # Main MCP server
├── ovnk_benchmark_mcp_agent_perfdata.py       # Data collection agent
├── ovnk_benchmark_mcp_agent_report.py         # Report generation agent
├── ovnk_benchmark_mcp_command.sh              # Startup script
├── ocauth/
│   └── ovnk_benchmark_auth.py                 # OpenShift authentication
├── tools/
│   ├── ovnk_benchmark_openshift_generalinfo.py # Cluster general info
│   ├── ovnk_benchmark_prometheus_basequery.py  # Base Prometheus queries
│   ├── ovnk_benchmark_prometheus_kubeapi.py    # API server metrics
│   ├── ovnk_benchmark_prometheus_multus.py     # Multus CNI metrics
│   ├── ovnk_benchmark_prometheus_ovnk_pods.py  # OVN-K pod metrics
│   ├── ovnk_benchmark_prometheus_ovnk_containers.py # OVN container metrics
│   └── ovnk_benchmark_prometheus_ovnk_sync.py  # OVN sync metrics
├── config/
│   ├── ovnk_benchmark_config.py               # Configuration management
│   └── metrics-base.yml                       # Prometheus metrics definitions
├── analysis/
│   └── ovnk_benchmark_performance_analysis.py # Performance analysis
├── elt/
│   └── ovnk_benchmark_elt_duckdb.py      # Data processing
├── storage/
│   └── ovnk_benchmark_prometheus_ovnk.py      # DuckDB storage
└── exports/                                    # Generated reports
```

## Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `KUBECONFIG` | Path to kubeconfig file | `~/.kube/config` |
| `OPENAI_API_KEY` | OpenAI API key for AI features | Required for reports |
| `MCP_SERVER_URL` | MCP server URL | `http://localhost:8000` |
| `COLLECTION_DURATION` | Metrics collection duration | `5m` |
| `REPORT_PERIOD_DAYS` | Report period in days | `7` |
| `DATABASE_PATH` | DuckDB database path | `storage/ovnk_benchmark.db` |
| `REPORT_OUTPUT_DIR` | Report output directory | `exports` |
export OVNK_PROMETHEUS_USE_ROUTE=true          # Use OpenShift routes (default)
export OVNK_PROMETHEUS_NAMESPACE=openshift-monitoring
export OVNK_PROMETHEUS_SA=prometheus-k8s
export KUBECONFIG=/path/to/kubeconfig

### Metrics Configuration

The `config/metrics-base.yml` file defines all Prometheus queries organized by category:

- **General Information**: Pod and namespace status
- **API Server**: Request latency and error rates
- **Multus**: CNI resource usage
- **OVN Control Plane/Node**: CPU and memory metrics
- **OVN Containers**: Database and controller metrics
- **OVS Containers**: OVS daemon metrics
- **OVN Sync**: Synchronization duration metrics

## API Reference

### MCP Tools

The server exposes the following MCP tools:

#### `get_openshift_general_info`
Get general cluster information including NetworkPolicy, AdminNetworkPolicy, and EgressFirewall counts.

**Parameters:**
- `namespace` (optional): Specific namespace to query

**Response:**
```json
{
  "timestamp": "2024-01-01T00:00:00Z",
  "summary": {
    "total_networkpolicies": 10,
    "total_adminnetworkpolicies": 2,
    "total_egressfirewalls": 5,
    "total_namespaces": 25,
    "total_nodes": 6
  }
}
```

#### `query_kube_api_metrics`
Query Kubernetes API server performance metrics.

**Parameters:**
- `duration` (optional): Query duration (default: "5m")
- `start_time` (optional): Start time in ISO format
- `end_time` (optional): End time in ISO format

#### `query_multus_metrics`
Query Multus CNI performance metrics.

#### `query_ovnk_pods_metrics`
Query OVN-Kubernetes pod performance metrics.

#### `query_ovnk_containers_metrics`
Query OVN-Kubernetes container metrics.

#### `query_ovnk_sync_metrics`
Query OVN-Kubernetes synchronization metrics.

#### `store_performance_data`
Store performance data in DuckDB.

#### `get_performance_history`
Retrieve historical performance data.

## AI Agents

### Performance Data Collection Agent

Uses LangGraph to orchestrate data collection:

1. **Initialize**: Setup collection parameters
2. **Collect General Info**: Gather cluster information
3. **Collect Metrics**: Query each component category
4. **Store Data**: Save to DuckDB storage
5. **Finalize**: Generate collection summary

### Report Generation Agent

Uses LangGraph with AI analysis:

1. **Fetch Historical Data**: Retrieve performance history
2. **Analyze Performance**: Calculate trends and statistics
3. **Generate Insights**: Use AI for recommendations
4. **Create Reports**: Generate Excel and PDF reports
5. **Finalize**: Output summary and files

## Storage Schema

### DuckDB Tables

- **`metrics`**: Individual metric data points
- **`metric_summaries`**: Category performance summaries
- **`performance_snapshots`**: Complete performance snapshots
- **`benchmark_runs`**: Benchmark execution records
- **`alerts_history`**: Historical alert data

## Report Types

### Excel Reports

- **Executive Summary**: Key performance indicators
- **Historical Trends**: Time-series performance data
- **Category Analysis**: Component-specific metrics
- **Recommendations**: AI-generated insights
- **Raw Data**: Complete dataset

### PDF Reports

- **Executive Summary**: High-level performance overview
- **Key Metrics**: Performance indicator tables
- **Category Analysis**: Component performance breakdown
- **Recommendations**: Prioritized action items

## Troubleshooting

### Common Issues

#### Authentication Problems
```bash
# Test cluster connectivity
kubectl cluster-info

# Verify kubeconfig
export KUBECONFIG=/path/to/config
./ovnk_benchmark_mcp_command.sh test
```

#### Prometheus Discovery
```bash
# Check Prometheus pods
kubectl get pods -n openshift-monitoring | grep prometheus

# Verify service accounts
kubectl get sa -n openshift-monitoring
```

#### MCP Server Issues
```bash
# Check server logs
tail -f logs/mcp_server_*.log

# Test server connectivity
curl http://localhost:8000/health
```

### Debug Mode

Enable debug logging:
```bash
export LOG_LEVEL=DEBUG
export OVNK_LOG_LEVEL=DEBUG
./ovnk_benchmark_mcp_command.sh server
```

## Contributing

1. **Fork the repository**
2. **Create a feature branch**
3. **Add tests for new functionality**
4. **Submit a pull request**

### Development Setup

```bash
# Install development dependencies
pip install -e .[dev]

# Run tests
pytest

# Format code
black .

# Type checking
mypy .
```

## License

MIT License - see LICENSE file for details.

## Support

For issues and questions:

1. **Check the troubleshooting section**
2. **Review logs in the `logs/` directory**
3. **Open an issue with detailed logs and configuration**

## Roadmap

- [ ] Kubernetes native deployment (Helm charts)
- [ ] Grafana dashboard integration
- [ ] Custom alert rule definitions
- [ ] Multi-cluster support
- [ ] Real-time streaming metrics
- [ ] Advanced ML-based anomaly detection
- [ ] Integration with CI/CD pipelines

---

**Note**: This tool is designed for OpenShift clusters with OVN-Kubernetes networking. Some features may not be available on other Kubernetes distributions.