Popeye is a readonly tool, it does not alter any of your Kubernetes resources in any way!
Popeye is available on Linux, OSX and Windows platforms.
For OSX/Unit using Homebrew/LinuxBrew
Building from source Popeye was built using go 1.12+. In order to build Popeye from source you must:
Clone the repo
Add the following command in your go.mod file
Build and run the executable
Quick recipe for the impatient:
Popeye uses 256 colors terminal mode. On `Nix system make sure TERM is set accordingly.
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, i.e. things like port mismatches, dead or unused resources, metrics utilization, probes, container images, RBAC rules, naked resources, etc…
Here is a list of some of the available sanitizers:
To save the Popeye report to a file pass the
--save flag to the command. By default it will create a temp directory and will store the report there, the path of the temp directory will be printed out on STDOUT. If you have the need to specify the output directory for the report, you can use the environment variable
POPEYE_REPORT_DIR. By default, the name of the output file follow the following format :
sanitizer_<cluster-name>_<time-UnixNano>.<output-extension> (e.g. : “sanitizer-mycluster-1594019782530851873.html”). If you have the need to specify the output file name for the report, you can pass the
--output-file flag with the filename you want as parameter.
Example to save report in working directory:
Example to save report in working directory in HTML format under the name “report.html” :
You can also save the generated report to an AWS S3 bucket (or another S3 compatible Object Storage) with providing the flag
--s3-bucket. As parameter you need to provide the name of the S3 bucket where you want to store the report. To save the report in a bucket subdirectory provide the bucket parameter as
Example to save report to S3:
If AWS sS3 is not your bag, you can further define an S3 compatible storage (OVHcloud Object Storage, Minio, Google cloud storage, etc…) using s3-endpoint and s3-region as so:
You don’t have to build and/or install the binary to run popeye: you can just run it directly from the official docker repo on DockerHub. The default command when you run the docker container is
popeye, so you just need to pass whatever cli args are normally passed to popeye. To access your clusters, map your local kube config directory into the container with
Running the above docker command with
--rm means that the container gets deleted when popeye exits. When you use
--save, it will write it to /tmp in the container and then delete the container when popeye exits, which means you lose the output. To get around this, map /tmp to the container’s /tmp. NOTE: You can override the default output directory location by setting
POPEYE_REPORT_DIR env variable.
You can use Popeye standalone or using a spinach yaml config to tune the sanitizer. Details about the Popeye configuration file are below.
Popeye can generate sanitizer reports in a variety of formats. You can use the -o cli option and pick your poison from there.
A spinach.yml configuration file can be specified via the
-f option to further configure the sanitizers. This file may specify the container utilization threshold and specific sanitizer configurations as well as resources that will be excluded from the sanitization.
NOTE: This file will change as Popeye matures!
excludes key you can configure to skip certain resources, or certain checks by code. Here, resource types are indicated in a group/version/resource notation. Example: to exclude PodDisruptionBugdets, use the notation
policy/v1/poddisruptionbudgets. Note that the resource name is written in the plural form and everything is spelled in lowercase. For resources without an API group, the group part is omitted (Examples:
A resource is identified by a resource kind and a fully qualified resource name, i.e.
NOTE! Please be careful with your regex as more resources than expected may get excluded from the report with a loose regex rule. When your cluster resources change, this could lead to a sub-optimal sanitization. Once in a while it might be a good idea to run Popeye „configless“ to make sure you will recognize any new issues that may have arisen in your clusters…
Here is an example spinach file as it stands in this release. There is a fuller eks and aks based spinach file in this repo under
spinach. (BTW: for new comers into the project, might be a great way to contribute by adding cluster specific spinach file PRs…)
Alternatively, Popeye is containerized and can be run directly in your Kubernetes clusters as a one-off or CronJob.
Here is a sample setup, please modify per your needs/wants. The manifests for this are in the k8s directory in this repo.
--force-exit-zero should be set to
true. Otherwise, the pods will end up in an error state. Note that popeye exits with a non-zero error code if the report has any errors.
In order for Popeye to do his work, the signed-in user must have enough RBAC oomph to get/list the resources mentioned above.
Sample Popeye RBAC Rules (please note that those are subject to change.)
The sanitizer report outputs each resource group scanned and their potential issues. The report is color/emoji coded in term of Sanitizer severity levels:
The heading section for each scanned Kubernetes resource provides a summary count for each of the categories above.
The Summary section provides a Popeye Score based on the sanitization pass on the given cluster.
This initial drop is brittle. Popeye will most likely blow up when…
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!
Popeye sits on top of many of open source projects and libraries. Our sincere appreciations to all the OSS contributors that work nights and weekends to make this project a reality!