api

BSS Metrics API Server

This is an API Server implemented in Golang for receiving and processing BSS (BPF Scheduler Subsystem) metrics data and providing system information.

DEMO

Click the image below to see our DEMO on YouTube!

Features

• Receive BSS metrics data sent by clients
• Query pod-to-PID mappings from the system
• Provide RESTful API in JSON format
• Include health check endpoint
• Support CORS
• Request logging capability
• Error handling and validation
• Kubernetes integration for pod label information
• Configurable scheduling strategies based on pod labels

API Endpoints

1. Submit Metrics Data

• URL: /api/v1/metrics
• Method: POST
• Content-Type: application/json

Request Format

{
  "usersched_pid": 1234,
  "nr_queued": 10,
  "nr_scheduled": 5,
  "nr_running": 2,
  "nr_online_cpus": 8,
  "nr_user_dispatches": 100,
  "nr_kernel_dispatches": 50,
  "nr_cancel_dispatches": 2,
  "nr_bounce_dispatches": 1,
  "nr_failed_dispatches": 0,
  "nr_sched_congested": 3
}

Success Response

{
  "success": true,
  "message": "Metrics received successfully",
  "timestamp": "2025-06-19T10:30:00Z"
}

Error Response

{
  "success": false,
  "error": "Invalid JSON format: ..."
}

2. Get Pod-PID Mappings

• URL: /api/v1/pods/pids
• Method: GET

Response

{
  "success": true,
  "message": "Pod-PID mappings retrieved successfully",
  "timestamp": "2025-06-25T13:50:21Z",
  "pods": [
    {
      "pod_name": "",
      "namespace": "",
      "pod_uid": "65979e01-4cb1-4d08-9dba-45530253ff00",
      "container_id": "5148a146ffbbe8672f11494843d54b8769d2eccc677c02027fc09aba192e3c67",
      "processes": [
        {
          "pid": 717720,
          "command": "pause",
          "ppid": 717576
        },
        {
          "pid": 718001,
          "command": "loki",
          "ppid": 717576
        }
      ]
    }
  ]
}

Error Response

{
  "success": false,
  "error": "Failed to get pod-pid mappings: ..."
}

3. Get and Set Scheduling Strategies

• URL: /api/v1/scheduling/strategies
• Methods: GET, POST
• Content-Type: application/json

GET Response

{
  "success": true,
  "message": "Scheduling strategies retrieved successfully",
  "timestamp": "2025-06-19T10:30:00Z",
  "scheduling": [
    {
      "priority": true,
      "execution_time": 20000000,
      "pid": 718001
    },
    {
      "priority": false,
      "execution_time": 10000000,
      "pid": 717720
    }
  ]
}

POST Request Format

{
  "strategies": [
    {
      "priority": true,
      "execution_time": 20000000,
      "selectors": [
        {
          "key": "nf",
          "value": "upf"
        }
      ]
    },
    {
      "priority": false,
      "execution_time": 10000000,
      "pid": 717720
    }
  ]
}

POST Success Response

{
  "success": true,
  "message": "Scheduling strategies saved successfully",
  "timestamp": "2025-06-19T10:30:00Z"
}

4. Health Check

• URL: /health
• Method: GET

Response

{
  "status": "healthy",
  "timestamp": "2025-06-19T10:30:00Z",
  "service": "BSS Metrics API Server"
}

5. API Information

• URL: /
• Method: GET

Quick Start

1. Install Dependencies

go mod tidy

2. Start Service

go run main.go

The service will start on http://localhost:8080.

3. Start Service with Kubernetes integration

# Use local Kubernetes config
go run main.go --kubeconfig=$HOME/.kube/config

# Run in-cluster (when deployed in Kubernetes)
go run main.go --in-cluster=true

4. Test API

Submit metrics data

curl -X POST http://localhost:8080/api/v1/metrics \
  -H "Content-Type: application/json" \
  -d '{
    "usersched_pid": 1234,
    "nr_queued": 10,
    "nr_scheduled": 5,
    "nr_running": 2,
    "nr_online_cpus": 8,
    "nr_user_dispatches": 100,
    "nr_kernel_dispatches": 50,
    "nr_cancel_dispatches": 2,
    "nr_bounce_dispatches": 1,
    "nr_failed_dispatches": 0,
    "nr_sched_congested": 3
  }'

Check health status

curl http://localhost:8080/health

Query Pod-PID Mappings

# Get all pod-pid mappings
curl -X GET http://localhost:8080/api/v1/pods/pids

# Format output with jq for better readability
curl -s -X GET http://localhost:8080/api/v1/pods/pids | jq '.'

# Get only specific information (example: extract pod UIDs and process counts)
curl -s -X GET http://localhost:8080/api/v1/pods/pids | jq '.pods[] | {pod_uid: .pod_uid, process_count: (.processes | length)}'

Get scheduling strategies

curl -X GET http://localhost:8080/api/v1/scheduling/strategies

Set scheduling strategies

curl -X POST http://localhost:8080/api/v1/scheduling/strategies \
  -H "Content-Type: application/json" \
  -d '{
    "strategies": [
      {
        "priority": true,
        "execution_time": 20000000,
        "selectors": [
          {
            "key": "nf",
            "value": "upf"
          }
        ]
      },
      {
        "priority": false,
        "execution_time": 10000000,
        "pid": 717720
      }
    ]
  }'

Data Structure Description

BssData Structure

PodInfo Structure

PodProcess Structure

SchedulingStrategy Structure

LabelSelector Structure

Development and Extension

Suggested New Features

1. Data Persistence: Store received metrics to database (such as PostgreSQL, MongoDB)
2. Data Analytics: Add statistical and analytical features
3. Alert System: Set up alert rules based on metrics values
4. Authentication & Authorization: Add API key or JWT authentication
5. Batch Processing: Support batch submission of multiple metrics data
6. Monitoring Dashboard: Build web interface to visualize metrics data

Architecture Description

• Uses Gorilla Mux for routing
• Includes middleware for CORS and logging
• Structured error handling and response format
• Timestamps use RFC3339 format
• Kubernetes client integration with caching
• Support for both in-cluster and out-of-cluster operation

Kubernetes 整合

此 API 伺服器可以與 Kubernetes 整合，以獲取真實的 Pod 標籤資訊。它支援兩種運行模式：

在 Kubernetes 集群內運行

當在 Kubernetes 集群內部署時，API 伺服器會自動使用 ServiceAccount 連接到 Kubernetes API。完整的部署清單可在 k8s/deployment.yaml 中找到，其中包含：

• 具備必要權限的 ServiceAccount
• 具有健康檢查的 Deployment
• 用於公開 API 的 Service

部署命令：

kubectl apply -f k8s/deployment.yaml

在集群外運行

當在 Kubernetes 集群外運行時，API 伺服器會嘗試使用 kubeconfig 文件連接到 Kubernetes API。預設情況下，它會使用 ~/.kube/config 路徑，您也可以通過設置 KUBECONFIG 環境變數或使用 --kubeconfig 參數來指定不同的路徑：

export KUBECONFIG=/path/to/your/kubeconfig
go run main.go

# 或者
go run main.go --kubeconfig=/path/to/your/kubeconfig

實時 Pod 標籤更新

API 伺服器會定期刷新其 Pod 標籤緩存，以確保即使在 Pod 標籤變更時，調度策略也能正確應用。

降級到模擬數據

如果無法連接到 Kubernetes API，系統會自動降級使用模擬數據。這對於開發和測試環境很有用。

Docker 映像建立

要建立 Docker 映像：

docker build -t bss-metrics-api:latest .

容器映像釋出

此專案使用 GitHub Actions 自動建置和釋出容器映像到 GitHub Container Registry (ghcr.io)。

自動釋出觸發條件：

• 當推送到 main 分支時
• 當建立新的版本標籤時（例如：v1.0.0）

映像標籤規則：

• main 分支的推送將標記為 main 和 main-<sha>
• 版本標籤將標記為 v1.0.0、1.0、1 等

使用已釋出的映像：

# 使用最新的 main 版本
docker pull ghcr.io/gthulhu/api:main

# 使用特定版本
docker pull ghcr.io/gthulhu/api:v1.0.0

License

This project is open source.