Popeye : scanner de santé pour clusters Kubernetes

Popeye scanne votre cluster Kubernetes en temps réel et génère un rapport de santé avec un score de 0 à 100. L’outil détecte les mauvaises configurations courantes : images taguées latest, absence de limites CPU/mémoire, pods sans probes, conteneurs root, secrets inutilisés. En 30 secondes, vous savez ce qui doit être corrigé.

Ce guide vous montre comment :

• Installer Popeye via mise, Homebrew ou binaire
• Lancer un scan et interpréter les résultats
• Filtrer l’analyse par namespace ou type de ressource
• Personnaliser les règles avec spinach.yaml
• Intégrer dans une CI/CD avec seuil de score minimal

Version actuelle

Ce guide utilise Popeye v0.22.1 (janvier 2025). Popeye supporte Kubernetes 1.25+ et fonctionne en lecture seule — il ne modifie jamais vos ressources.

Pourquoi auditer son cluster avec Popeye

Kubernetes accepte de déployer des manifestes même s’ils violent les bonnes pratiques. Un Deployment sans limites de ressources ? Accepté. Une image nginx:latest ? Déployée. Un pod qui tourne en root ? Aucune erreur.

Ces configurations fonctionnent… jusqu’au jour où :

• Un pod consomme toute la mémoire du node et fait crasher les autres
• Une mise à jour automatique de latest casse l’application
• Une vulnérabilité exploite les privilèges root du conteneur

Popeye détecte ces problèmes avant qu’ils ne surviennent en analysant ce qui tourne réellement dans le cluster (pas les fichiers YAML sur disque).

Ce que Popeye vérifie	Exemple de problème détecté
Images	Tag latest, image sans tag
Ressources	Pas de requests/limits CPU/mémoire
Probes	Pas de liveness/readiness probe
Sécurité	Container root, pas de NetworkPolicy
RBAC	ClusterRoles/Roles inutilisés
Ressources orphelines	ConfigMaps, Secrets non référencés

Glissez pour voir

Installation

Avec mise (recommandé)

mise install popeye@latest
mise use popeye@latest

Avec Homebrew

brew install derailed/popeye/popeye

Binaire précompilé

# Télécharger depuis GitHub
curl -LO https://github.com/derailed/popeye/releases/download/v0.22.1/popeye_linux_amd64.tar.gz
tar -xzf popeye_linux_amd64.tar.gz
sudo mv popeye /usr/local/bin/

Vérification :

popeye version

Version:   0.22.1
Commit:    35b554961dcdabfa7aba6bd070673c6c24c70884
Date:      2025-01-28T15:31:22Z

Premier scan

Popeye utilise votre kubeconfig actif (comme kubectl). Lancez un scan complet :

popeye

Résultat sur un cluster Kind fraîchement créé :

GENERAL [KIND-POPEYE-TEST]
┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅
  · Connectivity.............................✅
  · MetricServer.............................💥

CLUSTER (1 SCANNED)                    💥 0 😱 0 🔊 0 ✅ 1 100٪
┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅
  · Version..................................✅
    ✅ [POP-406] K8s version OK.

DEPLOYMENTS (2 SCANNED)                💥 0 😱 1 🔊 1 ✅ 0 50٪
┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅
  · demo/nginx-bad...........................😱
    🐳 nginx
      😱 [POP-101] Image tagged "latest" in use.
      😱 [POP-106] No resources requests/limits defined.
  · demo/nginx-good..........................🔊
    🐳 nginx
      🔊 [POP-108] Unnamed port 8080.

SUMMARY
┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅┅
Your cluster score: A (91)

Comprendre le rapport

Niveaux de sévérité

Icône	Niveau	Signification	Action
✅	OK	Ressource conforme	Rien à faire
🔊	Info	Recommandation	Amélioration optionnelle
😱	Warn	Problème potentiel	À corriger
💥	Error	Problème critique	Action immédiate requise

Glissez pour voir

Codes d’erreur courants

Code	Message	Explication	Solution
POP-101	Image tagged “latest”	L’image peut changer sans préavis	Spécifier une version : nginx:1.27.0
POP-102	No probes defined	Kubernetes ne sait pas si l’app est saine	Ajouter liveness/readiness probes
POP-106	No resources requests/limits	Le pod peut consommer toutes les ressources	Définir requests et limits
POP-107	No resource limits	Limits absentes (requests présentes)	Ajouter limits CPU/memory
POP-300	Uses “default” ServiceAccount	Risque de permissions excessives	Créer un ServiceAccount dédié
POP-302	Pod running as root	Risque de sécurité	Ajouter runAsNonRoot: true
POP-400	Unable to locate reference	ConfigMap/Secret inutilisé	Supprimer ou utiliser la ressource
POP-1204	Not secured by NetworkPolicy	Trafic non filtré	Ajouter une NetworkPolicy

Glissez pour voir

Liste complète des codes

Consultez la documentation officielle des codes pour la liste exhaustive.

Calcul du score

Le score (0-100) est calculé par type de ressource, puis agrégé. Chaque problème réduit le score selon sa sévérité :

• Error : forte pénalité
• Warn : pénalité moyenne
• Info : faible impact

Un cluster de production devrait viser 80+ (note B minimum).

Score	Note	Interprétation
90-100	A	Excellent, peu de corrections
80-89	B	Bon, quelques améliorations
70-79	C	Acceptable, corrections recommandées
60-69	D	Insuffisant, action requise
0-59	F	Critique, problèmes majeurs

Glissez pour voir

Filtrer l’analyse

Par namespace

# Un seul namespace
popeye -n demo

# Tous les namespaces
popeye -A

Par type de ressource

Utilisez l’option -s (sections) avec les alias de ressources :

# Pods et Deployments uniquement
popeye -n demo -s po,deploy

Ressource	Alias
Pod	po
Deployment	dp, deploy
Service	svc
ConfigMap	cm
Secret	sec
ServiceAccount	sa
Ingress	ing
StatefulSet	sts
DaemonSet	ds
Job	job
CronJob	cj
PersistentVolumeClaim	pvc
NetworkPolicy	np
HorizontalPodAutoscaler	hpa

Glissez pour voir

Par niveau de sévérité

Afficher uniquement les problèmes warn et plus :

popeye -l warn

Valeurs possibles : ok, info, warn, error

Formats de sortie

Console (défaut)

popeye

JSON (pour traitement automatisé)

popeye -o json > rapport.json

HTML (pour partage)

POPEYE_REPORT_DIR=\$(pwd) popeye --save --out html --output-file rapport.html

Score seul (pour CI/CD)

popeye -o score
# Retourne uniquement le chiffre, ex: 91

Autres formats

• yaml : rapport YAML
• junit : format JUnit pour intégration CI
• jurassic : texte sans couleurs ni icônes
• prometheus : métriques Prometheus

Personnaliser les règles avec spinach.yaml

Créez un fichier spinach.yaml pour adapter les règles à votre contexte :

spinach.yaml

# Configuration Popeye
popeye:
  # Seuils d'utilisation des ressources
  allocations:
    cpu:
      underPercUtilization: 200  # Alerte si CPU sous-utilisé > 200%
      overPercUtilization: 50    # Alerte si CPU sur-utilisé > 50%
    memory:
      underPercUtilization: 200
      overPercUtilization: 50

  # Exclusions
  excludes:
    # Exclusions globales (tous les linters)
    global:
      fqns: [rx:^kube-]  # Ignorer kube-system, kube-public...
      codes: ["300"]     # Ignorer le code POP-300

    # Exclusions par linter
    linters:
      pods:
        instances:
          - fqns: [kube-system/coredns]
            codes: ["302"]  # Ignorer "running as root" pour CoreDNS

      namespaces:
        codes: ["100"]  # Ignorer namespace inactif

  # Seuils pour les pods
  resources:
    pod:
      restarts: 5  # Alerte si > 5 restarts
      limits:
        cpu: 80
        memory: 75

  # Registries autorisés (tout autre registre = erreur)
  registries:
    - docker.io
    - ghcr.io
    - quay.io
    - registry.k8s.io

  # Modifier la sévérité d'un code
  overrides:
    - code: "206"      # PodDisruptionBudget manquant
      severity: 1      # Réduire à Info (1=info, 2=warn, 3=error)

Lancez Popeye avec ce fichier :

popeye -f spinach.yaml

Regex dans les exclusions

Les patterns regex utilisent le préfixe rx:. Exemple : rx:^kube- matche tout ce qui commence par kube-.

Attention aux regex trop larges qui pourraient masquer des problèmes réels.

Intégration CI/CD

GitHub Actions

.github/workflows/popeye.yaml

name: Kubernetes Lint

on:
  push:
    branches: [main]
  schedule:
    - cron: '0 6 * * *'  # Tous les jours à 6h

jobs:
  popeye:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup kubeconfig
        run: |
          mkdir -p ~/.kube
          echo "\${{ secrets.KUBECONFIG }}" | base64 -d > ~/.kube/config

      - name: Install Popeye
        run: |
          curl -LO https://github.com/derailed/popeye/releases/download/v0.22.1/popeye_linux_amd64.tar.gz
          tar -xzf popeye_linux_amd64.tar.gz
          sudo mv popeye /usr/local/bin/

      - name: Run Popeye
        run: |
          popeye -A --min-score 80 -o json > popeye-report.json

      - name: Upload Report
        uses: actions/upload-artifact@v4
        with:
          name: popeye-report
          path: popeye-report.json

L’option --min-score 80 fait échouer le job si le score est inférieur à 80.

GitLab CI

.gitlab-ci.yml

popeye:
  stage: validate
  image: quay.io/derailed/popeye:v0.22.1
  script:
    - popeye -A --min-score 75 --force-exit-zero -o yaml
  rules:
    - if: \$CI_PIPELINE_SOURCE == "schedule"

--force-exit-zero

Par défaut, Popeye retourne un code d’erreur non-nul si des problèmes sont détectés. Utilisez --force-exit-zero si vous voulez que le job réussisse même avec des warnings (utile pour les rapports informatifs).

Exécution dans le cluster

Popeye peut tourner directement dans Kubernetes via un CronJob :

popeye-cronjob.yaml

apiVersion: v1
kind: Namespace
metadata:
  name: popeye
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: popeye
  namespace: popeye
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: popeye
rules:
  - apiGroups: [""]
    resources: [configmaps, endpoints, namespaces, nodes, persistentvolumes,
                persistentvolumeclaims, pods, secrets, serviceaccounts, services]
    verbs: [get, list]
  - apiGroups: [apps]
    resources: [daemonsets, deployments, statefulsets, replicasets]
    verbs: [get, list]
  - apiGroups: [networking.k8s.io]
    resources: [ingresses, networkpolicies]
    verbs: [get, list]
  - apiGroups: [autoscaling]
    resources: [horizontalpodautoscalers]
    verbs: [get, list]
  - apiGroups: [policy]
    resources: [poddisruptionbudgets]
    verbs: [get, list]
  - apiGroups: [rbac.authorization.k8s.io]
    resources: [clusterroles, clusterrolebindings, roles, rolebindings]
    verbs: [get, list]
  - apiGroups: [metrics.k8s.io]
    resources: [pods, nodes]
    verbs: [get, list]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: popeye
subjects:
  - kind: ServiceAccount
    name: popeye
    namespace: popeye
roleRef:
  kind: ClusterRole
  name: popeye
  apiGroup: rbac.authorization.k8s.io
---
apiVersion: batch/v1
kind: CronJob
metadata:
  name: popeye
  namespace: popeye
spec:
  schedule: "0 */6 * * *"  # Toutes les 6 heures
  concurrencyPolicy: Forbid
  jobTemplate:
    spec:
      template:
        spec:
          serviceAccountName: popeye
          restartPolicy: Never
          containers:
            - name: popeye
              image: quay.io/derailed/popeye:v0.22.1
              args:
                - -A
                - -o
                - yaml
                - --force-exit-zero
              resources:
                limits:
                  cpu: 500m
                  memory: 256Mi

kubectl apply -f popeye-cronjob.yaml

Bonnes pratiques

Exécuter régulièrement

Planifiez un scan quotidien ou après chaque déploiement majeur. Les problèmes s’accumulent vite.

Commencer par un namespace

Sur un grand cluster, analysez d’abord un namespace critique :

popeye -n production -l warn

Documenter les exclusions

Si vous excluez des règles dans spinach.yaml, documentez pourquoi :

excludes:
  linters:
    pods:
      instances:
        # CoreDNS tourne en root par design (upstream)
        # Voir: https://github.com/coredns/coredns/issues/...
        - fqns: [kube-system/coredns]
          codes: ["302"]

Surveiller le score dans le temps

Exportez les rapports JSON et suivez l’évolution du score. Un score qui baisse indique une dette technique croissante.

Dépannage

Problème	Cause probable	Solution
MetricServer 💥	metrics-server non installé	Installer metrics-server ou ignorer
Timeout sur grand cluster	Trop de ressources à scanner	Filtrer par namespace -n
Permissions insuffisantes	RBAC manquant	Vérifier les droits get/list
Score très bas sur kube-system	Composants système non optimisés	Exclure via spinach.yaml

Glissez pour voir

À retenir

• Popeye analyse le cluster en temps réel (pas les fichiers YAML)
• Le score de 0 à 100 donne une vue d’ensemble rapide
• Les codes POP-xxx identifient précisément chaque problème
• spinach.yaml permet d’adapter les règles à votre contexte
• Intégrez dans la CI/CD avec --min-score pour bloquer les régressions
• Popeye est en lecture seule : il ne modifie jamais vos ressources

Prochaines étapes

Kubescape Scanner de sécurité Kubernetes plus poussé (NSA, MITRE)

k9s Interface terminal pour naviguer et débugger le cluster

Trivy Scanner de vulnérabilités pour images et configurations

Helm Gestionnaire de packages Kubernetes

Pour aller plus loin

• Documentation officielle Popeye
• Repository GitHub
• Liste complète des codes d’erreur
• Exemples de fichiers spinach

×

📖 Voir la documentation →