
👀 Ein Kubernetes-Cluster-Ressourcen-Sanitizer
Popeye ist ein Dienstprogramm, das Live-Kubernetes-Cluster scannt und potenzielle Probleme mit bereitgestellten Ressourcen und Konfigurationen meldet. Da die Kubernetes-Landschaft wächst, wird es für einen Menschen zunehmend schwierig, die Vielzahl von Manifests und Richtlinien zu verfolgen, die einen Cluster orchestrieren. Popeye scannt Ihren Cluster basierend auf dem, was bereitgestellt ist, und nicht auf dem, was auf der Festplatte liegt. Durch Linting Ihres Clusters erkennt es Fehlkonfigurationen, veraltete Ressourcen und hilft Ihnen sicherzustellen, dass Best Practices eingehalten werden, um so zukünftige Probleme zu vermeiden. Es zielt darauf ab, die kognitive Überlastung zu reduzieren, die beim Betrieb eines Kubernetes-Clusters in der Praxis auftritt. Darüber hinaus meldet es, wenn Ihr Cluster einen Metric-Server verwendet, potenzielle Über-/Unterauslastungen von Ressourcen und warnt Sie, falls Ihr Cluster an seine Kapazitätsgrenzen stößt.
Popeye ist ein reines Lesetool, es verändert in keiner Weise Ihre Kubernetes-Ressourcen!
Sie können den Scan-Bericht als HTML ausgeben.
Popeye veröffentlicht Prometheus-Metriken. Wir haben in diesem Repository ein Beispiel-Dashboard für Popeye bereitgestellt, um Ihnen den Einstieg zu erleichtern.
Popeye ist auf Linux-, OS X- und Windows-Plattformen verfügbar.
Binärdateien für Linux, Windows und Mac sind als Tarballs auf der Release-Seite verfügbar.
Für OS X/Unix mit Homebrew/LinuxBrew ```shell brew install derailed/popeye/popeye
Verwendung von go install
go install github.com/derailed/popeye@latest
Erstellung aus dem Quellcode Popeye wurde mit go 1.21+ erstellt. Um Popeye aus dem Quellcode zu erstellen, müssen Sie:
Klonen Sie das Repository
Fügen Sie den folgenden Befehl in Ihre go.mod-Datei ein
replace (
github.com/derailed/popeye => MY_POPEYE_CLONED_GIT_REPO
)
Erstellen und führen Sie die ausführbare Datei aus
go run main.go
Kurzanleitung für Ungeduldige: ```shell
git clone https://github.com/derailed/popeye cd popeye
make build
popeye
Popeye verwendet den 256-Farben-Terminalmodus. Stellen Sie unter `Nix-Systemen sicher, dass TERM entsprechend gesetzt ist.
export TERM=xterm-256color
Sie können Popeye im offenen Modus oder mit einer Spinat-YAML-Konfiguration verwenden, um Ihre Linter abzustimmen. Details zur Popeye-Konfigurationsdatei finden Sie unten.```shell
popeye version
popeye
fred namespacepopeye -n fred
popeye -A
popeye -f spinach.yaml
popeye --context olive
popeye -n ns1 -s pod,svc --logs none
popeye -n ns1 --logs /tmp/fred.log -v4
popeye help
---
## Linters
Popeye scannt Ihren Cluster auf Best Practices und potenzielle Probleme.
Derzeit sucht Popeye nur nach einem bestimmten Satz kuratierter Kubernetes-Ressourcen.
Weitere werden bald hinzugefügt!
Wir hoffen, dass Kubernetes-Freunde mithelfen, Popeye noch besser zu machen.
Das Ziel der Linters ist es, Fehlkonfigurationen aufzuspüren, wie z. B.
Portkonflikte, tote oder ungenutzte Ressourcen, Metriknutzung,
Probes, Container-Images, RBAC-Regeln, nackte Ressourcen usw.
Popeye ist kein weiteres statisches Analysetool. Es läuft und überprüft Kubernetes-Ressourcen in
Live-Clustern und lintet Ressourcen so, wie sie in freier Wildbahn vorkommen!
Hier ist eine Liste einiger verfügbarer Linters:
| | Ressource | Linters | Aliase |
|----|--------------------------|-------------------------------------------------------------------------|------------|
| 🛀 | Node | | no |
| | | Bedingungen z. B. nicht bereit, wenig Speicher/Platte, Netzwerk, PIDs | |
| | | Pod-Tolerierungen, die auf Node-Taints verweisen | |
| | | CPU/MEM-Auslastungsmetriken, schlägt an, wenn über Grenzen (Standard 80% CPU/MEM) | |
| 🛀 | Namespace | | ns |
| | | Inaktiv | |
| | | Tote Namespaces | |
| 🛀 | Pod | | po |
| | | Pod-Status | |
| | | Container-Status | |
| | | ServiceAccount-Vorhandensein | |
| | | CPU/MEM auf Containern über einem festgelegten CPU/MEM-Limit (Standard 80% CPU/MEM) | |
| | | Container-Image ohne Tags | |
| | | Container-Image mit `latest`-Tag | |
| | | Vorhandensein von Ressourcenanfragen/-limits | |
| | | Vorhandensein von Liveness-/Readiness-Probes | |
| | | Benannte Ports und deren Referenzen | |
| 🛀 | Service | | svc |
| | | Vorhandensein von Endpoints | |
| | | Übereinstimmende Pod-Labels | |
| | | Benannte Ports und deren Referenzen | |
| 🛀 | ServiceAccount | | sa |
| | | Unbenutzt, erkennt potenziell ungenutzte SAs | |
| 🛀 | Secrets | | sec |
| | | Unbenutzt, erkennt potenziell ungenutzte Secrets oder zugehörige Keys | |
| 🛀 | ConfigMap | | cm |
| | | Unbenutzt, erkennt potenziell ungenutzte CMs oder zugehörige Keys | |
| 🛀 | Deployment | | dp, deploy |
| | | Unbenutzt, Pod-Template-Validierung, Ressourcennutzung | |
| 🛀 | StatefulSet | | sts |
| | | Unbenutzt, Pod-Template-Validierung, Ressourcennutzung | |
| 🛀 | DaemonSet | | ds |
| | | Unbenutzt, Pod-Template-Validierung, Ressourcennutzung | |
| 🛀 | PersistentVolume | | pv |
| | | Unbenutzt, prüft Volume-Bindung oder Volume-Fehler | |
| 🛀 | PersistentVolumeClaim | | pvc |
| | | Unbenutzt, prüft Bindung oder Volume-Mount-Fehler | |
| 🛀 | HorizontalPodAutoscaler | | hpa |
| | | Unbenutzt, Auslastung, Max-Burst-Prüfungen | |
| 🛀 | PodDisruptionBudget | | |
| | | Unbenutzt, prüft minAvailable-Konfiguration | pdb |
| 🛀 | ClusterRole | | |
| | | Unbenutzt | cr |
| 🛀 | ClusterRoleBinding | | |
| | | Unbenutzt | crb |
| 🛀 | Role | | |
| | | Unbenutzt | ro |
| 🛀 | RoleBinding | | |
| | | Unbenutzt | rb |
| 🛀 | Ingress | | |
| | | Gültig | ing |
| 🛀 | NetworkPolicy | | |
| | | Gültig, Veraltet, Bewacht | np |
| 🛀 | PodSecurityPolicy | | |
| | | Gültig | psp |
| 🛀 | Cronjob | | |
| | | Gültig, Pausiert, Läuft | cj |
| 🛀 | Job | | |
| | | Pod-Prüfungen | job |
| 🛀 | GatewayClass | | |
| | | Gültig, Unbenutzt | gwc |
| 🛀 | Gateway | | |
| | | Gültig, Unbenutzt | gw |
| 🛀 | HTTPRoute | | |
| | | Gültig, Unbenutzt | gwr |
Siehe auch die [vollständige Liste der Codes](https://github.com/derailed/popeye/blob/master/docs/codes.md)
---
## Scans speichern
Um den Popeye-Bericht in einer Datei zu speichern, übergeben Sie das `--save`-Flag an den Befehl.
Standardmäßig wird ein tmp-Verzeichnis erstellt und der Scan-Bericht dort gespeichert.
Der Pfad des tmp-Verzeichnisses wird auf STDOUT ausgegeben.
Wenn Sie das Ausgabeverzeichnis für den Bericht angeben möchten,
können Sie die Umgebungsvariable `POPEYE_REPORT_DIR` verwenden. Der endgültige Pfad ist <POPEYE_REPORT_DIR>/<cluster>/<context>.
Standardmäßig folgt der Name der Ausgabedatei diesem Format: `lint_<cluster-name>_<time-UnixNano>.<output-extension>` (z. B. "lint-mycluster-1594019782530851873.html").
Wenn Sie auch den Ausgabedateinamen für den Bericht angeben möchten, können Sie das `--output-file`-Flag mit dem gewünschten Dateinamen als Parameter übergeben.
Beispiel zum Speichern des Berichts im aktuellen Arbeitsverzeichnis:```shell
POPEYE_REPORT_DIR=$(pwd) popeye --save
Beispiel zum Speichern des Berichts im Arbeitsverzeichnis im HTML-Format unter dem Namen "report.html" :```shell POPEYE_REPORT_DIR=$(pwd) popeye --save --out html --output-file report.html
### In S3-Objektspeicher speichern
Alternativ können Sie die generierten Berichte in einen AWS S3- oder Minio-Objektspeicher hochladen, indem Sie das Flag `--s3-bucket` angeben.
Für die Parameter müssen Sie den Namen des S3-Buckets angeben, in dem Sie den Bericht speichern möchten.
Um den Bericht in einem Unterverzeichnis des Buckets zu speichern, geben Sie den Bucket-Parameter als `bucket/path/to/report` an.
Beispiel zum Speichern des Berichts in S3:```shell
# AWS S3
# NOTE: You must provide env vars for AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
# This will create bucket my-popeye if not present and upload a popeye json report to /fred/scan.json
popeye --s3-bucket s3://my-popeye/fred --s3-region us-west-2 --out json --save --output-file scan.json
# Minio Object Store
# NOTE: You must provide env vars for AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY and a minio server URI
# This will create bucket my-popeye if not present and upload a popeye json report to /fred/scan.json
popeye --s3-bucket minio://my-popeye/fred --s3-region us-east --s3-endpoint localhost:9000 --out json --save --output-file scan.json
Sie können Popeye auch in einem Container ausführen, indem Sie es direkt aus dem offiziellen Docker-Repository auf Quay starten.
Der Standardbefehl beim Ausführen des Docker-Containers ist popeye, sodass Sie den Scan durch die Verwendung der unterstützten CLI-Flags anpassen können.
Um auf Ihre Cluster zuzugreifen, binden Sie Ihr lokales kubeconfig-Verzeichnis mit -v in den Container ein:```shell
docker run --rm -it -v $HOME/.kube:/root/.kube quay.io/derailed/popeye --context foo -n bar
Wenn Sie den obigen Docker-Befehl mit `--rm` ausführen, wird der Container gelöscht, wenn Popeye beendet wird.
Wenn Sie `--save` verwenden, wird die Ausgabe nach /tmp im Container geschrieben und dann der Container gelöscht, wenn Popeye beendet wird, was bedeutet, dass Sie die Ausgabe verlieren ;(
Um dies zu umgehen, mounten Sie /tmp auf das /tmp des Containers.
> HINWEIS: Sie können den Standardspeicherort des Ausgabeverzeichnisses überschreiben, indem Sie die Umgebungsvariable `POPEYE_REPORT_DIR` setzen.```shell
docker run --rm -it \
-v $HOME/.kube:/root/.kube \
-e POPEYE_REPORT_DIR=/tmp/popeye \
-v /tmp:/tmp \
quay.io/derailed/popeye --context foo -n bar --save --output-file my_report.txt
# Docker has exited, and the container has been deleted, but the file
# is in your /tmp directory because you mapped it into the container
cat /tmp/popeye/my_report.txt
<snip>
Popeye kann Linter-Berichte in verschiedenen Formaten erstellen. Sie können die Option -o verwenden und Ihr Gift auswählen.
Popeye kann Prometheus-Metriken direkt aus einem Scan veröffentlichen. Dazu benötigen Sie Zugriff auf einen Prometheus-Pushgateway und die entsprechenden Anmeldedaten.
HINWEIS! Diese können sich basierend auf dem Feedback und der Nutzung der Benutzer ändern!!
Um Metriken zu veröffentlichen, müssen zusätzliche CLI-Argumente vorhanden sein.```shell
popeye --push-gtwy-url http://localhost:9091
popeye -o html --save --push-gtwy-url http://localhost:9091
### PopProm Metriken
Die folgenden Popeye-Prometheus-Metriken werden veröffentlicht:
* `popeye_severity_total` [gauge] verfolgt verschiedene Zählungen basierend auf dem Schweregrad.
* `popeye_code_total` [gauge] verfolgt Zählungen nach Popeyes Linter-Codes.
* `popeye_linter_tally_total` [gauge] verfolgt Zählungen pro Linter.
* `popeye_report_errors_total` [gauge] verfolgt Gesamtzahlen von Scan-Fehlern.
* `popeye_cluster_score` [gauge] verfolgt Bewertungen der Scan-Berichte.
### PopGraf
Ein Beispiel-Dashboard für [Grafana](https://grafana.com) findest du in diesem Repository, um loszulegen.
> HINWEIS! In Arbeit, bitte zögere nicht, beizutragen, wenn du UX/Grafana/PromQL-Kenntnisse hast.
---
## SpinachYAML
Eine Spinach-YAML-Konfigurationsdatei kann über die Option `-f` angegeben werden, um die Linter weiter zu konfigurieren. Diese Datei kann den Container-Auslastungsschwellenwert und spezifische Linter-Konfigurationen sowie Ressourcen und Codes angeben, die vom Linter ausgeschlossen werden sollen.
> HINWEIS! Diese Datei wird sich ändern, sobald Popeye ausgereift ist!
Unter dem Schlüssel `excludes` kannst du konfigurieren, bestimmte Ressourcen oder Linter-Codes zu überspringen.
Popeyes Linter sind nach den k8s-Ressourcennamen benannt.
Zum Beispiel heißt der PodDisruptionBudget-Linter `poddisruptionbudgets` und scannt `policy/v1/poddisruptionbudgets`
> HINWEIS! Der Linter verwendet die Pluralform des Ressourcen-`kind` und alles wird in Kleinbuchstaben geschrieben.
Ein vollqualifizierter Ressourcenname, auch `FQN` genannt, wird in der Spinach-Datei verwendet, um einen Ressourcennamen zu identifizieren, z.B. `namespace/resource_name`.
Zum Beispiel ist der FQN eines Pods namens `fred-1234` im Namespace `blee` `blee/fred-1234`. Dies ermöglicht die Unterscheidung von `fred/p1` und `blee/p1`.
Für clusterweite Ressourcen entspricht der FQN dem Namen.
Ausschlussregeln können entweder ein direkter String-Vergleich oder ein regulärer Ausdruck sein. Im letzteren Fall muss der reguläre Ausdruck über das Präfix `rx:` angegeben werden.
> HINWEIS! Sei vorsichtig mit deinem Regex, da bei einer *lockeren* Regex-Regel mehr Ressourcen als erwartet vom Bericht ausgeschlossen werden könnten.
> Wenn sich deine Cluster-Ressourcen ändern, könnte dies zu suboptimalen Scans führen.
> Daher empfehlen wir, Popeye hin und wieder `weit offen` laufen zu lassen, um sicherzustellen, dass du alle neuen Probleme bemerkst, die in deinen Clustern aufgetreten sein könnten…
Hier ist eine Beispiel-Spinach-Datei, wie sie in dieser Version existiert.
Es gibt eine umfassendere auf EKS und AKS basierende Spinach-Datei in diesem Repository unter `spinach`.
(Übrigens: Für Neulinge im Projekt könnte es eine großartige Möglichkeit sein, beizutragen, indem sie clusterspezifische Spinach-Datei-PRs hinzufügen...)```yaml
# spinach.yaml
# A Popeye sample configuration file
popeye:
# Checks resources against reported metrics usage.
# If over/under these thresholds a linter warning will be issued.
# Your cluster must run a metrics-server for these to take place!
allocations:
cpu:
underPercUtilization: 200 # Checks if cpu is under allocated by more than 200% at current load.
overPercUtilization: 50 # Checks if cpu is over allocated by more than 50% at current load.
memory:
underPercUtilization: 200 # Checks if mem is under allocated by more than 200% at current load.
overPercUtilization: 50 # Checks if mem is over allocated by more than 50% usage at current load.
# Excludes excludes certain resources from Popeye scans
excludes:
# [NEW!] Global exclude resources and codes globally of any linters.
global:
fqns: [rx:^kube-] # => excludes all resources in kube-system, kube-public, etc..
# [NEW!] Exclude resources for all linters matching these labels
labels:
app: [bozo, bono] #=> exclude any resources with labels matching either app=bozo or app=bono
# [NEW!] Exclude resources for all linters matching these annotations
annotations:
fred: [blee, duh] # => exclude any resources with annotations matching either fred=blee or fred=duh
# [NEW!] Exclude scan codes globally via straight codes or regex!
codes: ["300", "206", "rx:^41"] # => exclude issue codes 300, 206, 410, 415 (Note: regex match!)
# [NEW!] Configure individual resource linters
linters:
# Configure the namespaces linter for v1/namespaces
namespaces:
# [NEW!] Exclude these codes for all namespace resources straight up or via regex.
codes: ["100", "rx:^22"] # => exclude codes 100, 220, 225, ...
# [NEW!] Excludes specific namespaces from the scan
instances:
- fqns: [kube-public, kube-system] # => skip ns kube-pulbic and kube-system
- fqns: [blee-ns]
codes: [106] # => skip code 106 for namespace blee-ns
# Skip secrets in namespace bozo.
secrets:
instances:
- fqns: [rx:^bozo]
# Configure the pods linter for v1/pods.
pods:
instances:
# [NEW!] exclude all pods matching these labels.
- labels:
app: [fred,blee] # Exclude codes 102, 105 for any pods with labels app=fred or app=blee
codes: [102, 105]
resources:
# Configure node resources.
node:
# Limits set a cpu/mem threshold in % ie if cpu|mem > limit a lint warning is triggered.
limits:
# 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
# Configure pod resources
pod:
# Restarts check the restarts count and triggers a lint warning if above threshold.
restarts: 3
# Check container resource utilization in percent.
# Issues a lint warning if about these threshold.
limits:
cpu: 80
memory: 75
# [New!] overrides code severity
overrides:
# Code specifies a custom severity level ie critical=3, warn=2, info=1
- code: 206
severity: 1
# Configure a list of allowed registries to pull images from.
# Any resources not using the following registries will be flagged!
registries:
- quay.io
- docker.io
Popeye ist containerisiert und kann direkt in Ihren Kubernetes-Clustern als einmaliger Job oder CronJob ausgeführt werden.
Hier ist ein Beispiel-Setup, bitte passen Sie es nach Ihren Bedürfnissen/Wünschen an. Die Manifests hierfür befinden sich im k8s-Verzeichnis in diesem Repository.```shell kubectl apply -f k8s/popeye
INPUT:```yaml
---
apiVersion: v1
kind: Namespace
metadata:
name: popeye
---
apiVersion: batch/v1
kind: CronJob
metadata:
name: popeye
namespace: popeye
spec:
schedule: "* */1 * * *" # Fire off Popeye once an hour
concurrencyPolicy: Forbid
jobTemplate:
spec:
template:
spec:
serviceAccountName: popeye
restartPolicy: Never
containers:
- name: popeye
image: derailed/popeye:vX.Y.Z
imagePullPolicy: IfNotPresent
args:
- -o
- yaml
- --force-exit-zero
resources:
limits:
cpu: 500m
memory: 100Mi
Das Flag --force-exit-zero sollte gesetzt sein. Andernfalls landen die Pods in einem Fehlerzustand.
HINWEIS! Popeye beendet sich mit einem Fehlercode ungleich null, wenn Lint-Fehler erkannt werden.
Damit Popeye seine Arbeit verrichten kann, muss der angemeldete Benutzer über ausreichend RBAC-Power verfügen, um die oben genannten Ressourcen abzurufen/aufzulisten.
Beispiel-Popeye-RBAC-Regeln (beachten Sie, dass diese Änderungen unterliegen.)
HINWEIS! Bitte überprüfen und an Ihre Cluster-Richtlinien anpassen.```yaml
apiVersion: v1 kind: ServiceAccount metadata: name: popeye namespace: popeye
apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: name: popeye rules:
apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRoleBinding metadata: name: popeye subjects:
---
## Aufbau des Berichts
Der Lint-Bericht gibt jede gescannte Ressourcengruppe und deren potenzielle Probleme aus.
Der Bericht ist farblich/emojicodiert nach den Schweregraden des Linters:
| Stufe | Symbol | Jurassic | Farbe | Beschreibung |
|-------|--------|----------|-----------|-----------------------|
| Ok | ✅ | OK | Grün | Alles klar! |
| Info | 🔊 | I | Blaugrün | Zur Info |
| Warn | 😱 | W | Gelb | Mögliches Problem |
| Error | 💥 | E | Rot | Handlung erforderlich |
Der Kopfbereich für jede gescannte Kubernetes-Ressource liefert eine zusammenfassende Anzahl
für jede der obigen Kategorien.
Der Abschnitt Zusammenfassung liefert einen **Popeye-Score** basierend auf dem Linter-Durchlauf
für den angegebenen Cluster.
---
## Bekannte Probleme
Diese erste Version ist instabil. Popeye wird höchstwahrscheinlich explodieren, wenn…
* Sie ältere Versionen von Kubernetes ausführen. Popeye funktioniert am besten mit Kubernetes 1.25.X.
* Sie nicht genügend RBAC-Power haben, um Ihren Cluster zu verwalten (siehe RBAC-Abschnitt)
---
## Haftungsausschluss
Dies ist noch in Arbeit! Wenn genügend Interesse in der Kubernetes-Community besteht,
werden wir gemäß Ihren Empfehlungen/Beiträgen verbessern.
Auch wenn Ihnen diese Arbeit gefällt, lassen Sie es uns bitte ebenfalls wissen!
---
## ATTA Girls/Boys!
Popeye baut auf vielen Open-Source-Projekten und -Bibliotheken auf. Unser *aufrichtiger* Dank
gilt allen OSS-Mitwirkenden, die nachts und an Wochenenden arbeiten, um dieses Projekt
Wirklichkeit werden zu lassen!
### Kontaktinformationen
1. **Email**: [email protected]
2. **Twitter**: [@kitesurfer](https://twitter.com/kitesurfer?lang=en)
---
<img src="https://raw.githubusercontent.com/derailed/popeye/master/assets/imhotep_logo.png" width="32" height="auto"/> © 2025 Imhotep Software LLC.
Alle Materialien lizenziert unter [Apache v2.0](http://www.apache.org/licenses/LICENSE-2.0)
| Format | Beschreibung | Standard | Credits |
|---|
| standard | Die volle Ausgabe mit Icons und Farben | ja | |
| jurassic | Keine Icons oder Farben wie im Jahr 1979 | ||
| yaml | Als YAML | ||
| html | Als HTML | ||
| json | Als JSON | ||
| junit | Für die melancholischen Java-Entwickler | ||
| prometheus | Gibt einen Bericht als Prometheus-Metriken aus | dardanel | |
| score | Gibt einen einzelnen Cluster-Linter-Score-Wert (0-100) zurück | kabute |