Introduction

On kubeadm clusters, metrics-server problems usually come from one of four areas: the deployment itself is unhealthy, the API aggregation layer is not working, metrics-server cannot talk to kubelets, or certificate and address selection do not match the node setup. A good troubleshooting flow checks those layers in order instead of jumping directly to flags.

Start with the Obvious Signals

First confirm whether the deployment is running and whether the metrics API is registered.

kubectl get pods -n kube-system -l k8s-app=metrics-server
kubectl get apiservice v1beta1.metrics.k8s.io -o yaml
kubectl top nodes

These commands tell you three important things:

• whether the pod is up
• whether the aggregated API is available
• whether end-user metrics requests succeed at all

If kubectl top fails, read the exact error before changing configuration.

Read the Metrics-Server Logs

The logs often point straight at the broken layer.

kubectl logs -n kube-system deploy/metrics-server

Typical failures include:

• x509 certificate validation errors
• connection timeouts to kubelet port 10250
• forbidden or unauthorized kubelet responses
• address resolution problems on node IPs

Those messages are more useful than guessing from the deployment status alone.

Kubelet TLS and Address Problems

A very common kubeadm issue is that metrics-server connects to a node address that does not match the kubelet certificate SANs, or it chooses an unreachable node address type.

That is why these flags are frequently involved:

args:
  - --kubelet-preferred-address-types=InternalIP,Hostname,InternalDNS,ExternalDNS,ExternalIP
  - --kubelet-use-node-status-port

In development or broken lab environments, people sometimes add:

- --kubelet-insecure-tls

That can help diagnose certificate issues, but it should be treated as a workaround, not a first-choice production answer.

Check the Aggregation Layer

metrics-server exposes an aggregated API, so the API server aggregation setup must be healthy. If the APIService object shows unavailable status, inspect its conditions carefully.

kubectl describe apiservice v1beta1.metrics.k8s.io

If aggregation is unhealthy, even a running metrics-server pod will not satisfy kubectl top.

Verify Network Reachability to Kubelets

metrics-server needs to reach each kubelet on its secure port, usually 10250. Firewalls, node security policy, broken CNI routing, or control-plane isolation can block that path.

On kubeadm clusters, this is especially important when the cluster runs across several hosts or mixed network environments. A healthy pod and valid certificates still will not help if packets cannot reach the kubelets.

Version Compatibility Still Matters

Although metrics-server problems often look like certificates or networking, incompatible versions can also create confusing failures. If the deployment manifest came from an old blog post, check it against the cluster's Kubernetes version before chasing lower-level causes for too long.

That does not mean version mismatch is always the issue. It means stale manifests are common enough to rule out early.

Keep the Scope of the Problem Narrow

When kubectl top fails, do not assume the whole monitoring stack is broken. metrics-server is a very specific component with a very specific job. Narrowing the issue to aggregation, kubelet connectivity, or TLS removes a lot of noise from the debugging process and usually gets you to the real cause much faster.

Common Pitfalls

• Adding --kubelet-insecure-tls immediately instead of first identifying the actual certificate or address mismatch.
• Looking only at pod status and skipping kubectl describe apiservice.
• Ignoring kubelet reachability on port 10250.
• Letting metrics-server choose a node address type that is unreachable or not present in the kubelet certificate.
• Applying an outdated manifest without checking compatibility with the kubeadm cluster version.

Summary

• On kubeadm, troubleshoot metrics-server by checking pod health, APIService status, kubelet connectivity, and TLS expectations in that order.
• Use kubectl logs and kubectl describe apiservice before changing flags.
• Node address selection and kubelet certificate SANs are frequent root causes.
• '--kubelet-insecure-tls is a diagnostic shortcut, not the ideal long-term fix.'
• Many metrics-server issues are infrastructure and certificate problems rather than application bugs inside the component itself.