Popeye — Kubernetes Cluster Sanitizer

What it is

Popeye is a command-line utility that scans a live Kubernetes cluster and reports potential issues with deployed resources. It checks for misconfigurations, unused resources, port mismatches, dead references, and violations of best practices. Think of it as a linter for your running cluster rather than for your YAML files.

Popeye targets Kubernetes operators, SREs, and DevOps engineers who want a quick health check of their clusters without setting up a full policy engine like OPA or Kyverno.

How it saves time or tokens

Popeye runs a comprehensive scan in seconds and produces a color-coded report that highlights issues by severity. Instead of manually inspecting each namespace, deployment, and service for problems, you get an immediate overview of what needs attention. This is especially valuable after cluster upgrades, migrations, or when onboarding a new team to an inherited cluster.

For AI-assisted operations, Popeye's structured output (JSON, YAML, or HTML) can be fed to an LLM for automated triage and remediation suggestions.

How to use

1. Install Popeye: brew install derailed/popeye/popeye on macOS, or download the binary from GitHub releases. It uses your current kubeconfig context.
2. Run popeye to scan all namespaces. Use popeye -n my-namespace to scope the scan to a specific namespace.
3. Review the report. Each resource gets a grade (OK, Info, Warning, Error). Focus on Error and Warning items first.

Example

# Scan the entire cluster
$ popeye

# Output (abbreviated):
# GENERAL [B]
#   Connectivity...................OK
#   k8s Version....................OK
#
# DEPLOYMENTS (default) [C]
#   web-api
#     Container web-api
#       [W] No resource limits defined
#       [W] No liveness probe defined
#       [I] No readiness probe defined
#
# SERVICES (default) [A]
#   web-api-svc....................OK

# Export as JSON for programmatic analysis
$ popeye -o json > cluster-report.json

The letter grades (A through F) give you an instant sense of cluster health at a glance.

Related on TokRepo

• DevOps tools — Tools for infrastructure management and operations
• Monitoring tools — Observability and alerting solutions

Common pitfalls

• Popeye needs read access to cluster resources. Ensure your kubeconfig has sufficient RBAC permissions for the namespaces you want to scan.
• Some warnings are intentional in your environment (e.g., no resource limits on development namespaces). Use a Spinach configuration file to suppress known false positives.
• Popeye scans the live cluster state, not your YAML manifests. It catches runtime issues that static analysis tools miss, but does not replace pre-deploy validation.