derailed/popeye👀 Un sanificatore di risorse per cluster Kubernetes
Popeye è un'utilità che scansiona cluster Kubernetes live e segnala potenziali problemi con risorse e configurazioni distribuite. Con la crescita del panorama Kubernetes, sta diventando una sfida per un essere umano tenere traccia della marea di manifesti e policy che orchestrano un cluster. Popeye scansiona il tuo cluster in base a ciò che è distribuito e non ciò che è sul disco. Effettuando il linting del tuo cluster, rileva configurazioni errate, risorse obsolete e ti assiste per assicurarti che le best practice siano in atto, prevenendo così futuri mal di testa. Mira a ridurre il sovraccarico cognitivo che si affronta quando si opera un cluster Kubernetes in ambiente reale. Inoltre, se il tuo cluster utilizza un metric-server, segnala potenziali allocazioni eccessive/insufficienti di risorse e tenta di avvisarti nel caso in cui il tuo cluster esaurisca la capacità.
Popeye è uno strumento di sola lettura, non altera in alcun modo le tue risorse Kubernetes!
Puoi esportare il report di scansione in HTML.
Popeye pubblica metriche Prometheus. Abbiamo fornito un dashboard Popeye di esempio per iniziare in questo repository.
Popeye è disponibile su piattaforme Linux, OSX e Windows.
I binari per Linux, Windows e Mac sono disponibili come tarball nella pagina release.
Per OSX/Unit utilizzando Homebrew/LinuxBrew ```shell brew install derailed/popeye/popeye
Usando go install
go install github.com/derailed/popeye@latest
Compilazione dal sorgente Popeye è stato costruito con go 1.21+. Per compilare Popeye dal sorgente devi:
Clonare il repository
Aggiungere il seguente comando nel file go.mod
replace (
github.com/derailed/popeye => MY_POPEYE_CLONED_GIT_REPO
)
Compilare ed eseguire l'eseguibile
go run main.go
Ricetta veloce per gli impazienti: ```shell
git clone https://github.com/derailed/popeye cd popeye
make build
popeye
Popeye utilizza la modalità terminale a 256 colori. Su `Nix sistema assicurati che TERM sia impostato di conseguenza.
export TERM=xterm-256color
Puoi usare Popeye a tutto campo o utilizzando un config yaml spinach per regolare i tuoi linters. I dettagli sul file di configurazione di Popeye sono qui sotto.```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 scansiona il tuo cluster per individuare best practice e potenziali problemi.
Attualmente, Popeye esamina solo un determinato insieme di risorse Kubernetes curate.
Altre arriveranno presto!
Speriamo che gli amici di Kubernetes collaborino per rendere Popeye ancora migliore.
L'obiettivo dei linter è individuare configurazioni errate, come discrepanze di porte, risorse inutilizzate o morte, utilizzo delle metriche, probe, immagini dei container, regole RBAC, risorse nude, ecc...
Popeye non è un altro strumento di analisi statica. Esegue e ispeziona le risorse Kubernetes su cluster live e analizza le risorse così come sono in produzione!
Ecco un elenco di alcuni dei linter disponibili:
| | Resource | Linters | Aliases |
|----|-------------------------|-------------------------------------------------------------------------|------------|
| 🛀 | Node | | no |
| | | Condizioni, ad es. non pronto, memoria/disco esauriti, rete, pids, ecc. | |
| | | Tolleranze dei pod che fanno riferimento ai taint dei nodi | |
| | | Metriche di utilizzo CPU/MEM, scatta se supera i limiti (default 80% CPU/MEM) | |
| 🛀 | Namespace | | ns |
| | | Inattivo | |
| | | Namespace morti | |
| 🛀 | Pod | | po |
| | | Stato del pod | |
| | | Stati dei container | |
| | | Presenza del ServiceAccount | |
| | | CPU/MEM sui container oltre un limite impostato (default 80% CPU/MEM) | |
| | | Immagine del container senza tag | |
| | | Immagine del container che usa il tag `latest` | |
| | | Presenza di richieste/limiti delle risorse | |
| | | Presenza di probe di liveness/readiness | |
| | | Porte nominate e loro riferimenti | |
| 🛀 | Service | | svc |
| | | Presenza di endpoint | |
| | | Etichette dei pod corrispondenti | |
| | | Porte nominate e loro riferimenti | |
| 🛀 | ServiceAccount | | sa |
| | | Inutilizzate, rileva SA potenzialmente inutilizzate | |
| 🛀 | Secrets | | sec |
| | | Inutilizzati, rileva segreti potenzialmente inutilizzati o chiavi associate | |
| 🛀 | ConfigMap | | cm |
| | | Inutilizzate, rileva cm potenzialmente inutilizzate o chiavi associate | |
| 🛀 | Deployment | | dp, deploy |
| | | Inutilizzati, validazione del template del pod, utilizzo delle risorse | |
| 🛀 | StatefulSet | | sts |
| | | Inutilizzati, validazione del template del pod, utilizzo delle risorse | |
| 🛀 | DaemonSet | | ds |
| | | Inutilizzati, validazione del template del pod, utilizzo delle risorse | |
| 🛀 | PersistentVolume | | pv |
| | | Inutilizzato, controlla se il volume è legato o errore di volume | |
| 🛀 | PersistentVolumeClaim | | pvc |
| | | Inutilizzato, controlla se è legato o errore di montaggio volume | |
| 🛀 | HorizontalPodAutoscaler | | hpa |
| | | Inutilizzato, Utilizzo, Controlli Max burst | |
| 🛀 | PodDisruptionBudget | | |
| | | Inutilizzato, Controlla configurazione minAvailable | pdb |
| 🛀 | ClusterRole | | |
| | | Inutilizzato | cr |
| 🛀 | ClusterRoleBinding | | |
| | | Inutilizzato | crb |
| 🛀 | Role | | |
| | | Inutilizzato | ro |
| 🛀 | RoleBinding | | |
| | | Inutilizzato | rb |
| 🛀 | Ingress | | |
| | | Valido | ing |
| 🛀 | NetworkPolicy | | |
| | | Valido, Obsoleto, Protetto | np |
| 🛀 | PodSecurityPolicy | | |
| | | Valido | psp |
| 🛀 | Cronjob | | |
| | | Valido, Sospeso, Esegue | cj |
| 🛀 | Job | | |
| | | Controlli dei pod | job |
| 🛀 | GatewayClass | | |
| | | Valido, Inutilizzato | gwc |
| 🛀 | Gateway | | |
| | | Valido, Inutilizzato | gw |
| 🛀 | HTTPRoute | | |
| | | Valido, Inutilizzato | gwr |
Puoi anche vedere la [lista completa dei codici](https://github.com/derailed/popeye/blob/HEAD/docs/codes.md)
---
## Salvataggio delle scansioni
Per salvare il report di Popeye in un file, passa il flag `--save` al comando.
Di default creerà una directory tmp e memorizzerà il report di scansione lì.
Il percorso della directory tmp verrà stampato su STDOUT.
Se hai bisogno di specificare la directory di output per il report, puoi usare questa variabile d'ambiente `POPEYE_REPORT_DIR`. Il percorso finale sarà <POPEYE_REPORT_DIR>/<cluster>/<context>.
Di default, il nome del file di output segue il seguente formato: `lint_<cluster-name>_<time-UnixNano>.<output-extension>` (ad es.: "lint-mycluster-1594019782530851873.html").
Se vuoi anche specificare il nome del file di output per il report, puoi passare il flag `--output-file` con il nome del file che desideri come parametro.
Esempio per salvare il report nella directory di lavoro:```shell
POPEYE_REPORT_DIR=$(pwd) popeye --save
Esempio per salvare il report nella directory di lavoro in formato HTML con il nome "report.html" :```shell POPEYE_REPORT_DIR=$(pwd) popeye --save --out html --output-file report.html
### Salva in archiviazione oggetti S3
In alternativa, puoi inviare i report generati a un archivio oggetti AWS S3 o Minio fornendo il flag `--s3-bucket`.
Per i parametri devi fornire il nome del bucket S3 in cui desideri salvare il report.
Per salvare il report in una sottodirectory del bucket, fornisci il parametro bucket come `bucket/path/to/report`.
Esempio per salvare il report su 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
Puoi anche eseguire Popeye in un container eseguendolo direttamente dal repository docker ufficiale su Quay.
Il comando predefinito quando si esegue il container docker è popeye, quindi puoi personalizzare la scansione utilizzando i flag cli supportati.
Per accedere ai tuoi cluster, mappa la directory kubeconfig locale nel container con -v :```shell
docker run --rm -it -v $HOME/.kube:/root/.kube quay.io/derailed/popeye --context foo -n bar
Eseguendo il comando docker sopra con `--rm` significa che il container viene eliminato quando Popeye esce.
Quando usi `--save`, scrive il report in /tmp nel container e poi elimina il container quando popeye esce, il che significa che perdi l'output ;(
Per aggirare questo problema, mappa /tmp al /tmp del container.
> NOTA: Puoi sovrascrivere la posizione predefinita della directory di output impostando la variabile d'ambiente `POPEYE_REPORT_DIR`.```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 può generare report di linting in vari formati. Puoi utilizzare l'opzione CLI -o e scegliere il tuo veleno.
Popeye può pubblicare metriche Prometheus direttamente da una scansione. Dovrai avere accesso a un pushgateway Prometheus e alle credenziali.
NOTA! Questi sono soggetti a modifiche in base al feedback e all'uso degli utenti!!
Per pubblicare le metriche, devono essere presenti ulteriori argomenti CLI.```shell
popeye --push-gtwy-url http://localhost:9091
popeye -o html --save --push-gtwy-url http://localhost:9091
### Metrica PopProm
Le seguenti metriche prometheus di Popeye vengono pubblicate:
* `popeye_severity_total` [gauge] traccia vari conteggi in base alla gravità.
* `popeye_code_total` [gauge] traccia conteggi per codice del linter di Popeye.
* `popeye_linter_tally_total` [gauge] traccia conteggi per linter.
* `popeye_report_errors_total` [gauge] traccia totali errori di scansione.
* `popeye_cluster_score` [gauge] traccia punteggi del report di scansione.
### PopGraf
Un esempio di dashboard [Grafana](https://grafana.com) si trova in questo repo per iniziare.
> NOTA! Lavoro in corso, sentiti libero di contribuire se hai competenze in UX/grafana/promql.
---
## SpinachYAML
Un file di configurazione YAML di tipo spinach può essere specificato tramite l'opzione `-f` per configurare ulteriormente i linter. Questo file può specificare la soglia di utilizzo del container e configurazioni specifiche del linter, così come risorse e codici che saranno esclusi dal linter.
> NOTA! Questo file cambierà man mano che Popeye matura!
Sotto la chiave `excludes` puoi configurare di saltare determinate risorse o codici del linter. I linter di Popeye prendono il nome dalle risorse k8s. Ad esempio il linter PodDisruptionBudget si chiama `poddisruptionbudgets` e scansiona `policy/v1/poddisruptionbudgets`.
> NOTA! Il linter usa la forma plurale del `kind` della risorsa e tutto è scritto in minuscolo.
Un nome completo della risorsa (noto come `FQN`) è usato nel file spinach per identificare un nome di risorsa, cioè `namespace/resource_name`.
Ad esempio, il FQN di un pod chiamato `fred-1234` nel namespace `blee` sarà `blee/fred-1234`. Questo permette di differenziare `fred/p1` e `blee/p1`. Per le risorse a livello di cluster, il FQN è equivalente al nome. Le regole di esclusione possono essere un semplice match di stringa o un'espressione regolare. In quest'ultimo caso l'espressione regolare deve essere specificata tramite il prefisso `rx:`.
> NOTA! Per favore, fai attenzione con le tue regex poiché più risorse del previsto potrebbero essere escluse dal report con una regola regex *permissiva*.
> Quando le risorse del tuo cluster cambiano, ciò potrebbe portare a scansioni sub-ottimali.
> Pertanto raccomandiamo di eseguire Popeye `wide open` di tanto in tanto per assicurarti di cogliere eventuali nuovi problemi che potrebbero essere sorti nei tuoi cluster…
Ecco un file spinach di esempio così come si presenta in questa release. C'è un file spinach più completo basato su eks e aks in questo repo sotto `spinach`. (BTW: per i nuovi arrivati nel progetto, potrebbe essere un ottimo modo per contribuire aggiungendo PR con file spinach specifici per cluster...)```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 è containerizzato e può essere eseguito direttamente nei tuoi cluster Kubernetes come job una tantum o CronJob.
Ecco un esempio di configurazione, modificalo secondo le tue esigenze/preferenze. I manifest per questa configurazione si trovano nella directory k8s in questo repository.```shell kubectl apply -f k8s/popeye
INGRESSO:```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
The --force-exit-zero dovrebbe essere impostata. Altrimenti, i pod finiranno in uno stato di errore.
NOTA! Popeye termina con un codice di errore diverso da zero se vengono rilevati errori di lint.
Affinché Popeye possa svolgere il suo lavoro, l'utente autenticato deve avere sufficiente potenza RBAC per ottenere/elencare le risorse menzionate sopra.
Esempi di regole RBAC per Popeye (si prega di notare che sono soggette a modifiche.)
NOTA! Si prega di rivedere e regolare in base alle politiche del proprio cluster.```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:
---
## Morfologia del Report
Il report di lint restituisce ogni gruppo di risorse scansionato e i loro potenziali problemi.
Il report è codificato a colori/emoji in termini di livelli di severità del linter:
| Livello | Icona | Jurassic | Colore | Descrizione |
|---------|-------|----------|-----------|---------------------|
| Ok | ✅ | OK | Verde | Felice! |
| Info | 🔊 | I | BluVerde | Info |
| Avviso | 😱 | W | Giallo | Potenziale Problema |
| Errore | 💥 | E | Rosso | Azione richiesta |
La sezione di intestazione per ogni risorsa Kubernetes scansionata fornisce un conteggio riepilogativo per ciascuna delle categorie sopra indicate.
La sezione Riepilogo fornisce un **Punteggio Popeye** basato sulla passata del linter sul cluster dato.
---
## Problemi Noti
Questa prima versione è fragile. Popeye molto probabilmente esploderà quando…
* Stai eseguendo versioni precedenti di Kubernetes. Popeye funziona meglio con Kubernetes 1.25.X.
* Non hai abbastanza potenza RBAC per gestire il tuo cluster (vedi sezione RBAC)
---
## Dichiarazione di non responsabilità
Questo è un work in progress! Se c'è abbastanza interesse nella comunità di Kubernetes, lo miglioreremo in base ai vostri suggerimenti/contributi. Inoltre, se apprezzate questo sforzo, fatecelo sapere!
---
## ATTA Ragazze/Ragazzi!
Popeye si basa su molti progetti e librerie open source. Il nostro *sincero* ringraziamento a tutti i contributori OSS che lavorano notti e weekend per rendere questo progetto realtà!
### Informazioni di Contatto
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.
Tutti i materiali sono concessi in licenza sotto [Apache v2.0](http://www.apache.org/licenses/LICENSE-2.0)
| Formato | Descrizione | Predefinito | Crediti |
|---|
| standard | L'output completo con icone e colori | sì | |
| jurassic | Niente icone o colori come nel 1979 | ||
| yaml | Come YAML | ||
| html | Come HTML | ||
| json | Come JSON | ||
| junit | Per i malinconici di Java | ||
| prometheus | Genera un report come metriche Prometheus | dardanel | |
| score | Restituisce un singolo punteggio di linting del cluster (0-100) | kabute |