
👀 Санитайзер ресурсов кластера Kubernetes
Popeye — это утилита, которая сканирует живые кластера Kubernetes и сообщает о потенциальных проблемах с развёрнутыми ресурсами и конфигурациями. По мере роста ландшафта Kubernetes человеку становится всё сложнее отслеживать множество манифестов и политик, управляющих кластером. Popeye сканирует ваш кластер на основе того, что развёрнуто, а не того, что находится на диске. Линтируя кластер, он обнаруживает неправильные конфигурации, устаревшие ресурсы и помогает убедиться, что применяются лучшие практики, предотвращая тем самым будущие проблемы. Он направлен на снижение когнитивной перегрузки, с которой сталкивается человек при эксплуатации кластера Kubernetes в реальных условиях. Кроме того, если в вашем кластере используется metric-server, он сообщает о потенциальном пере/недоиспользовании ресурсов и пытается предупредить, если кластеру грозит нехватка ёмкости.
Popeye — это инструмент только для чтения, он никоим образом не изменяет ваши ресурсы Kubernetes!
Вы можете выгрузить отчёт сканирования в HTML.
Popeye публикует метрики Prometheus. В этом репозитории мы предоставили образец панели Popeye, чтобы вы могли быстро начать.
Popeye доступен на платформах Linux, OSX и Windows.
Бинарные файлы для Linux, Windows и Mac доступны в виде tarball'ов на странице релизов.
Для OSX/Unit с использованием Homebrew/LinuxBrew ```shell brew install derailed/popeye/popeye
Использование go install
go install github.com/derailed/popeye@latest
Сборка из исходных кодов Popeye был собран с использованием go 1.21+. Чтобы собрать Popeye из исходных кодов, необходимо:
Клонировать репозиторий
Добавить следующую команду в ваш файл go.mod
replace (
github.com/derailed/popeye => MY_POPEYE_CLONED_GIT_REPO
)
Собрать и запустить исполняемый файл
go run main.go
Быстрый рецепт для нетерпеливых: ```shell
git clone https://github.com/derailed/popeye cd popeye
make build
popeye
Popeye использует 256-цветный терминальный режим. В системе `Nix убедитесь, что TERM установлен соответствующим образом.
export TERM=xterm-256color
Вы можете использовать Popeye в открытом виде или с помощью spinach yaml config для настройки ваших линтеров. Подробности о файле конфигурации Popeye приведены ниже.```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
---
## Линтеры
Popeye сканирует ваш кластер на предмет лучших практик и потенциальных проблем.
В настоящее время Popeye проверяет только заданный набор отобранных ресурсов Kubernetes.
Скоро их станет больше!
Мы надеемся, что друзья Kubernetes помогут сделать Popeye еще лучше.
Цель линтеров — выявлять неправильные конфигурации, такие как
несоответствие портов, мертвые или неиспользуемые ресурсы, использование метрик,
пробы, образы контейнеров, правила RBAC, «голые» ресурсы и т. д.
Popeye — это не очередной инструмент статического анализа. Он работает и проверяет ресурсы Kubernetes на
живых кластерах и линтит ресурсы в том виде, в котором они существуют в реальной среде!
Вот список некоторых доступных линтеров:
| | Ресурс | Линтеры | Псевдонимы |
|----|-------------------------|-------------------------------------------------------------------------|------------|
| 🛀 | Node | | no |
| | | Условия, например, не готов, нехватка памяти/диска, сети, процессов и т.д. | |
| | | Допуски подов, ссылающиеся на окрашивания узлов | |
| | | Метрики использования CPU/ОЗУ, срабатывание при превышении лимитов (по умолчанию 80% CPU/ОЗУ) | |
| 🛀 | Namespace | | ns |
| | | Неактивные | |
| | | Мертвые пространства имён | |
| 🛀 | Pod | | po |
| | | Статус пода | |
| | | Статусы контейнеров | |
| | | Наличие ServiceAccount | |
| | | CPU/ОЗУ на контейнерах сверх заданного лимита (по умолчанию 80% CPU/ОЗУ) | |
| | | Образ контейнера без тегов | |
| | | Образ контейнера с тегом `latest` | |
| | | Наличие запросов/лимитов ресурсов | |
| | | Наличие проб liveness/readiness | |
| | | Именованные порты и их ссылки | |
| 🛀 | Service | | svc |
| | | Наличие Endpoints | |
| | | Метки подов, соответствующих сервису | |
| | | Именованные порты и их ссылки | |
| 🛀 | ServiceAccount | | sa |
| | | Неиспользуемые, выявляет потенциально неиспользуемые SA | |
| 🛀 | Secrets | | sec |
| | | Неиспользуемые, выявляет потенциально неиспользуемые секреты или связанные ключи | |
| 🛀 | ConfigMap | | cm |
| | | Неиспользуемые, выявляет потенциально неиспользуемые CM или связанные ключи | |
| 🛀 | Deployment | | dp, deploy |
| | | Неиспользуемые, проверка шаблона пода, использование ресурсов | |
| 🛀 | StatefulSet | | sts |
| | | Неиспользуемые, проверка шаблона пода, использование ресурсов | |
| 🛀 | DaemonSet | | ds |
| | | Неиспользуемые, проверка шаблона пода, использование ресурсов | |
| 🛀 | PersistentVolume | | pv |
| | | Неиспользуемые, проверка привязки тома или ошибки тома | |
| 🛀 | PersistentVolumeClaim | | pvc |
| | | Неиспользуемые, проверка привязки или ошибки монтирования тома | |
| 🛀 | HorizontalPodAutoscaler | | hpa |
| | | Неиспользуемые, использование, проверка максимального всплеска | |
| 🛀 | PodDisruptionBudget | | |
| | | Неиспользуемые, проверка конфигурации minAvailable | pdb |
| 🛀 | ClusterRole | | |
| | | Неиспользуемые | cr |
| 🛀 | ClusterRoleBinding | | |
| | | Неиспользуемые | crb |
| 🛀 | Role | | |
| | | Неиспользуемые | ro |
| 🛀 | RoleBinding | | |
| | | Неиспользуемые | rb |
| 🛀 | Ingress | | |
| | | Действительный | ing |
| 🛀 | NetworkPolicy | | |
| | | Действительная, устаревшая, защищённая | np |
| 🛀 | PodSecurityPolicy | | |
| | | Действительная | psp |
| 🛀 | Cronjob | | |
| | | Действительная, приостановленная, выполняется | cj |
| 🛀 | Job | | |
| | | Проверки пода | job |
| 🛀 | GatewayClass | | |
| | | Действительный, неиспользуемый | gwc |
| 🛀 | Gateway | | |
| | | Действительный, неиспользуемый | gw |
| 🛀 | HTTPRoute | | |
| | | Действительный, неиспользуемый | gwr |
Вы также можете посмотреть [полный список кодов](https://github.com/derailed/popeye/blob/HEAD/docs/codes.md)
---
## Сохранение результатов сканирования
Чтобы сохранить отчёт Popeye в файл, укажите флаг `--save` в команде.
По умолчанию будет создана временная директория, и в неё будет сохранён отчёт о сканировании.
Путь к временной директории будет выведен в STDOUT.
Если вам нужно указать директорию вывода для отчёта,
вы можете использовать переменную окружения `POPEYE_REPORT_DIR`. Конечный путь будет <POPEYE_REPORT_DIR>/<cluster>/<context>.
По умолчанию имя выходного файла имеет следующий формат: `lint_<cluster-name>_<time-UnixNano>.<output-extension>` (например: "lint-mycluster-1594019782530851873.html").
Если вы также хотите указать имя выходного файла для отчёта, вы можете указать флаг `--output-file` с желаемым именем файла.
Пример сохранения отчёта в рабочей директории:```shell
POPEYE_REPORT_DIR=$(pwd) popeye --save
Пример сохранения отчета в рабочем каталоге в формате HTML под именем "report.html" :```shell POPEYE_REPORT_DIR=$(pwd) popeye --save --out html --output-file report.html
### Сохранение в объектное хранилище S3
Кроме того, вы можете отправлять сгенерированные отчеты в объектное хранилище AWS S3 или Minio, указав флаг `--s3-bucket`.
Для параметров необходимо указать имя корзины S3, в которой вы хотите сохранить отчет.
Чтобы сохранить отчет в подкаталоге корзины, укажите параметр bucket как `bucket/path/to/report`.
Пример сохранения отчета в 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
Вы также можете запустить Popeye в контейнере, запустив его напрямую из официального docker-репозитория на Quay.
Команда по умолчанию при запуске docker-контейнера — popeye, поэтому вы можете настроить сканирование, используя поддерживаемые флаги CLI.
Чтобы получить доступ к вашим кластерам, смонтируйте локальную директорию kubeconfig в контейнер с помощью -v :```shell
docker run --rm -it -v $HOME/.kube:/root/.kube quay.io/derailed/popeye --context foo -n bar
Запуск указанной выше команды docker с флагом `--rm` означает, что контейнер будет удалён после завершения работы Popeye.
При использовании флага `--save` вывод будет записан в /tmp внутри контейнера, а затем контейнер удалится при завершении Popeye, что означает потерю вывода ;(
Чтобы обойти эту проблему, смонтируйте /tmp в /tmp контейнера.
> ПРИМЕЧАНИЕ: Вы можете переопределить расположение каталога вывода по умолчанию, задав переменную окружения `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 может генерировать отчеты линтера в различных форматах. Вы можете использовать параметр -o и выбрать подходящий формат.
Popeye может публиковать метрики Prometheus напрямую из сканирования. Вам понадобится доступ к pushgateway Prometheus и учетные данные.
ПРИМЕЧАНИЕ! Эти метрики могут измениться на основе отзывов пользователей и использования!!
Для публикации метрик должны быть указаны дополнительные аргументы командной строки.```shell
popeye --push-gtwy-url http://localhost:9091
popeye -o html --save --push-gtwy-url http://localhost:9091
### Метрики PopProm
Следующие метрики Prometheus публикуются Popeye:
* `popeye_severity_total` [gauge] отслеживает различные счетчики по степени серьезности.
* `popeye_code_total` [gauge] отслеживает счетчики по кодам линтеров Popeye.
* `popeye_linter_tally_total` [gauge] отслеживает счетчики по каждому линтеру.
* `popeye_report_errors_total` [gauge] отслеживает общее количество ошибок сканирования.
* `popeye_cluster_score` [gauge] отслеживает оценки отчета сканирования.
### PopGraf
Пример панели управления [Grafana](https://grafana.com) можно найти в этом репозитории, чтобы начать работу.
> ПРИМЕЧАНИЕ! Работа в процессе, пожалуйста, не стесняйтесь вносить свой вклад, если вы разбираетесь в UX/grafana/promql.
---
## SpinachYAML
Файл конфигурации spinach YAML можно указать с помощью опции `-f` для дальнейшей настройки линтеров. Этот файл может задавать
порог использования контейнера и конкретные конфигурации линтеров, а также ресурсы и коды, которые будут исключены из проверки линтером.
> ПРИМЕЧАНИЕ! Этот файл будет меняться по мере развития Popeye!
В разделе `excludes` вы можете настроить пропуск определенных ресурсов или кодов линтеров.
Линтеры Popeye названы в честь имен ресурсов k8s.
Например, линтер PodDisruptionBudget называется `poddisruptionbudgets` и сканирует `policy/v1/poddisruptionbudgets`
> ПРИМЕЧАНИЕ! Линтер использует множественную форму ресурса `kind`, и все пишется строчными буквами.
Полное квалифицированное имя ресурса, также известное как `FQN`, используется в файле spinach для идентификации имени ресурса, т.е. `пространство_имён/имя_ресурса`.
Например, FQN пода с именем `fred-1234` в пространстве имен `blee` будет `blee/fred-1234`. Это позволяет различать `fred/p1` и `blee/p1`.
Для ресурсов уровня кластера FQN эквивалентен имени.
Правила исключения могут быть либо точным совпадением строки, либо регулярным выражением. В последнем случае регулярное выражение должно быть указано с префиксом `rx:`.
> ПРИМЕЧАНИЕ! Будьте осторожны с вашим регулярным выражением, так как из отчета может быть исключено больше ресурсов, чем ожидалось, из-за *свободного* правила регулярного выражения.
> Когда ресурсы вашего кластера меняются, это может привести к неоптимальным сканированиям.
> Поэтому мы рекомендуем время от времени запускать Popeye `на полную катушку`, чтобы убедиться, что вы улавливаете любые новые проблемы, которые могли возникнуть в ваших кластерах…
Вот пример файла spinach в том виде, в котором он представлен в этом релизе.
В этом репозитории в папке `spinach` есть более полные файлы spinach для eks и aks.
(Кстати: для новичков в проекте это может быть отличным способом внести свой вклад, добавив PR с файлами spinach для конкретных кластеров...)```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 контейнеризирован и может быть запущен непосредственно в ваших кластерах Kubernetes как одноразовая задача или CronJob.
Вот пример настройки, пожалуйста измените в соответствии с вашими потребностями/желаниями. Манифесты для этого находятся в k8s каталоге в этом репозитории.```shell kubectl apply -f k8s/popeye
Advanced features:
- **Конфигурация через YAML**: Все настройки, включая цели, полезные нагрузки и методы обхода, определяются в одном YAML-файле для удобного управления и контроля версий.
- **Система плагинов**: Легко расширяйте функциональность с помощью пользовательских плагинов, написанных на Python.
- **Совместная работа в реальном времени**: Делитесь результатами сканирования с членами команды в реальном времени.```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
Флаг --force-exit-zero должен быть установлен. В противном случае поды перейдут в состояние ошибки.
ПРИМЕЧАНИЕ! Popeye завершается с ненулевым кодом ошибки, если обнаружены какие-либо ошибки линтинга.
Для выполнения своей работы Popeye требует, чтобы вошедший пользователь имел достаточные права RBAC для получения/просмотра упомянутых выше ресурсов.
Пример правил RBAC для Popeye (обратите внимание, что они могут измениться.)
ПРИМЕЧАНИЕ! Пожалуйста, проверьте и настройте в соответствии с политиками вашего кластера.```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:
---
## Морфология отчёта
Отчёт линтера выводит каждую проверенную группу ресурсов и их потенциальные проблемы.
Отчёт цветокодирован и использует эмодзи в соответствии с уровнями серьёзности линтера:
| Уровень | Иконка | Jurassic | Цвет | Описание |
|---------|--------|----------|-----------|-------------------|
| Ok | ✅ | OK | Зелёный | Всё хорошо! |
| Info | 🔊 | I | Сине-зелёный| К сведению |
| Warn | 😱 | W | Жёлтый | Потенциальная проблема |
| Error | 💥 | E | Красный | Требуется действие |
В заголовочном разделе для каждого проверенного ресурса Kubernetes приводится сводное количество
по каждой из указанных выше категорий.
Раздел Summary содержит **Popeye Score**, основанный на результате прохода линтера по данному кластеру.
---
## Известные проблемы
Этот первоначальный релиз нестабилен. Popeye, скорее всего, «взорвётся», когда…
* Вы используете старые версии Kubernetes. Popeye лучше всего работает с Kubernetes 1.25.X.
* У вас недостаточно прав RBAC для управления кластером (см. раздел RBAC)
---
## Отказ от ответственности
Это работа в процессе! Если сообщество Kubernetes проявит достаточный интерес,
мы будем улучшать проект согласно вашим рекомендациям/вкладам.
Также, если вам нравится эта работа, дайте нам знать!
---
## Благодарности!
Popeye построен на основе множества проектов и библиотек с открытым исходным кодом. Наша *искренняя*
благодарность всем участникам OSS, которые работают по ночам и выходным,
чтобы сделать этот проект реальностью!
### Контактная информация
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.
Все материалы лицензированы по [Apache v2.0](http://www.apache.org/licenses/LICENSE-2.0)
| Формат | Описание | По умолчанию | Авторы |
|---|
| standard | Полный вывод с иконками и цветами | да | |
| jurassic | Без иконок и цветов, как в 1979 году | ||
| yaml | В формате YAML | ||
| html | В формате HTML | ||
| json | В формате JSON | ||
| junit | Для меланхоличных Java-разработчиков | ||
| prometheus | Выгружает отчет в виде метрик Prometheus | dardanel | |
| score | Возвращает одно значение оценки линтера кластера (0–100) | kabute |