# Popeye — Kubernetes Cluster Sanitizer

> Scan your live Kubernetes cluster for resource issues, misconfigurations, and best practice violations. Popeye reports problems before they become outages.

## Install

Save as a script file and run:

# Popeye — Kubernetes Cluster Sanitizer

## Quick Use
```bash
brew install derailed/popeye/popeye
popeye
# Or run in-cluster:
kubectl run popeye --image=derailed/popeye --restart=Never -- -o json
```

## Introduction
Popeye is a read-only Kubernetes cluster sanitizer that scans live resources for potential issues. Unlike static analysis tools that check YAML files, Popeye inspects the running state of your cluster and flags unused resources, misconfigured pods, over-provisioned workloads, and security concerns.

## What Popeye Does
- Scans live cluster resources including pods, services, nodes, and RBAC objects
- Detects unused ConfigMaps, Secrets, PVCs, and service accounts
- Flags missing resource limits, liveness probes, and security contexts
- Reports over-allocated CPU and memory based on actual usage versus requests
- Outputs results as text, JSON, HTML, or Prometheus metrics

## Architecture Overview
Popeye is a Go binary that connects to the Kubernetes API server using your kubeconfig. It runs a set of linters, one per resource kind, that query the live state of the cluster. Each linter applies a series of checks and assigns severity levels (OK, Info, Warn, Error) to findings. Results are aggregated into a cluster-wide health score and rendered in the chosen output format.

## Self-Hosting & Configuration
- Install via Homebrew, Go install, or pull the Docker image for in-cluster use
- Point at any cluster by setting KUBECONFIG or using --context flag
- Create a spinach.yaml to customize severity levels, exclusions, and thresholds
- Filter scans by namespace with -n or by resource type with specific subcommands
- Export Prometheus metrics for continuous cluster health monitoring

## Key Features
- Live cluster scanning that catches runtime issues static analysis misses
- Detects unused and orphaned resources wasting cluster capacity
- Over-allocation detection by comparing requests and limits to actual usage
- Customizable severity tuning and resource exclusions via spinach.yaml
- Built by the same developer behind k9s, with a focus on operator productivity

## Comparison with Similar Tools
- **k9s** — Interactive cluster management TUI; Popeye is a batch scanner focused on audit reports
- **Kubescape** — Security-focused scanning with NSA/CISA frameworks; Popeye covers broader operational hygiene
- **Polaris** — Checks manifests and running resources for best practices; Popeye adds unused-resource detection and over-allocation analysis
- **kube-score** — Static manifest linter; Popeye scans the live cluster state

## FAQ
**Q: Does Popeye modify anything in the cluster?**
A: No. Popeye is strictly read-only. It queries the API server but never creates, updates, or deletes resources.

**Q: Can I run Popeye in CI/CD?**
A: Yes. Point it at a staging cluster and use the JSON or JUnit output format to fail pipelines on critical findings.

**Q: How does it detect unused resources?**
A: Popeye cross-references ConfigMaps, Secrets, and PVCs against all pod specs in the cluster. Resources not referenced by any workload are flagged.

**Q: What is the spinach.yaml file?**
A: It is the configuration file where you can exclude namespaces, resources, or specific checks and adjust severity thresholds.

## Sources
- https://github.com/derailed/popeye
- https://popeyecli.io

---
Source: https://tokrepo.com/en/workflows/b6253af9-3974-11f1-9bc6-00163e2b0d79
Author: Script Depot