diff --git a/pkg/cmd/top/top.go b/pkg/cmd/top/top.go index 9f7e284c5..d5b9ecec2 100644 --- a/pkg/cmd/top/top.go +++ b/pkg/cmd/top/top.go @@ -39,9 +39,31 @@ var ( topLong = templates.LongDesc(i18n.T(` Display resource (CPU/memory) usage. - The top command allows you to see the resource consumption for nodes or pods. + This command provides a view of recent resource consumption for nodes and pods. + It fetches metrics from the Metrics Server, which aggregates this data from the + kubelet on each node. The Metrics Server must be installed and running in the + cluster for this command to work. - This command requires Metrics Server to be correctly configured and working on the server. `)) + The metrics shown are specifically optimized for Kubernetes autoscaling + decisions, such as those made by the Horizontal Pod Autoscaler (HPA) and + Vertical Pod Autoscaler (VPA). Because of this, the values may not match those + from standard OS tools like 'top', as the metrics are designed to provide a + stable signal for autoscalers rather than for pinpoint accuracy. + + When to use this command: + + * For on-the-fly spot-checks of resource usage (e.g. identify which pods + are consuming the most resources at a glance, or get a quick sense of the load + on your nodes) + * Understand current resource consumption patterns + * Validate the behavior of your HPA or VPA configurations by seeing the metrics + they use for scaling decisions. + + It is not intended to be a replacement for full-featured monitoring solutions. + Its primary design goal is to provide a low-overhead signal for autoscalers, + not to be a perfectly accurate monitoring tool. For high-accuracy reporting, + historical analysis, dashboarding, or alerting, you should use a dedicated + monitoring solution.`)) ) func NewCmdTop(f cmdutil.Factory, streams genericiooptions.IOStreams) *cobra.Command {