Skip to content
GreenKube

REST API

GreenKube exposes a complete REST API powered by FastAPI, providing programmatic access to all metrics, recommendations, and configuration.

API Overview

Section titled “API Overview”

The API is served at http://<service>:8000/api/v1/ and includes:

  • Auto-generated OpenAPI docs at /docs (Swagger UI) and /redoc
  • CORS support for cross-origin dashboard access
  • JSON responses with consistent error handling
  • Pydantic v2 validation on all request/response models

Endpoints

Section titled “Endpoints”

Health & Status

Section titled “Health & Status”
MethodPathDescription
GET/healthHealth check (liveness)
GET/api/v1/versionAPI and app version
GET/api/v1/configCurrent configuration (redacted)

Metrics

Section titled “Metrics”
MethodPathDescription
GET/api/v1/metricsLatest metrics snapshot
GET/api/v1/metrics/namespacesMetrics grouped by namespace
GET/api/v1/metrics/nodesPer-node metrics and hardware info
GET/api/v1/metrics/podsPer-pod detailed metrics

Time Series

Section titled “Time Series”
MethodPathDescription
GET/api/v1/timeseriesHistorical metrics with filtering
GET/api/v1/timeseries/energyEnergy consumption over time
GET/api/v1/timeseries/carbonCarbon emissions over time
GET/api/v1/timeseries/costCost data over time

Recommendations

Section titled “Recommendations”
MethodPathDescription
GET/api/v1/recommendationsActive recommendations
GET/api/v1/recommendations/historyHistorical recommendations
GET/api/v1/recommendations/summaryAggregated savings potential

Prometheus Metrics

Section titled “Prometheus Metrics”
MethodPathDescription
GET/metricsPrometheus-format metrics for self-monitoring

Query Parameters

Section titled “Query Parameters”

Most endpoints support common query parameters:

?from=2024-01-01T00:00:00Z    # Start time (ISO 8601)
&to=2024-01-31T23:59:59Z      # End time (ISO 8601)
&namespace=production           # Filter by namespace
&group_by=daily                 # Aggregation: hourly/daily/weekly/monthly
&limit=100                      # Pagination
&offset=0                       # Pagination offset

Example Requests

Section titled “Example Requests”

Get Latest Metrics

Section titled “Get Latest Metrics”
Terminal window
curl http://localhost:8000/api/v1/metrics | jq

Get Carbon Emissions for a Namespace

Section titled “Get Carbon Emissions for a Namespace”
Terminal window
curl "http://localhost:8000/api/v1/timeseries/carbon?namespace=production&from=2024-01-01&group_by=daily"

Get Active Recommendations

Section titled “Get Active Recommendations”
Terminal window
curl http://localhost:8000/api/v1/recommendations?severity=critical

Authentication

Section titled “Authentication”

By default, the API is unauthenticated (designed for cluster-internal use). For external exposure, secure it behind:

  • Kubernetes Ingress with authentication
  • OAuth2 proxy
  • Network policies

CORS Configuration

Section titled “CORS Configuration”

CORS is enabled by default to allow the dashboard to communicate with the API:

greenkube:
  corsOrigins: "*"  # Restrict in production

Integration Examples

Section titled “Integration Examples”

Grafana Data Source

Section titled “Grafana Data Source”

Use the JSON API data source plugin to pull GreenKube metrics into Grafana dashboards.

CI/CD Pipeline

Section titled “CI/CD Pipeline”

Add carbon budget checks to your pipeline:

Terminal window
CARBON=$(curl -s http://greenkube:8000/api/v1/metrics | jq '.total_carbon_grams')
if [ $(echo "$CARBON > 1000" | bc) -eq 1 ]; then
  echo "Carbon budget exceeded!"
  exit 1
fi

Slack Notifications

Section titled “Slack Notifications”

Poll recommendations and send alerts for critical findings.

Section titled “Related”