karpenter-optimizer

Karpenter Optimizer

License Go Report Card CI Release

💰 Cost optimization tool for Karpenter NodePools. Analyzes Kubernetes cluster usage and provides AI-powered recommendations to reduce AWS EC2 costs while maintaining performance.

Karpenter Optimizer helps you optimize your Karpenter NodePool configurations by analyzing actual cluster usage and providing intelligent, cost-effective instance type recommendations. Get visual before/after comparisons showing cost and resource savings.

✨ Features

📸 Screenshots

Cluster Overview

Cluster Overview View cluster-wide statistics and generate recommendations

Cost Savings Analysis

Potential Savings See potential cost savings across your entire cluster

NodePool Recommendations

NodePool Recommendation Detailed NodePool recommendations with before/after comparisons

AI-Powered Explanations

AI Explanation Get intelligent explanations for each recommendation

Node Usage Visualization

Node Usage Real-time visualization of CPU and memory usage per node

Node Disruption Tracking

Node Disruptions Monitor Karpenter node disruptions and identify blocked deletions

Settings & Configuration

Settings Configure Kubernetes, Ollama, and AWS Pricing API settings

Architecture

Architecture Diagram

Karpenter Optimizer follows a modern microservices architecture:

For detailed architecture documentation, see docs/architecture.md.

🗺️ Roadmap

We’re actively working on improving Karpenter Optimizer. Here’s what’s coming next:

Community-Driven

We welcome community input! If you have ideas or feature requests, please:

🚀 Quick Start

Prerequisites

Quick Install

helm repo add karpenter-optimizer https://kaskol10.github.io/karpenter-optimizer
helm repo update
helm install karpenter-optimizer karpenter-optimizer/karpenter-optimizer \
  --namespace karpenter-optimizer \
  --create-namespace

See the Helm chart documentation for detailed configuration options.

Using Docker

docker run -d \
  --name karpenter-optimizer \
  -p 8080:8080 \
  -v ~/.kube/config:/root/.kube/config:ro \
  ghcr.io/kaskol10/karpenter-optimizer:latest

Local Development

Backend:

# Install dependencies
go mod download

# Run the API server
go run ./cmd/api

Frontend:

cd frontend
npm install
npm start

The API will be available at http://localhost:8080 and the frontend at http://localhost:3000

Environment Variables:

📖 Documentation

Example Workload JSON

[
  {
    "name": "web-app",
    "namespace": "default",
    "cpu": "500m",
    "memory": "512Mi",
    "gpu": 0,
    "labels": {}
  },
  {
    "name": "ml-training",
    "namespace": "ml",
    "cpu": "4",
    "memory": "16Gi",
    "gpu": 1,
    "labels": {
      "karpenter.sh/capacity-type": "on-demand"
    }
  }
]

API Endpoints

Interactive API Documentation

Swagger UI: Access interactive API documentation at /swagger/index.html.

Local Development:

# Start the API server
go run ./cmd/api

# Access Swagger UI at:
# http://localhost:8080/api/swagger/index.html

Via Ingress (Production): When deployed with ingress enabled:

The ingress routes:

Dynamic Host Detection: Swagger automatically detects the request host and scheme (http/https) from ingress headers (X-Forwarded-Host, X-Forwarded-Proto), so API calls from Swagger UI will work correctly whether accessed directly or through ingress.

Generate Swagger Documentation

# Generate Swagger docs (requires swag CLI: go install github.com/swaggo/swag/cmd/swag@latest)
make swagger

Core Endpoints

For complete API documentation with request/response schemas, see the Swagger UI or generate the docs with make swagger.

Recommendation Output

Each recommendation includes:

Visual Comparison Features

The frontend provides comprehensive before/after comparisons:

Kubernetes Native Approach

Karpenter Optimizer uses the Kubernetes API directly to analyze your cluster:

  1. Node Usage Calculation: Calculates CPU and memory usage from scheduled pods
  2. Real-time Data: Uses current cluster state - no external metrics required
  3. Accurate Recommendations: Bases recommendations on actual resource allocations and node capacity

How It Works

Kubernetes Integration

NodePool Analysis

The tool fetches existing Karpenter NodePool configurations:

Development

Project Structure

.
├── cmd/
│   ├── api/            # Backend API server
│   │   └── main.go
│   └── cli/            # CLI tool
│       └── main.go
├── internal/
│   ├── api/            # HTTP handlers
│   ├── config/         # Configuration
│   ├── kubernetes/     # Kubernetes client
│   └── recommender/    # Recommendation logic
├── frontend/           # React frontend
│   ├── src/
│   │   ├── components/
│   │   │   ├── ComparisonView.js
│   │   │   ├── RecommendationCard.js
│   │   │   ├── WorkloadForm.js
│   │   │   └── WorkloadSelector.js
│   │   └── App.js
│   └── package.json
├── examples/           # Example files
│   └── workloads.json
└── go.mod

Building

# Build backend
go build -o bin/karpenter-optimizer-api ./cmd/api

# Build CLI
go build -o bin/karpenter-optimizer ./cmd/cli

# Build frontend
cd frontend
npm run build

Docker Deployment

# Build and run with docker-compose
docker-compose up --build

# Or build individually
docker build -t karpenter-optimizer-api .
docker build -t karpenter-optimizer-frontend ./frontend

Usage Examples

Example 1: Analyze Workloads from Cluster

  1. Start the backend with Kubernetes access: 
    KUBECONFIG=~/.kube/config go run ./cmd/api

  2. Open the frontend at http://localhost:3000

  3. Select a namespace from the dropdown

  4. Check workloads to add them

  5. Click “Analyze Workloads” to get recommendations

Example 2: Analyze Cluster Usage

  1. Start backend with Kubernetes access: 
    KUBECONFIG=~/.kube/config go run ./cmd/api

  2. The recommendations automatically analyze actual pod resource requests and node usage

  3. View the comparison charts showing current vs recommended costs

Example 3: Compare with Existing NodePools

  1. Ensure Kubernetes access is configured
  2. The tool automatically fetches existing NodePool configurations
  3. Recommendations show “before” (actual NodePools) vs “after” (recommended)
  4. View detailed cost and node count comparisons

🏗️ Architecture

Architecture Diagram

Karpenter Optimizer is built with a modern microservices architecture:

For detailed architecture documentation, see docs/architecture.md.

🔌 API Endpoints

Core Endpoints

See the Swagger UI for complete interactive API documentation with request/response schemas, or generate the docs with make swagger.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

🌟 Adopters

See ADOPTERS.md for a list of organizations using Karpenter Optimizer. If you’re using it, please add your organization via pull request!

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🔒 Security

For security vulnerabilities, please see SECURITY.md.

🙏 Acknowledgments

Made with ❤️ for the Kubernetes community

This site is open source. Improve this page.