Skip to content

api-reference.md

Latest commit

 

History

History
322 lines (250 loc) · 5.77 KB

api-reference.md

File metadata and controls

322 lines (250 loc) · 5.77 KB

API Reference

Karpenter Optimizer provides a RESTful API for programmatic access to recommendations and cluster data.

Base URL

  • Local Development: http://localhost:8080
  • In-Cluster: http://karpenter-optimizer:8080 (service DNS)
  • Via Ingress: https://your-domain.com/api

Interactive Documentation

The API includes interactive Swagger/OpenAPI documentation:

  • Swagger UI: http://localhost:8080/api/swagger/index.html
  • OpenAPI Spec: http://localhost:8080/api/swagger/doc.json

Authentication

Currently, the API does not require authentication (assumes internal network access). Future versions may add authentication.

Endpoints

Health Check

GET /api/v1/health

Check API health and service status.

Response:

{
  "status": "healthy",
  "service": "karpenter-optimizer",
  "version": "0.0.1",
  "kubernetes": "connected",
  "aws_pricing": "available",
  "ollama": "available"
}

Get Cluster Summary

GET /api/v1/cluster/summary

Get cluster-wide statistics.

Response:

{
  "totalNodes": 10,
  "totalCPU": 40.0,
  "totalMemory": 160.0,
  "usedCPU": 25.5,
  "usedMemory": 80.0,
  "nodePools": 3
}

List NodePools

GET /api/v1/nodepools

List all NodePools with actual node data.

Response:

[
  {
    "name": "general-pool",
    "instanceTypes": ["m5.large", "m5.xlarge"],
    "capacityType": "spot",
    "nodes": [
      {
        "name": "node-1",
        "instanceType": "m5.large",
        "cpuUsage": 1.5,
        "memoryUsage": 4.0
      }
    ]
  }
]

Get NodePool Recommendations

GET /api/v1/nodepools/recommendations

Get recommendations for all NodePools.

Response:

[
  {
    "nodePoolName": "general-pool",
    "currentNodes": 5,
    "currentInstanceTypes": ["m5.large (3)", "m5.xlarge (2)"],
    "currentCPUUsed": 12.5,
    "currentCPUCapacity": 20.0,
    "currentMemoryUsed": 40.0,
    "currentMemoryCapacity": 80.0,
    "currentCost": 0.48,
    "recommendedNodes": 4,
    "recommendedInstanceTypes": ["m5.xlarge (4)"],
    "recommendedTotalCPU": 16.0,
    "recommendedTotalMemory": 64.0,
    "recommendedCost": 0.384,
    "costSavings": 0.096,
    "costSavingsPercent": 20.0,
    "reasoning": "AI-generated explanation...",
    "architecture": "amd64",
    "capacityType": "spot"
  }
]

Get Cluster Summary Recommendations

GET /api/v1/recommendations/cluster-summary

Get cluster-wide recommendations with AI explanations (SSE streaming).

Query Parameters:

  • stream (optional): Enable Server-Sent Events streaming (default: false)

Response (non-streaming):

{
  "recommendations": [...],
  "totalCostSavings": 0.5,
  "totalCostSavingsPercent": 15.0
}

Response (streaming): Server-Sent Events with progress updates:

event: progress
data: {"message": "Analyzing NodePools...", "progress": 25.0}

event: progress
data: {"message": "Generating recommendations...", "progress": 50.0}

event: complete
data: {"recommendations": [...], "totalCostSavings": 0.5}

List Nodes

GET /api/v1/nodes

Get all nodes with usage data.

Response:

[
  {
    "name": "node-1",
    "instanceType": "m5.large",
    "architecture": "amd64",
    "capacityType": "spot",
    "nodePool": "general-pool",
    "cpuUsage": {
      "used": 1.5,
      "capacity": 2.0,
      "percentage": 75.0
    },
    "memoryUsage": {
      "used": 4.0,
      "capacity": 8.0,
      "percentage": 50.0
    },
    "podCount": 10
  }
]

Get Node Disruptions

GET /api/v1/disruptions

Get node disruption information (on-demand nodes only).

Response:

[
  {
    "nodeName": "node-1",
    "nodePool": "general-pool",
    "disruptionReason": "FailedDraining",
    "blocked": true,
    "blockedReason": "Pod has PDB"
  }
]

Analyze Workloads

POST /api/v1/analyze

Analyze workloads and get recommendations (legacy endpoint).

Request Body:

{
  "workloads": [
    {
      "name": "app-1",
      "namespace": "default",
      "cpu": 2.0,
      "memory": 4.0
    }
  ]
}

Response:

{
  "recommendations": [...],
  "totalCost": 0.5
}

Error Responses

All errors follow this format:

{
  "error": "Error message",
  "code": "ERROR_CODE"
}

HTTP Status Codes:

  • 200 - Success
  • 400 - Bad Request
  • 404 - Not Found
  • 500 - Internal Server Error

Rate Limiting

Currently, there is no rate limiting. Future versions may add rate limiting.

CORS

CORS is enabled for local development. For production, configure CORS appropriately.

Examples

Using cURL

# Health check
curl http://localhost:8080/api/v1/health

# Get recommendations
curl http://localhost:8080/api/v1/nodepools/recommendations

# Get cluster summary
curl http://localhost:8080/api/v1/cluster/summary

Using JavaScript (Fetch API)

// Get recommendations
const response = await fetch('http://localhost:8080/api/v1/nodepools/recommendations');
const recommendations = await response.json();
console.log(recommendations);

Using Go

import "net/http"

resp, err := http.Get("http://localhost:8080/api/v1/health")
if err != nil {
    log.Fatal(err)
}
defer resp.Body.Close()

Swagger/OpenAPI

For complete API documentation with request/response schemas, see:

  • Swagger UI: http://localhost:8080/api/swagger/index.html
  • OpenAPI Spec: http://localhost:8080/api/swagger/doc.json

Generate Swagger docs locally:

make swagger

Versioning

The API uses URL versioning (/api/v1/). Future breaking changes will use /api/v2/.

Support

For API questions or issues: