derailed/popeye

Popeye - Kubernetes集群清理工具

!https://github.com/derailed/popeye/blob/master/assets/popeye_logo.png

镜像概述和主要用途

Popeye是一款Kubernetes集群清理工具，通过扫描运行中的集群，基于已部署资源（非磁盘配置）检测潜在问题和错误配置，帮助确保最佳实践的实施，减少集群运维的认知负担。它能报告资源分配过度或不足情况（需集群部署metric-server），且作为只读工具，不会对集群资源进行任何修改。

核心功能和特性

主要功能

• 多资源扫描：支持节点、命名空间、Pod、服务、ServiceAccount、Secret、ConfigMap、部署、StatefulSet等多种Kubernetes资源的检测（完整列表见下方清理器表格）
• 错误配置检测：识别端口不匹配、未使用资源、容器镜像标签问题（如latest标签）、探针缺失等配置问题
• 资源分配分析：检查CPU/内存资源的过度分配或分配不足，基于集群metric-server数据提供利用率警告
• 多输出格式：支持标准（带图标和颜色）、YAML、HTML、JSON、JUnit、Prometheus等多种报告格式
• 灵活配置：通过spinach.yml配置文件自定义资源利用率阈值、排除特定资源或检查项
• 安全只读：仅读取集群资源，不执行任何修改操作

支持的清理器

使用场景和适用范围

• 集群健康检查：定期扫描集群，识别配置问题和资源风险
• 部署前验证：在新应用部署后检查配置是否符合最佳实践
• 资源优化：发现过度分配或未充分利用的资源，优化集群资源使用
• 合规审计：生成标准化报告，用于合规性检查和审计跟踪
• Kubernetes管理员工具：辅助管理员监控集群状态，减少运维负担

使用方法和配置说明

Docker快速启动

基本扫描

通过Docker运行Popeye，挂载本地kubeconfig以访问集群：

shell
docker run --rm -it \
  -v $HOME/.kube:/root/.kube \
  derailed/popeye --context <集群上下文> -n <命名空间>

保存报告到本地

将报告保存到宿主机目录，需挂载本地目录并设置报告目录环境变量：

shell
docker run --rm -it \
  -v $HOME/.kube:/root/.kube \
  -e POPEYE_REPORT_DIR=/tmp/popeye \
  -v /tmp:/tmp \
  derailed/popeye --context <集群上下文> -n <命名空间> --save --output-file <报告文件名>

示例：保存HTML报告到当前目录

shell
POPEYE_REPORT_DIR=$(pwd) docker run --rm -it \
  -v $HOME/.kube:/root/.kube \
  -v $(pwd):/tmp/popeye \
  derailed/popeye --save --out html --output-file cluster-report.html

保存报告到S3兼容存储

指定S3 bucket和可选子目录，支持AWS S3及MinIO等兼容存储：

shell
docker run --rm -it \
  -v $HOME/.kube:/root/.kube \
  -e AWS_ACCESS_KEY_ID=<访问密钥> \
  -e AWS_SECRET_ACCESS_KEY=<密钥> \
  derailed/popeye --s3-bucket=<bucket名>/<子目录> --out json

命令行选项

环境变量

预检检查

• 终端颜色支持：在类Unix系统中，需确保终端支持256色：

shell
export TERM=xterm-256color

• RBAC权限：运行Popeye的用户/ServiceAccount需具备集群资源的get和list权限（详见下方RBAC配置）

配置文件（spinach.yml）

通过-f spinach.yml指定配置文件，自定义清理规则。示例配置：

yaml
popeye:
  # 资源分配阈值（过度/不足分配百分比）
  allocations:
    cpu:
      underPercUtilization: 200  # CPU分配不足阈值（当前负载下低于200%）
      overPercUtilization: 50    # CPU过度分配阈值（当前负载下超过50%）
    memory:
      underPercUtilization: 200
      overPercUtilization: 50

  # 排除规则：跳过特定资源或检查项
  excludes:
    # 排除v1/pods中监控命名空间的探针检查（错误码102）
    v1/pods:
      - name: rx:monitoring  # 正则匹配命名空间
        codes: [102]         # 排除错误码102（探针缺失）
      # 排除icx命名空间中istio代理容器的检查
      - name: rx:icx/.*      # 正则匹配pod名称（格式：命名空间/pod名）
        containers: [istio-proxy, istio-init]  # 排除特定容器

  # 节点资源阈值（利用率百分比）
  node:
    limits:
      cpu: 90    # 节点CPU利用率超过90%触发警告
      memory: 80 # 节点内存利用率超过80%触发警告

  # Pod配置
  pod:
    restarts: 3  # Pod重启次数超过3次触发警告
    limits:
      cpu: 80    # 容器CPU利用率超过80%触发警告
      memory: 75 # 容器内存利用率超过75%触发警告

  # 允许的镜像仓库
  registries:
    - quay.io
    - docker.io

RBAC权限配置

Popeye需要以下RBAC权限以扫描集群资源，创建ClusterRole和ClusterRoleBinding：

yaml
---
# ServiceAccount
apiVersion: v1
kind: ServiceAccount
metadata:
  name: popeye
  namespace: popeye

---
# ClusterRole
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: popeye
rules:
- apiGroups: [""]
  resources: [configmaps, endpoints, limitranges, 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, podsecuritypolicies]
  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"]

---
# ClusterRoleBinding
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

输出格式说明

注意事项

• Kubernetes版本：建议使用Kubernetes 1.13+，低版本可能存在兼容性问题
• Metric-Server：资源利用率分析依赖集群部署metric-server，否则相关检查将被跳过
• 正则排除规则：使用正则排除资源时需谨慎，避免过度排除导致漏检重要问题
• 报告安全：报告可能包含集群敏感信息，建议妥善保管输出文件