Skip to content
🧭 A Kubernetes cluster resource sanitizer
Branch: master
Clone or download
Latest commit c143333 Apr 17, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
change_logs beef up test + docker builds Apr 17, 2019
cmd beef up test + docker builds Apr 17, 2019
pkg beef up test + docker builds Apr 17, 2019
.dockerignore beef up test + docker builds Apr 17, 2019
.goreleaser.yml rework report formats + added res Apr 17, 2019
LICENSE add licence + fix typos Apr 5, 2019

Popeye - A Kubernetes Cluster Sanitizer

Popeye is a utility that cruises Kubernetes cluster resources and reports potential issues with your deployment manifests and configurations. By scanning your clusters, it detects misconfigurations and ensure best practices are in place thus preventing potential future headaches. It aims at reducing the cognitive overload one faces when managing and operating a Kubernetes cluster in the wild. Popeye is a readonly tool, it does not change or update any of your Kubernetes resources or configurations in any way!

Go Report Card Build Status release Get it from the Snap Store


Popeye is available on Linux, OSX and Windows platforms.

  • Binaries for Linux, Windows and Mac are available as tarballs in the release page or via the SnapCraft link above.

  • For OSX using Homebrew

    brew tap derailed/popeye && brew install popeye
  • Building from source Popeye was built using go 1.12+. In order to build Popeye from source you must:

    1. Clone the repo

    2. Set env var GO111MODULE=on

    3. Add the following command in your go.mod file

      replace ( => MY_POPEYE_CLONED_GIT_REPO
    4. Build and run the executable

      go run main.go


Popeye scans your cluster for best practices and potential issues. Currently, Popeye only looks at nodes, namespaces, pods and services. More will come soon! We are hoping Kubernetes friends will pitch'in to make Popeye even better.

The aim of the sanitizers is to pick up on misconfigurations ie things like ports mismatch, dead or unused resources, metrics utilization, probes, container images, RBAC rules, naked resources, etc...

Popeye is not another static analysis tool. It runs and inspect Kubernetes resources on live clusters and sanitize resources as they are in the wild!

Here is a list of sanitizers in place for the current release.

Resource Sanitizers Section
πŸ›€ Node no
Conditions ie not ready, out of mem/disk, network, pids, etc
Pod tolerations referencing node taints
CPU/MEM utilization metrics, trips if over limits (default 80% CPU/MEM)
πŸ›€ Namespace ns
Dead namespaces
πŸ›€ Pod po
Pod status
Containers statuses
ServiceAccount presence
CPU/MEM on containers over a set CPU/MEM limit (default 80% CPU/MEM)
Container image with no tags
Container image using latest tag
Resources request/limits presence
Probes liveness/readiness presence
Named ports and their references
πŸ›€ Service svc
Endpoints presence
Matching pods labels
Named ports and their references
πŸ›€ ServiceAccount sa
Unused, detects potentially unused SAs
πŸ›€ Secrets sec
Unused, detects potentially unused secrets or associated keys
πŸ›€ ConfigMap cm
Unused, detects potentially unused cm or associated keys
πŸ›€ Deployment dp
Unused, pod template validation, resource utilization
πŸ›€ StatefulSet sts
Unsed, pod template validation, resource utilization
πŸ›€ PersistentVolume pv
Unused, check volume bound or volume error
πŸ›€ PersistentVolumeClaim pvc
Unused, check bounded or volume mount error
πŸ›€ HorizontalPodAutoscaler hpa
Unused, Utilization, Max burst checks

The Command Line

You can use Popeye standalone or using a spinach yaml config to tune the sanitizer. Details about the Popeye configuration file are below.

# Dump version info
popeye version
# Popeye a cluster using your current kubeconfig environment.
# Popeye uses a spinach config file of course! aka spinachyaml!
popeye -f spinach.yml
# Popeye a cluster using a kubeconfig context.
popeye --context olive
# Stuck?
popeye help


Cluster D Score

Cluster A Score

The SpinachYAML Configuration

NOTE: This file will change as Popeye matures!

# A Popeye sample configuration file
  # Checks allocations and trip report based on over or under allocations for CPU and Memory.
      over: 100
      under: 50
      over: 100
      under: 50

  # Configure node resources.
    # Limits set a cpu/mem threshold in % ie if cpu|mem > limit a lint warning is triggered.
      # CPU checks if current CPU utilization on a node is greater than 90%.
      cpu:    90
      # Memory checks if current Memory utilization on a node is greater than 80%.
      memory: 80
    # Exclude lists node names to exclude from the scan.
    - master

  # Configure namespace resources
    # Exclude list out namespaces to be excluded from the scan.
      - kube-system
      - kube-public

  # Configure pod resources
    # Restarts check the restarts count and triggers a lint warning if above threshold.
    # Check container resource utilization in percent.
    # Issues a lint warning if about these threshold.
      cpu:    80
      memory: 75

  # Service ...
    # Excludes these services from the scan.
      - default/kubernetes
      - blee-ns/fred

Report Morphology

The sanitizer report outputs each resource group scanned and their potential issues. The report is color/emoji coded in term of Sanitizer severity levels:

Level Icon Text Color Description
Ok βœ… OK Green Happy!
Info πŸ”Š I BlueGreen FYI
Warn 😱 W Yellow Potential Issue
Error πŸ’₯ E Red Action required

The heading section for each Kubenertes resource scanned, provides an issue rollup summary count for each of the categories above.

The Summary section provides a Popeye Score based on the sanitization pass on the given cluster.

Supported Resources

This initial drop only supports a handful of resources. More will be added soon...

  • Node
  • Namespace
  • Pod
  • Service

Known Issues

This initial drop is brittle. Popeye will most likely blow up...

  • You're running older versions of Kubernetes. Popeye works best Kubernetes 1.13+.
  • You don't have enough RBAC fu to manage your cluster (see RBAC section below)
  • Your cluster does not run a metric server.


In order for Popeye to do his work, the signed in user must have enough oomph to get/list the resources mentioned above as well as metrics-server get/list access.


This is work in progress! If there is enough interest in the Kubernetes community, we will enhance per your recommendations/contributions. Also if you dig this effort, please let us know that too!

ATTA Girls/Boys!

Popeye sits on top of many of opensource projects and libraries. Our sincere appreciations to all the OSS contributors that work nights and weekends to make this project a reality!

Contact Info

  1. Email:
  2. Twitter: @kitesurfer

Β© 2019 Imhotep Software LLC. All materials licensed under Apache v2.0

You can’t perform that action at this time.