# kubernetes-sigs/metrics-server architecture

> Architecture diagram of the GitHub repository kubernetes-sigs/metrics-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kubernetes-sigs/metrics-server
- Repository: https://github.com/kubernetes-sigs/metrics-server

## Overview

##### Project Type and Purpose
- This project is a Kubernetes add-on that collects, processes, and exposes resource metrics from Kubelets running on cluster nodes. Its primary use is enabling horizontal and vertical autoscaling by integrating with Kubernetes’ Metrics API.
- The README emphasizes its role in autoscaling (via Horizontal Pod Autoscaler and Vertical Pod Autoscaler) and clearly states the design intent to be lightweight, efficient, and scalable to thousands of nodes.

##### File Structure
- The top-level structure includes configuration files (Dockerfile, Makefile, .github workflows, etc.), charts (Helm charts for deployment), manifests (Kubernetes YAML configurations for deploying Metrics Server and various profiles such as high availability), and the main source code in Go.
- The source code is organized across several directories:
- cmd/metrics-server: This is the entry point of the application.
- pkg/api, pkg/server, pkg/scraper, pkg/storage, pkg/utils: These packages modularize the application’s functions such as API endpoint handling, metrics scraping from Kubelets, storing and processing data, and health/monitoring routines.
- There are also dedicated directories for tests, documentation, and scripts, which indicate a mature project with CI/CD pipelines and deployments (e.g., through GitHub Actions and cloud build configurations).

##### Main Components
a. External Components:
- Kubernetes Control Plane & API Server: Acts as a consumer and a gateway which interacts with Metrics Server.
- Kubelets on Cluster Nodes: These are the endpoints that provide raw resource metrics.
b. Metrics Server Components:
- Metrics Server Pod/Container: Represented as a deployment in Kubernetes.
- Core Modules inside Metrics Server:
- API Layer (pkg/api): Handles requests from the Kubernetes API server and from tools like “kubectl top”.
- Metrics Server (pkg/server): Manages health checks, webhook communications, and serves endpoints.
- Scraper (pkg/scraper): Contains the logic to retrieve metrics from individual Kubelets.
- Storage (pkg/storage): Processes and likely caches or aggregates the metrics data.
- Utilities (pkg/utils): Provides helper functions such as address resolution and monitoring support.
c. Deployment Artifacts:
- Kubernetes Manifests (manifests/*): Define how the Metrics Server is deployed in various modes (default, high availability, test overlays).
- Helm Chart (charts/metrics-server): Offers an alternative, packaged deployment solution.
- Dockerfile & build scripts: Used for building container images.

##### Relationships and Interactions
- From Kubelets (each node) → Metrics Server’s scraper: The scraper module initiates connections to the Kubelet endpoints to pull resource usage data.
- From Metrics Server core modules (scraper, storage, API server) → Kubernetes API Server: The processed metrics are exposed via APIs for autoscaling and “kubectl top” commands.

##### Architectural Patterns and Design Principles
- Modular design: The separation into packages (API, server, scraper, storage, utils) suggests a layered architecture.
- Kubernetes-native design: The usage of manifests and Helm charts highlights that the component is tightly integrated with Kubernetes paradigms.
- Scalability: Emphasize that the Metrics Server is built to handle dynamic clusters with potentially up to 5,000 nodes and is optimized for resource efficiency.
- High availability: Highlight the HA mode in the manifests and Helm charts, indicating the importance of redundancy and load balancing (e.g., via aggregator routing).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Kubernetes Cluster
    subgraph "Kubernetes Cluster"
        A("Kubernetes API Server"):::external
        B("Kubelet on Node"):::external
        C("Metrics Server Pod"):::internal
    end

    %% Metrics Server Internal Components
    subgraph "Metrics Server"
        D("API Layer (pkg/api)"):::internal
        E("Server Core (pkg/server)"):::internal
        F("Metrics Scraper (pkg/scraper)"):::internal
        G("Data Storage (pkg/storage)"):::internal
        H("Supporting Utilities (pkg/utils)"):::internal
        I("Application Entry Point (cmd/metrics-server)"):::internal
    end

    %% Deployment & Build Artifacts
    subgraph "Deployment & Build"
        M("Kubernetes Manifests"):::deployment
        N("Helm Chart"):::deployment
        O("Dockerfile"):::deployment
        P("Makefile"):::deployment
        Q(".github/workflows"):::deployment
        R("cloudbuild.yaml"):::deployment
    end

    %% External Data Flow
    B -->|"PullMetricsData"| F
    D -->|"ExposeMetricsAPI"| A

    %% Internal Composition within Metrics Server Pod
    C --> D
    C --> E
    C --> F
    C --> G
    C --> H
    C --> I

    %% Deployment Artifacts feed into Metrics Server Pod
    M --> C
    N --> C
    O --> C
    P --> C
    Q --> C
    R --> C

    %% Click Events for Component Mapping
    click D "https://github.com/kubernetes-sigs/metrics-server/tree/master/pkg/api"
    click E "https://github.com/kubernetes-sigs/metrics-server/tree/master/pkg/server"
    click F "https://github.com/kubernetes-sigs/metrics-server/tree/master/pkg/scraper"
    click G "https://github.com/kubernetes-sigs/metrics-server/tree/master/pkg/storage"
    click H "https://github.com/kubernetes-sigs/metrics-server/tree/master/pkg/utils"
    click I "https://github.com/kubernetes-sigs/metrics-server/tree/master/cmd/metrics-server"
    click M "https://github.com/kubernetes-sigs/metrics-server/tree/master/manifests"
    click N "https://github.com/kubernetes-sigs/metrics-server/tree/master/charts/metrics-server"
    click O "https://github.com/kubernetes-sigs/metrics-server/tree/master/Dockerfile"
    click P "https://github.com/kubernetes-sigs/metrics-server/tree/master/Makefile"
    click Q "https://github.com/kubernetes-sigs/metrics-server/tree/master/.github/workflows"
    click R "https://github.com/kubernetes-sigs/metrics-server/blob/master/cloudbuild.yaml"

    %% Styles
    classDef external fill:#f9e79f,stroke:#333,stroke-width:2px;
    classDef internal fill:#aed6f1,stroke:#333,stroke-width:2px;
    classDef deployment fill:#a9dfbf,stroke:#333,stroke-width:2px;
```
