KubeStack-AI

AI-Powered Unified Middleware Management for Kubernetes & Beyond

中文文档 • Architecture • Contributing • Plugin Development

---

🚀 Mission Statement

KubeStack-AI is a revolutionary, AI-powered command-line assistant that transforms how you diagnose, manage, and optimize your entire middleware stack running on Kubernetes and bare-metal environments. By combining the power of Large Language Models with deep middleware expertise, KubeStack-AI provides intelligent, natural language-driven operations for complex cloud-native infrastructures.

🎯 Why KubeStack-AI?

The Challenge

Modern cloud-native environments involve dozens of middleware components (Redis, Kafka, PostgreSQL, MinIO, ElasticSearch, etc.), each with unique operational complexities. Traditional approaches require:

• Fragmented Tools: Different CLI tools for each middleware
• Deep Expertise: Extensive knowledge of each system's internals
• Manual Correlation: Connecting symptoms across multiple systems
• Time-Consuming Diagnosis: Hours spent troubleshooting complex issues

Our Solution

KubeStack-AI provides a unified, AI-driven interface that:

✅ Speaks Your Language: Natural language queries instead of complex commands
✅ Thinks Holistically: Cross-middleware correlation and root cause analysis
✅ Acts Intelligently: AI-powered diagnosis with actionable recommendations
✅ Extends Seamlessly: Plugin architecture for any middleware
✅ Operates Safely: Interactive confirmation for critical operations

⭐ Key Features

🔍 Intelligent Diagnosis

• Multi-Layer Analysis: System, Kubernetes, and middleware-specific checks
• AI-Powered RCA: Root cause analysis across complex distributed systems
• Natural Language Queries: Ask questions in plain English

🛠️ Universal Middleware Support

• Database Systems: MySQL, PostgreSQL, MongoDB, Redis, ClickHouse
• Message Queues: Kafka, RabbitMQ, Pulsar
• Search & Analytics: ElasticSearch, OpenSearch
• Storage: MinIO, Ceph
• Monitoring: Prometheus, Grafana
• Service Discovery: etcd, Consul

🧩 Plugin Architecture

• Extensible Design: Add support for any middleware through plugins
• Community Driven: Open plugin ecosystem
• Hot-swappable: Install, update, and remove plugins without downtime

🤖 AI-Enhanced Operations

• Smart Recommendations: Context-aware optimization suggestions
• Automated Fixes: One-click resolution for common issues
• Knowledge Integration: Built-in best practices and troubleshooting guides

🚀 Getting Started

Installation

Option 1: Go Install

go install github.com/turtacn/kubestack-ai/cmd/ksa@latest

Option 2: Homebrew (macOS/Linux)

brew tap turtacn/kubestack-ai
brew install kubestack-ai

Option 3: Download Binary

Visit our releases page to download pre-built binaries.

Quick Start

# Initialize KubeStack-AI
ksa init

# Diagnose all middleware in current namespace
ksa diagnose --all

# Ask natural language questions
ksa ask "Why is my Redis cluster slow?"

# Get specific middleware status
ksa status redis --namespace production

# List available plugins
ksa plugin list

# Install a new plugin
ksa plugin install mongodb

Basic Usage Examples

Example 1: Comprehensive System Health Check

$ ksa diagnose --middleware redis,mysql,kafka
🔍 Analyzing Redis cluster...
✅ Redis: Healthy (3/3 nodes up, memory usage: 45%)

🔍 Analyzing MySQL primary-replica...
⚠️  MySQL: Warning detected
   • Replica lag: 2.3s (threshold: 1s)
   • Slow queries: 23 in last hour

🔍 Analyzing Kafka cluster...
❌ Kafka: Critical issues found
   • Topic 'orders': 50K messages backed up
   • Consumer group 'payment-service': 5min lag

💡 AI Recommendations:
   1. MySQL: Consider tuning innodb_buffer_pool_size
   2. Kafka: Scale consumer group or check processing logic

Example 2: Natural Language Troubleshooting

$ ksa ask "My application can't connect to the database"
🤔 Analyzing connection issues...

🔍 Discovered Issues:
   • PostgreSQL max_connections (100) reached
   • Connection pool exhaustion in app pods
   • Network policy blocking traffic on port 5432

🛠️  Suggested Actions:
   1. Increase max_connections: `ksa exec postgres --set max_connections=200`
   2. Scale app replicas: `ksa scale app --replicas 5`
   3. Review network policies: `ksa network analyze postgres`

Execute fixes? [y/N]: 

Example 3: Plugin Management

$ ksa plugin install clickhouse
📦 Installing ClickHouse plugin v1.2.0...
✅ Plugin installed successfully

$ ksa diagnose clickhouse --cluster analytics
🔍 ClickHouse Cluster Analysis:
   • Merge queue: 145 items (high)
   • Query latency P95: 2.3s
   • Disk usage: 78% on shard-2

💡 Recommendations:
   • Consider adding more background merge threads
   • Archive old partitions in 'events' table

📖 Documentation

• Architecture Overview - Technical deep-dive into system design
• Plugin Development Guide - Build your own middleware plugins
• Configuration Reference - Complete config options
• Troubleshooting Guide - Common issues and solutions
• API Reference - REST API and SDK documentation

🏗️ Codebase Structure

A brief overview of the key directories in the KubeStack-AI repository:

• /cmd: Main application entry points. The ksa CLI application lives here.
• /internal: All of the core application logic. As this is an internal package, it is not meant to be imported by external applications.
  • /cli: Defines the command-line interface using Cobra, including command definitions, flag parsing, and UI formatters.
  • /core: The heart of the application. It contains the central orchestrator and the primary interfaces for diagnosis, execution, and plugins.
  • /llm: Abstractions and clients for interacting with Large Language Models (LLMs) and the Retrieval-Augmented Generation (RAG) pipeline.
  • /knowledge: Components for the knowledge base, including storage, crawling, and search functionalities.
  • /plugins: The plugin management system and all built-in middleware plugins (e.g., Redis, Kafka).
• /pkg: Shared utility packages that could theoretically be used by external applications.
• /deployments: Kubernetes manifests, Dockerfiles, and other deployment-related artifacts.
• /docs: Project documentation, including architecture and contribution guides.
• /scripts: Helper scripts for development tasks like building, testing, and linting.
• /web: Contains frontend assets for a potential web-based UI.

🤝 Contributing

We welcome contributions from the community! KubeStack-AI is built by middleware experts for middleware experts.

How to Contribute

1. 🐛 Report Issues: Found a bug? Open an issue
2. 💡 Feature Requests: Have ideas? Start a discussion
3. 🔧 Code Contributions: Fork, develop, and submit PRs
4. 📝 Documentation: Help improve our docs
5. 🧩 Plugin Development: Build plugins for new middleware

Development Setup

git clone https://github.com/turtacn/kubestack-ai.git
cd kubestack-ai
make dev-setup
make test
make build

See CONTRIBUTING.md for detailed guidelines.

🏆 Community & Support

• 💬 Discussions: GitHub Discussions
• 🐛 Issues: GitHub Issues
• 📧 Email: kubestack-ai@turtacn.com
• 🐦 Twitter: @KubeStackAI

📜 License

KubeStack-AI is licensed under the Apache License 2.0. See LICENSE file for details.

🌟 Star History

---

Built with ❤️ by the KubeStack-AI community