Kubernetes Metrics Server is one of those components that most teams install once and then forget about, until kubectl top returns an error or a HorizontalPodAutoscaler refuses to scale. Understanding what it does, what it does not do, and how to read its data from Java code will save you a lot of debugging time.
This article covers the architecture of Metrics Server, how to install and verify it, how its data feeds kubectl top and autoscaling, the most common failure modes, and how to query the Metrics API from a Java application.
The problem it solves
Kubernetes schedules workloads based on the resource requests you declare, but the scheduler does not know how much CPU and memory your containers are actually using right now. Operators need that information to answer basic questions: which pod is consuming all the memory on this node, is this deployment over-provisioned, and should it scale out under load?
Metrics Server is the cluster add-on that answers these questions with current resource usage. It is intentionally narrow in scope. It only exposes CPU and memory usage for nodes and pods, and it keeps only the most recent sample.
Architecture in one picture
The data path has four steps:
- Every node runs a kubelet, which already collects container resource statistics from the container runtime.
- Metrics Server periodically queries each kubelet over HTTPS on port 10250 and aggregates the results. The default resolution is 15 seconds.
- Metrics Server keeps the latest values in memory. It does not write to etcd or to any disk store.
- The kube-apiserver exposes these values under
metrics.k8s.io/v1beta1through the API aggregation layer. Clients such askubectl, the Horizontal Pod Autoscaler, and the Vertical Pod Autoscaler read from that API, not from Metrics Server directly.
Because the data lives in memory, a restart of Metrics Server clears it. The first few seconds after a restart may return no data, which is normal.
Metrics Server is not a monitoring system. It has no history, no alerting, and no query language. For time series and dashboards, you still want Prometheus or a similar tool. Metrics Server is the lightweight source of truth for "what is happening right now" that the platform itself depends on.
Installing and verifying it
Many managed Kubernetes offerings install Metrics Server by default. If your cluster does not have it, the upstream project publishes a manifest:
kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml Wait for the deployment to become ready, then check that the aggregated API is registered:
kubectl get apiservice v1beta1.metrics.k8s.io kubectl top nodes kubectl top pods --all-namespaces --containers If the APIService shows Available: True and kubectl top nodes prints a table, the pipeline is working. If kubectl top says Metrics API not available, the problem is almost always in one of the areas covered in the troubleshooting section below.
Reading kubectl top
The output is simple but easy to misread:
NAME CPU(cores) MEMORY(bytes) orders-api-7f9c6d5b8-abcde 38m 412Mi orders-api-7f9c6d5b8-fghij 41m 398Mi CPU(cores) is expressed in millicores, where 1000m equals one full core. MEMORY(bytes) is the working set memory reported by the kubelet. Both values are instantaneous samples, so run the command a few times before drawing conclusions from a single reading.
Why requests matter more than you think
The Horizontal Pod Autoscaler (HPA) uses Metrics Server as its default source for CPU and memory. When you set a target like 70 percent CPU utilization, the percentage is calculated against the container's CPU request, not against the node's capacity. A pod that requests 100m and uses 80m is at 80 percent utilization. A pod with no request at all cannot be scaled on CPU utilization, and the HPA will report an error.
Here is a minimal HPA that scales a deployment between 2 and 10 replicas based on average CPU utilization:
apiVersion: autoscaling/v2 kind: HorizontalPodAutoscaler metadata: name: orders-api spec: scaleTargetRef: apiVersion: apps/v1 kind: Deployment name: orders-api minReplicas: 2 maxReplicas: 10 metrics: - type: Resource resource: name: cpu target: type: Utilization averageUtilization: 70 The corresponding deployment must declare requests, otherwise there is nothing to measure against:
resources: requests: cpu: 250m memory: 256Mi limits: memory: 512Mi Many teams set memory limits but omit CPU limits, which avoids CPU throttling while still letting the HPA work from requests. Choose the pattern that fits your workload, but always set requests.
Common failures and how to fix them
Metrics API not available. The APIService is not registered or is unhealthy. Run kubectl describe apiservice v1beta1.metrics.k8s.io and read the conditions. A common cause is a metrics-server pod that is crash-looping.
TLS errors when talking to kubelets. On many self-managed clusters, kubelet certificates are self-signed or not issued for the names Metrics Server tries to resolve. The logs show x509 errors. The proper fix is to configure kubelet certificates that the cluster trusts. For a throwaway development cluster only, you can pass --kubelet-insecure-tls to the Metrics Server container. Do not ship that flag to production.
no metrics known for pod. The pod started recently, or Metrics Server cannot reach the kubelet on that node. Check the Metrics Server logs and any NetworkPolicy that blocks traffic on port 10250.
Address resolution failures. If the node hostnames are not resolvable from the control plane, use --kubelet-preferred-address-types=InternalIP so Metrics Server connects by IP address.
HPA shows unknown for the current metric. Verify that the pods have requests and that kubectl top pods returns data for them. The HPA cannot compute utilization without both.
Querying the Metrics API from Java
Sometimes an application needs to read its own resource usage or that of its peers, for example to implement custom throttling, to expose a status endpoint, or to feed an internal capacity dashboard. The Metrics API is a regular REST endpoint, so Java can call it directly.
The following example runs inside a pod and uses the service account token that Kubernetes mounts automatically. It lists per-pod CPU and memory usage for a namespace and normalizes the Kubernetes quantity strings, which come in several units:
import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.ObjectMapper; import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.nio.file.Files; import java.nio.file.Path; public class PodMetricsReader { private static final String API_SERVER = "https://kubernetes.default.svc"; private static final Path TOKEN_FILE = Path.of("/var/run/secrets/kubernetes.io/serviceaccount/token"); private final HttpClient http; private final ObjectMapper mapper = new ObjectMapper(); public PodMetricsReader(HttpClient http) { this.http = http; } public JsonNode podMetrics(String namespace) throws Exception { String token = Files.readString(TOKEN_FILE).trim(); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create(API_SERVER + "/apis/metrics.k8s.io/v1beta1/namespaces/" + namespace + "/pods")) .header("Authorization", "Bearer " + token) .header("Accept", "application/json") .GET() .build(); HttpResponse<String> response = http.send(request, HttpResponse.BodyHandlers.ofString()); if (response.statusCode() != 200) { throw new IllegalStateException( "Metrics API returned " + response.statusCode() + ": " + response.body()); } return mapper.readTree(response.body()); } /** Converts CPU quantities such as "1234567n", "250m", or "2" into millicores. */ static double cpuToMillicores(String quantity) { if (quantity.endsWith("n")) { return Double.parseDouble(stripSuffix(quantity, 1)) / 1_000_000.0; } if (quantity.endsWith("u")) { return Double.parseDouble(stripSuffix(quantity, 1)) / 1_000.0; } if (quantity.endsWith("m")) { return Double.parseDouble(stripSuffix(quantity, 1)); } return Double.parseDouble(quantity) * 1000.0; } /** Converts memory quantities such as "512Ki", "126Mi", "1Gi", or raw bytes into MiB. */ static double memoryToMebibytes(String quantity) { if (quantity.endsWith("Ki")) { return Double.parseDouble(stripSuffix(quantity, 2)) / 1024.0; } if (quantity.endsWith("Mi")) { return Double.parseDouble(stripSuffix(quantity, 2)); } if (quantity.endsWith("Gi")) { return Double.parseDouble(stripSuffix(quantity, 2)) * 1024.0; } return Double.parseDouble(quantity) / (1024.0 * 1024.0); } private static String stripSuffix(String value, int length) { return value.substring(0, value.length() - length); } public static void main(String[] args) throws Exception { String namespace = args.length > 0 ? args[0] : "default"; PodMetricsReader reader = new PodMetricsReader(HttpClient.newHttpClient()); for (JsonNode pod : reader.podMetrics(namespace).path("items")) { String name = pod.path("metadata").path("name").asText(); double cpu = 0; double memory = 0; for (JsonNode container : pod.path("containers")) { cpu += cpuToMillicores(container.path("usage").path("cpu").asText()); memory += memoryToMebibytes(container.path("usage").path("memory").asText()); } System.out.printf("%-45s cpu=%.0fm memory=%.1fMiB%n", name, cpu, memory); } } } Two practical notes. First, the default HttpClient does not trust the cluster certificate authority. In production, build an SSLContext that loads the CA from /var/run/secrets/kubernetes.io/serviceaccount/ca.crt and pass it to HttpClient.newBuilder().sslContext(...). Second, the service account needs RBAC permission to read pods in metrics.k8s.io. Grant only get and list on that resource, scoped to the namespace the application needs.
The quantity parsing matters more than it looks. The Metrics API reports CPU in nanocores for precision, so a value like 38123456n means roughly 38 millicores. Mixing units without normalizing them produces numbers that look plausible but are wrong by orders of magnitude.
Best practices
Set requests on every container. This is the single most important habit. Requests drive scheduling, drive HPA utilization math, and make kubectl top results meaningful when compared against allocation.
Treat Metrics Server as a short-term source. Use it for autoscaling, quick diagnostics, and platform logic. Keep historical data, alerting, and capacity planning in Prometheus or another time-series system.
Scale the Metrics Server itself. On large clusters, the default replica count and resource requests may be too small. Watch its CPU and memory and adjust. Metrics Server should be cheap, but it is on the critical path for autoscaling.
Monitor the APIService. Alert when v1beta1.metrics.k8s.io is unavailable. A broken aggregated API fails silently for many consumers until an HPA stops scaling during a traffic spike.
Know its limits. Metrics Server only knows CPU and memory. Scaling on queue depth, request latency, or business metrics requires the custom metrics or external metrics APIs, usually backed by Prometheus Adapter or a similar component.
Restrict access. Metrics data reveals which workloads run and how busy they are. Limit read access to the metrics API through RBAC, the same way you would protect other cluster telemetry.
Conclusion and key takeaways
Metrics Server is small, but it sits underneath kubectl top, the Horizontal Pod Autoscaler, and several other platform features. Its design is intentionally simple: it keeps recent CPU and memory samples in memory and exposes them through the aggregation layer.
Key takeaways:
- Metrics Server collects current CPU and memory usage from kubelets and serves it through
metrics.k8s.io. - It holds no history. Use Prometheus for trends and alerts.
- HPA utilization is calculated against container requests, so requests are mandatory for CPU-based autoscaling.
- Most failures come from APIService health, kubelet TLS, network policies, or missing requests.
- Applications can query the Metrics API directly from Java, but must normalize Kubernetes quantities and secure their RBAC and TLS configuration.
If your cluster does not show metrics yet, start with kubectl get apiservice v1beta1.metrics.k8s.io. That single command tells you most of what you need to know.

