|
| 1 | +--- |
| 2 | +title: Kubelet Summary API |
| 3 | +content_type: reference |
| 4 | +weight: 55 |
| 5 | +description: >- |
| 6 | + The kubelet Summary API for accessing node, pod, and container metrics. |
| 7 | +--- |
| 8 | + |
| 9 | +<!-- overview --> |
| 10 | + |
| 11 | +The kubelet exposes a Summary API at the `/stats/summary` endpoint that provides |
| 12 | +aggregated metrics for nodes, pods, containers, and volumes. This API serves as a |
| 13 | +primary source for resource usage data collected by the kubelet. |
| 14 | + |
| 15 | +<!-- body --> |
| 16 | + |
| 17 | +## Accessing the Summary API |
| 18 | + |
| 19 | +You can access the Summary API through the Kubernetes API server as a proxy: |
| 20 | + |
| 21 | +```shell |
| 22 | +kubectl get --raw "/api/v1/nodes/<NODE_NAME>/proxy/stats/summary" |
| 23 | +``` |
| 24 | + |
| 25 | +Replace `<NODE_NAME>` with the name of the node you want to query. |
| 26 | + |
| 27 | +Alternatively, if you have direct access to the kubelet port (typically 10250), |
| 28 | +you can query it directly: |
| 29 | + |
| 30 | +```shell |
| 31 | +curl -k https://<NODE_IP>:10250/stats/summary |
| 32 | +``` |
| 33 | + |
| 34 | +{{< note >}} |
| 35 | +Direct access to the kubelet requires proper authentication and is typically |
| 36 | +restricted in production environments. Using `kubectl proxy` is the recommended |
| 37 | +approach. |
| 38 | +{{< /note >}} |
| 39 | + |
| 40 | +## API Response Structure |
| 41 | + |
| 42 | +The Summary API returns a JSON object containing comprehensive metrics organized |
| 43 | +hierarchically: |
| 44 | + |
| 45 | +```json |
| 46 | +{ |
| 47 | + "node": { |
| 48 | + "nodeName": "node-1", |
| 49 | + "systemContainers": [...], |
| 50 | + "startTime": "2024-01-01T00:00:00Z", |
| 51 | + "cpu": {...}, |
| 52 | + "memory": {...}, |
| 53 | + "network": {...}, |
| 54 | + "fs": {...}, |
| 55 | + "runtime": {...}, |
| 56 | + "rlimit": {...} |
| 57 | + }, |
| 58 | + "pods": [ |
| 59 | + { |
| 60 | + "podRef": { |
| 61 | + "name": "pod-name", |
| 62 | + "namespace": "namespace", |
| 63 | + "uid": "pod-uid" |
| 64 | + }, |
| 65 | + "startTime": "2024-01-01T00:00:00Z", |
| 66 | + "containers": [...], |
| 67 | + "cpu": {...}, |
| 68 | + "memory": {...}, |
| 69 | + "network": {...}, |
| 70 | + "volume": [...], |
| 71 | + "ephemeral-storage": {...}, |
| 72 | + "process_stats": {...} |
| 73 | + } |
| 74 | + ] |
| 75 | +} |
| 76 | +``` |
| 77 | + |
| 78 | +## Metrics Categories |
| 79 | + |
| 80 | +### Node-Level Metrics |
| 81 | + |
| 82 | +- **CPU**: Usage statistics including total usage and cumulative usage |
| 83 | +- **Memory**: Working set, available memory, usage, RSS, and page faults |
| 84 | +- **Network**: Interface statistics with RX/TX bytes and errors |
| 85 | +- **Filesystem**: Capacity, available space, and usage for the root filesystem |
| 86 | +- **Runtime**: Container runtime information and image filesystem stats |
| 87 | +- **Rlimit**: System resource limits |
| 88 | + |
| 89 | +### Pod-Level Metrics |
| 90 | + |
| 91 | +- **CPU**: Aggregate CPU usage for all containers in the pod |
| 92 | +- **Memory**: Aggregate memory statistics for the pod |
| 93 | +- **Network**: Pod-level network I/O statistics |
| 94 | +- **Volume**: Usage statistics for each volume mounted in the pod |
| 95 | +- **Ephemeral Storage**: Total filesystem usage for containers and emptyDir volumes |
| 96 | + |
| 97 | +### Container-Level Metrics |
| 98 | + |
| 99 | +- **CPU**: Per-container CPU usage and cumulative usage |
| 100 | +- **Memory**: Per-container memory statistics |
| 101 | +- **Rootfs**: Container writable layer usage |
| 102 | +- **Logs**: Container logs storage usage |
| 103 | +- **Accelerators**: GPU and other accelerator metrics (if applicable) |
| 104 | +- **User-defined metrics**: Custom metrics exposed by containers |
| 105 | + |
| 106 | +## Data Sources |
| 107 | + |
| 108 | +By default, the kubelet collects these metrics using an embedded |
| 109 | +[cAdvisor](https://github.com/google/cadvisor). However, when the |
| 110 | +`PodAndContainerStatsFromCRI` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) |
| 111 | +is enabled, the kubelet can fetch pod and container metrics directly from the |
| 112 | +[Container Runtime Interface (CRI)](/docs/concepts/architecture/cri/). |
| 113 | + |
| 114 | +## Common Use Cases |
| 115 | + |
| 116 | +1. **Monitoring Solutions**: Tools like metrics-server (prior to v0.6.x) use the |
| 117 | + Summary API to collect cluster-wide metrics. |
| 118 | + |
| 119 | +2. **Debugging Resource Usage**: Administrators can query the API to understand |
| 120 | + actual resource consumption versus configured requests and limits. |
| 121 | + |
| 122 | +3. **Custom Autoscaling**: The Summary API can provide data for custom autoscaling |
| 123 | + solutions or vertical pod autoscaling. |
| 124 | + |
| 125 | +4. **Capacity Planning**: Historical data from the Summary API helps in understanding |
| 126 | + resource utilization patterns. |
| 127 | + |
| 128 | +## Limitations and Considerations |
| 129 | + |
| 130 | +- Starting with metrics-server v0.6.x, the preferred endpoint is `/metrics/resource` |
| 131 | + instead of `/stats/summary`. |
| 132 | +- The Summary API provides point-in-time data and doesn't store historical metrics. |
| 133 | +- Access to the Summary API requires appropriate RBAC permissions when accessed |
| 134 | + through the API server. |
| 135 | +- The data format is specific to Kubernetes and differs from Prometheus-style metrics. |
| 136 | + |
| 137 | +## {{% heading "whatsnext" %}} |
| 138 | + |
| 139 | +- Learn more about [Node Metrics](/docs/reference/instrumentation/node-metrics/) |
| 140 | +- Explore [CRI Pod & Container Metrics](/docs/reference/instrumentation/cri-pod-container-metrics/) |
| 141 | +- Read about [Kubernetes Metrics](/docs/concepts/cluster-administration/system-metrics/) |
0 commit comments