Skip to content

Kubernetes (K3s) Module API Explanation

The Kubernetes (K3s) module monitors node resource allocation and real-time CPU/memory utilization percentages across cluster nodes.

API Execution Logic

The backend process parses the active services declared in the configuration file to discover any services with identifiers prefixed by k3s or kubernetes. For each discovered instance, the API URL is resolved, and the bearer authentication token is retrieved from the K3S_TOKEN environment variable.

Dual-Endpoint Query Execution

Unlike standard API services that return capacity and usage within a single payload, the Kubernetes Metrics API only reports raw resource utilization without node capacity specifications. Therefore, the module must query two separate cluster endpoints in parallel using Promise.all:

  1. Metrics Query: A request is sent to /apis/metrics.k8s.io/v1beta1/nodes/[NODE_NAME] to retrieve active CPU and memory usage.
  2. Node Specification Query: A request is sent to /api/v1/nodes/[NODE_NAME] to retrieve the total allocatable CPU and memory capacity.

Both requests attach the Authorization: Bearer [TOKEN] header and enforce a 5-second timeout.

Data Parsing and Unit Conversion

For each node, a dual-endpoint query process is executed to compute percentages:

  • CPU Utilization: The module parses CPU usage (reported in nanocores ending with n or millicores ending with m or u) and divides it by the total allocatable CPU cores (converted to millicores). The quotient is multiplied by 100 and rounded to integer precision.
  • Memory Utilization: Memory usage (reported in Ki or Mi) and allocatable memory (Ki, Mi, or Gi) are normalized to bytes. Usage is divided by total capacity, multiplied by 100, and rounded to integer precision.

Metric Output

  • Primary Metric: The average CPU utilization percentage across all monitored nodes.
  • Secondary Metric: The average memory utilization percentage across all monitored nodes.
  • Specs Output: Returns string representations of total cores and memory capacity (e.g., 4 Cores | 16 GB RAM).

Caching Strategy

Cluster metrics are cached in memory for 15 seconds (TTL) with a stale window of up to 60 seconds.