If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/kubernetes-sigs/metrics-server shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 1w ago
• 12 active contributors
• Distributed ownership (top contributor 47% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live kubernetes-sigs/metrics-server repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/kubernetes-sigs/metrics-server.

What it runs against: a local clone of kubernetes-sigs/metrics-server — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in kubernetes-sigs/metrics-server | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 40 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of kubernetes-sigs/metrics-server. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/kubernetes-sigs/metrics-server.git
#   cd metrics-server
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of kubernetes-sigs/metrics-server and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "kubernetes-sigs/metrics-server(\\.git)?\\b" \\
  && ok "origin remote is kubernetes-sigs/metrics-server" \\
  || miss "origin remote is not kubernetes-sigs/metrics-server (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 40 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~10d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/kubernetes-sigs/metrics-server"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Metrics Server is a Kubernetes component that collects container resource metrics (CPU, memory) from Kubelets and exposes them via the Kubernetes Metrics API, enabling the Horizontal Pod Autoscaler and Vertical Pod Autoscaler to make scaling decisions. It provides efficient, low-overhead metric collection (1 milli-core CPU, 2 MB memory per node) and scales to 5,000-node clusters with a 15-second collection interval. Single-binary Go application with: cmd/ directory for CLI entry points, pkg/ for core metrics collection logic (kubelet scraping, API exposition), charts/metrics-server/ for Helm deployment manifests, and test coverage integrated alongside source files (*_test.go pattern). The Dockerfile and Makefile orchestrate building and releasing container images for multi-architecture support.

Kubernetes cluster administrators and DevOps engineers who need to enable autoscaling for their workloads, and Kubernetes distributors (EKS, GKE, etc.) who integrate autoscaling into their platforms. Contributors are typically maintainers of Kubernetes ecosystem projects and autoscaling systems.

Production-ready and actively maintained. The project is part of kubernetes-sigs (official Kubernetes special interest groups), requires Go 1.26.1, has comprehensive GitHub Actions CI/CD workflows (.github/workflows/), Helm chart distribution via charts/metrics-server/, and is currently synced with Kubernetes v0.35.0 APIs. Active dependency management via dependabot.yaml indicates ongoing maintenance.

Standard open source risks apply.

Active development against Kubernetes 1.35 APIs. Recent activity includes: Helm chart updates (charts/metrics-server/CHANGELOG.md), GitHub Actions workflow refinement (.github/workflows/release.yaml, lint-test-chart.yaml), and dependency updates (go.mod shows recent prometheus, k8s.io/apiserver versions). Dependabot is actively managing transitive dependencies.

git clone https://github.com/kubernetes-sigs/metrics-server.git
cd metrics-server
make
make test

Build targets and test setup defined in Makefile. Go 1.26.1+ required per go.mod.

Daily commands:

make
./metrics-server --help

For Kubernetes: helm install metrics-server charts/metrics-server/ after configuring values.yaml for your cluster (TLS mode, kubelet args, etc.). Development: use Makefile targets for lint, test, and container image builds.

• pkg/scraper/client.go: Core Kubelet scraping client: handles mTLS, node authorization, and metric collection from each node's metrics endpoint
• pkg/api/register.go: Metrics API registration with aggregated apiserver; defines how metrics are exposed to kubectl and autoscalers
• cmd/metrics-server/main.go: Entry point with cobra CLI flag definitions (kubelet-insecure-tls, kubelet-preferred-address-types, etc.)
• charts/metrics-server/templates/deployment.yaml: Kubernetes Deployment manifest; defines Pod security, service account, RBAC role references, and resource limits
• charts/metrics-server/values.yaml: Helm configuration template; contains all user-facing options (image, replicas, TLS mode, kubelet flags, resources)
• .github/workflows/release.yaml: Release pipeline: builds multi-arch container images, publishes Helm charts, and tags releases
• go.mod: Dependency declarations showing coupling to k8s.io/apiserver v0.35.0, prometheus instrumentation, and test frameworks

Start in pkg/ for metric collection logic: pkg/scraper/ handles Kubelet communication, pkg/api/ exposes the Metrics API. Tests are colocated (*_test.go). For CLI changes, edit cmd/ and use spf13/cobra's flag patterns. For deployment: modify charts/metrics-server/templates/ (YAML templates use Go's text/template syntax, see charts/metrics-server/templates/_helpers.tpl). Add test coverage alongside new code using ginkgo.

Kubelet certificate validation: by default metrics-server validates Kubelet certs against the cluster CA; for self-signed certs, you must pass --kubelet-insecure-tls (security tradeoff). Aggregation layer: apiserver must have --enable-aggregator-routing enabled; without it, metrics requests fail silently. RBAC: metrics-server requires 'view' permissions on all pods/nodes and 'get' on nonresourceurl '/metrics'; the Helm chart grants these but manual RBAC setup often misses nonresourceurl. TLS modes: the Helm chart supports none (--kubelet-insecure-tls), helm-generated certs, cert-manager integration, or existing secrets (charts/metrics-server/ci/ shows each)—wrong mode choice breaks the scrape loop.

• Kubernetes Aggregated API Layer — Metrics Server registers the /apis/metrics.k8s.io custom API as a delegate to kube-apiserver, making metrics queryable like native Kubernetes resources; understanding aggregation is critical for deployment troubleshooting
• Kubelet Metrics Endpoint (cAdvisor Integration) — Metrics Server scrapes /stats/summary from each Kubelet, which is populated by cAdvisor; cAdvisor's sampling interval and container runtime integration directly affect metric accuracy and collection overhead
• mTLS (Mutual TLS) Authentication — Metrics Server authenticates to Kubelets using client certificates signed by the cluster CA; certificate validation failures are a common deployment blocker, and --kubelet-insecure-tls is a last-resort bypass
• Resource Requests vs. Usage Metrics — HPA and VPA use metrics-server's actual container usage (CPU, memory) to compare against requests/limits and scale; conflating requests (desired) with usage (observed) is a common autoscaling misconfiguration
• Helm Chart Templating — The charts/metrics-server/ Helm chart uses Go text/template syntax with custom helpers to generate RBAC, TLS configs, and Pod specs; understanding template conditionals is required to customize deployments
• Kubernetes API Webhook Authentication/Authorization — Metrics Server requires Kubelet webhook auth/authz enabled so the Kubelet can verify the metrics-server Pod's identity; if disabled, all kubelet requests fail with 403 Forbidden
• Ginkgo BDD Test Framework — The codebase uses ginkgo/v2 with Describe/It/BeforeEach patterns for test organization; familiarizing yourself with Ginkgo is necessary to write and debug tests in this project

• kubernetes/kubernetes — Parent Kubernetes repository; metrics-server integrates with kube-apiserver aggregation layer and kubelet's metrics endpoint defined here
• kubernetes/metrics — API definition repository for the Metrics API types (PodMetrics, NodeMetrics) that metrics-server exposes through its API server
• kubernetes/autoscaler — Hosts Horizontal Pod Autoscaler and Vertical Pod Autoscaler implementations that consume metrics-server's API for scaling decisions
• prometheus/prometheus — Full-featured monitoring platform; metrics-server is the opposite design choice—minimal, Kubernetes-native metric collection for autoscaling only, not general observability
• kubernetes/kube-state-metrics — Companion Kubernetes SIG project; while metrics-server exports resource metrics, kube-state-metrics exports cluster state (object counts, conditions), and both often run together

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for kubelet_client options validation

The cmd/metrics-server/app/options/ directory has kubelet_client.go and kubelet_client_test.go, but based on the options structure handling TLS, authentication, and kubelet connectivity, the test coverage appears incomplete. New contributors could add integration tests for various kubelet client configurations (TLS cert validation, bearer tokens, client certificates, insecure modes) that verify end-to-end behavior rather than just unit-level testing.

• [ ] Examine cmd/metrics-server/app/options/kubelet_client.go to identify all TLS/auth configuration paths
• [ ] Review existing cmd/metrics-server/app/options/kubelet_client_test.go to identify gaps in coverage
• [ ] Add integration-level tests for certificate validation scenarios, bearer token handling, and fallback behaviors
• [ ] Add edge case tests for conflicting kubelet client options (e.g., insecure + certificate validation)
• [ ] Document test scenarios in CONTRIBUTING.md if not already present

Add CI workflow for Helm chart security scanning and policy validation

The charts/metrics-server directory contains production Helm templates with RBAC, APIService, and security-sensitive configurations (PSP, deployments), but there's no automated security scanning in .github/workflows/. Adding a workflow for Helm security scanning (using tools like Checkov, Kubesec, or Helm Lint with policies) would catch misconfigurations before release and provide security assurance to users.

• [ ] Review existing workflows in .github/workflows/ to understand current chart testing (lint-test-chart.yaml exists)
• [ ] Integrate Kubesec or Checkov scanning for Kubernetes YAML manifests generated from charts/metrics-server/templates/
• [ ] Add validation for Pod Security Standards (PSP templates exist but need runtime validation)
• [ ] Create new workflow file .github/workflows/chart-security-scan.yaml with automated policy checks
• [ ] Document security scanning results in the Helm chart README.md

Implement metrics-server specific command-line flag documentation generator

The docs/command-line-flags.txt file exists but appears to be static documentation. Given that cmd/metrics-server/app/options/options.go defines all CLI flags, new contributors could create a code generation tool that automatically extracts flag definitions from the Go source and generates authoritative documentation, keeping docs/command-line-flags.txt and any generated flag documentation in sync with the actual code.

• [ ] Analyze cmd/metrics-server/app/options/options.go structure to identify how Cobra/pflag flags are defined
• [ ] Create a new tool in cmd/ directory (e.g., cmd/gen-flags-doc/) that parses flag definitions
• [ ] Generate markdown documentation from flag metadata (description, defaults, type)
• [ ] Integrate the tool into the Makefile with a target like 'make generate-docs'
• [ ] Add CI step in .github/workflows/ to verify docs/command-line-flags.txt is up-to-date with code

• Add integration tests for Kubelet scraping with TLS client certificates: currently tests mock Kubelet responses (test doubles), but end-to-end tests verifying mTLS validation logic and cert rotation are missing from test coverage.
• Document failure modes in KNOWN_ISSUES.md: add specific examples like 'aggregation layer disabled' symptoms and diagnostic commands (e.g., kubectl get APIService metrics.k8s.io -o yaml to check if registered), which would help users debug deployment failures.
• Add Prometheus metrics export to metrics-server's /metrics endpoint: the binary imports prometheus/prometheus but doesn't currently expose request latency, kubelet scrape errors, or memory collection metrics that cluster monitoring solutions expect.

The metrics-server codebase demonstrates solid security practices overall. Strengths include: use of distroless base images, non-root user execution, clear security policy, and established vulnerability reporting procedures. However, there are concerns with the Go version specification (1.26.1 appears to be a placeholder), use of 'latest' image tags reducing reproducibility, and limited visibility into supply chain security practices (SBOM, provenance signing). No hardcoded secrets, SQL injection risks, or XSS vulnerabilities were identified in the visible file structure. The project follows Kubernetes security best practices and uses modern Go dependencies. Recommendations focus on version pinning, supply chain transparency, and verification of test coverage for security-critical components.

• Medium · Go Version Mismatch - Future Compatibility Risk — go.mod. The go.mod file specifies 'go 1.26.1' which is a future Go version (as of current knowledge cutoff in April 2024). This version doesn't exist yet and may indicate a typo or placeholder. This could cause build failures and dependency resolution issues when the actual Go 1.26.1 is released, as dependencies may not be compatible with this far-future version. Fix: Verify the intended Go version. Update to a stable, currently available Go version (e.g., 1.22.x or 1.23.x). Ensure all dependencies are compatible with the target Go version before updating.
• Low · Distroless Image Without Version Pinning — Dockerfile (line 16). The Dockerfile uses 'gcr.io/distroless/static:latest-$ARCH' which pulls the latest tag. While distroless images are security-hardened, using 'latest' tag prevents reproducible builds and makes it difficult to track which version is running in production. This could lead to unexpected behavior changes between builds. Fix: Pin the distroless image to a specific version/digest instead of using 'latest'. Example: 'gcr.io/distroless/static:nonroot-$ARCH' with a specific version tag or SHA256 digest for reproducibility and security.
• Low · Non-Root User UID Hardcoded — Dockerfile (line 17). The Dockerfile uses 'USER 65534' which is a hardcoded UID. While running as non-root is a security best practice, using a numeric UID without verification that it exists in the image could lead to unexpected behavior. The distroless image should be verified to have this UID. Fix: Verify that UID 65534 exists in the distroless/static image. Consider using named users (e.g., 'nonroot') if available in the base image, or document the rationale for this specific UID choice.
• Low · Missing SBOM and Supply Chain Security — GitHub workflows and release process. While the project has good infrastructure (GitHub workflows, security policy), there's no evidence of SBOM (Software Bill of Materials) generation or provenance signing in the visible CI/CD configuration. This limits transparency and traceability of dependencies for consumers. Fix: Implement SBOM generation using tools like syft or cyclonedx during the release process. Consider implementing provenance attestation using Sigstore/cosign to sign container images and allow verification of build artifacts.
• Low · Potential Test Coverage for Kubelet Client Configuration — cmd/metrics-server/app/options/kubelet_client.go. The file structure shows 'kubelet_client_test.go' exists, but without viewing the actual test content, it's unclear if all security-relevant paths in 'kubelet_client.go' are covered, particularly around TLS certificate validation and authentication. Fix: Ensure comprehensive test coverage (>90%) for kubelet client configuration, particularly: TLS certificate validation, hostname verification, authentication methods, and error handling for invalid credentials.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.