DeathStarOps 🌑

DeathStarOps is a real-time Kubernetes cluster monitoring dashboard with an AI-powered chatbot assistant that helps DevOps engineers manage, debug, and understand their cluster health without leaving the UI.

The Problem

Kubernetes debugging is complex - engineers constantly switch between kubectl commands, logs, dashboards, and documentation. Getting a quick answer like "why is this pod failing?" requires multiple steps and tribal knowledge.

The Solution

An intelligent assistant that:

• Queries cluster data in natural language - "How are my pods doing?" → fetches real cluster stats
• Provides contextual help - understands current time and page for relevant responses
• Generates kubectl commands - suggests exact commands for operations
• Analyzes pod issues - identifies CrashLoopBackOff, resource limits, etc.

---

Tech Stack & Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         FRONTEND                                │
│  React + TypeScript + Vite + TailwindCSS + shadcn/ui            │
│                                                                 │
│  ┌─────────────────┐    ┌──────────────────────────────────┐    │
│  │   Dashboard UI  │    │      AI Chatbot (Tambo)          │    │
│  │  - Fleet Status │    │  - useTamboThread                │    │
│  │  - Pod Cards    │    │  - useTamboThreadInput           │    │
│  │  - Namespace    │    │  - TamboProvider with Tools      │    │
│  └─────────────────┘    └──────────────────────────────────┘    │
└──────────────────────────────┬──────────────────────────────────┘
                               │ /api proxy
┌──────────────────────────────▼──────────────────────────────────┐
│                         BACKEND                                 │
│              Node.js + Express + kubectl                        │
│                                                                 │
│  /api/cluster-stats  →  kubectl get nodes, pods                 │
│  /api/pods           →  kubectl get pods -A -o json             │
│  /api/pods/:ns/:name →  kubectl describe pod + logs             │
└──────────────────────────────┬──────────────────────────────────┘
                               │
┌──────────────────────────────▼──────────────────────────────────┐
│                       KUBERNETES CLUSTER                        │
│                          (Minikube)                             │
│                                                                 │
│          ArgoCD, Kyverno, Redis, and application workloads      │
└─────────────────────────────────────────────────────────────────┘

Layer	Technologies
Frontend	React 18, TypeScript, Vite, TailwindCSS, shadcn/ui, Zustand
AI Integration	@tambo-ai/react, @tambo-ai/typescript-sdk
Backend	Node.js, Express, child_process (kubectl)
Infra	Kubernetes (Minikube), ArgoCD, Kyverno

---

How Tambo Was Used

1. TamboProvider Setup

Wrapped the app with TamboProvider to enable AI capabilities throughout:

// tambo-wrapper.tsx
<TamboProvider
    apiKey={tamboKey}
    components={tamboComponents}
    tools={tamboTools}
    contextHelpers={{
        userTime: currentTimeContextHelper,
        userPage: currentPageContextHelper,
    }}
>
    {children}
</TamboProvider>

2. AI Tools for Kubernetes Operations

Created 5 tools that Tambo's AI can execute:

Tool	Purpose
getClusterStats	Fetch node/pod counts, capacity, health
getPodInfo	Get details about a specific pod
listPods	List/filter pods by namespace or status
getNamespaces	List all cluster namespaces
suggestKubectlCommand	Generate kubectl commands

// Example tool definition
const getClusterStatsTool: TamboTool = {
    name: 'getClusterStats',
    description: 'Fetches cluster health statistics...',
    tool: async () => {
        const response = await fetch('/api/cluster-stats');
        const stats = await response.json();
        return { nodes: stats.nodes, runningPods: stats.pods.running, ... };
    },
    inputSchema: z.object({}),
    outputSchema: z.object({ ... }),
};

3. Context Helpers

Added context helpers so the AI knows the current time and page:

const currentTimeContextHelper = () => new Date().toLocaleString();
const currentPageContextHelper = () => window.location.pathname;

4. Chat Interface with Hooks

Used Tambo's React hooks for the chat UI:

const { thread } = useTamboThread();
const { value, setValue, submit, isPending, isError, error } = useTamboThreadInput();

5. Error Handling

Added proper error display when API calls fail:

{isError && error && (
    <div className="error-box">
        <AlertTriangle /> Error: {error.message}
    </div>
)}

Features

• 🚀 Real-time Pod Monitoring - View all pods with live status updates
• 🤖 AI-Powered Analysis - Get intelligent error analysis and configuration explanations
• 🎨 Light/Dark Themes - Stormtrooper White & Star Destroyer Bridge modes
• 📊 Cluster Health Overview - See node count, capacity, and alerts at a glance
• 🏷️ Smart Pod Grouping - Pods organized by category (Applications, System, Monitoring, etc.)
• ⚡ Pod Actions - Restart, delete, and scale pods directly from the UI

---

Prerequisites

Before you begin, ensure you have:

• Node.js (v18 or higher) - Download
• npm (comes with Node.js)
• kubectl configured with cluster access - Install kubectl
• Tambo AI API Key - Get your key

Verify Prerequisites

# Check Node.js version
node --version
# Should show v18.x.x or higher

# Check npm
npm --version

# Check kubectl is configured
kubectl cluster-info
# Should show cluster info if connected

---

Quick Start

1. Clone the Repository

git clone https://github.com/ayushsgit/DeathStarOps.git
cd DeathStarOps

2. Install Dependencies

# Install server dependencies
cd server
npm install

# Install client dependencies
cd ../client
npm install

3. Configure Environment Variables

Create a .env file in the server directory:

cd server
touch .env

Add your Tambo AI API key:

TAMBO_API_KEY=your_tambo_api_key_here

4. Start the Application

You need two terminal windows - one for the server and one for the client.

Terminal 1 - Start the Backend Server:

cd server
npm run dev

The server will start on http://localhost:3001

Terminal 2 - Start the Frontend:

cd client
npm run dev

The client will start on http://localhost:5173

5. Open the Dashboard

Open your browser and go to: http://localhost:5173

You'll be prompted to enter your Tambo AI API key on first load.

---

Project Structure

Opus-DeathStarOps/
├── client/                 # React Frontend
│   ├── src/
│   │   ├── components/     # React components
│   │   ├── lib/            # Utilities & API client
│   │   ├── store/          # Zustand state stores
│   │   └── App.tsx         # Main application
│   ├── package.json
│   └── vite.config.ts      # Vite configuration
│
├── server/                 # Node.js Backend
│   ├── server.js           # Express server
│   └── package.json
│
└── README.md               # This file

---

Available Scripts

Client (Frontend)

cd client

# Start development server
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

# Type check
npm run typecheck

Server (Backend)

cd server

# Start development server (with hot reload)
npm run dev

# Start production server
npm start

---

Building for Production

1. Build the Client

cd client
npm run build

This creates a dist/ folder with the production-ready frontend.

2. Serve the Application

For production, you can serve the built client through the Express server or use a static file server like nginx.

---

Troubleshooting

"Cannot connect to cluster"

• Ensure kubectl is properly configured
• Run kubectl cluster-info to verify connection
• Check if your kubeconfig is set: echo $KUBECONFIG

"401 Unauthorized" errors

• Make sure you've entered a valid Tambo AI API key
• Clear browser localStorage and re-enter the API key

"Port already in use"

• Kill the process using the port:

  # For port 3001 (server)
  lsof -ti:3001 | xargs kill -9
  
  # For port 5173 (client)
  lsof -ti:5173 | xargs kill -9

"Module not found" errors

• Delete node_modules and reinstall:

  rm -rf node_modules package-lock.json
  npm install

---

Learning & Growth

Challenges Faced

1. Context provider crashes - Tambo hooks crash when called outside TamboProvider. Fixed by handling the "skip auth" flow gracefully.
2. API endpoint mismatch - Tools were calling wrong endpoints. Fixed by aligning frontend tools with backend routes.
3. Proxy configuration - Vite wasn't forwarding API calls to the backend. Added proxy config.

Key Takeaways

• Tambo's tool system is powerful - The AI automatically decides when to call tools based on user intent.
• Error handling is critical - Always handle errors gracefully in both hooks and tool execution.
• Context helpers add value - Small additions like time/page context make the AI more helpful.

Future Improvements

• Add useTamboSuggestions for quick action buttons
• Add useTamboStreamStatus for better loading indicators
• Add voice input with useTamboVoice

AI Usage

Google Gemini, Claude Opus were used for boilerplate template and fixing backend refreshing bugs.

---

License

MIT License - Feel free to use this for your own projects!

---

May the Force be with your clusters. 🌟