target/pod-reaper

pod-reaper: 基于规则的Kubernetes Pod删除工具

镜像概述和主要用途

pod-reaper是一个基于规则的Kubernetes Pod删除工具，旨在根据预定义条件识别并删除满足条件的Pod。通过配置不同规则，可实现混沌测试、异常Pod清理、定时维护等场景。具体规则详见「核心规则说明」部分。

核心功能和特性

• 多规则支持：基于混沌概率、容器状态、Pod状态、运行时长等多种条件删除Pod
• 灵活的作用域控制：支持按命名空间、标签、注解筛选目标Pod
• 安全删除机制：可配置优雅关闭周期，支持驱逐（Eviction）操作以尊重PodDisruptionBudget
• 可定制调度：支持Cron表达式或固定间隔调度检查周期
• 完善的日志系统：JSON结构化日志，支持多格式（Logrus、Fluentd）和日志级别控制
• 自愈与一次性运行：支持长期运行（通过Deployment管理）或限时运行模式

使用场景和适用范围

• 混沌工程：通过随机概率规则（Chaos Chance）注入故障，测试系统弹性
• 异常Pod清理：自动删除处于错误状态（如ImagePullBackOff、Evicted）的Pod
• 资源回收：清理长时间运行或未就绪的Pod，释放集群资源
• 维护自动化：配合调度规则实现定时Pod替换，确保应用滚动更新
• 集群稳定性：排除特定标签的关键Pod，只清理非核心工作负载

详细配置说明

环境变量总览

pod-reaper通过环境变量配置，需至少启用一个规则（详见「核心规则说明」），否则将报错退出。主要环境变量分类如下：

示例配置：

sh
# 基础配置
NAMESPACE=test
SCHEDULE=@every 30s
RUN_DURATION=15m
EXCLUDE_LABEL_KEY=pod-reaper
EXCLUDE_LABEL_VALUES=disabled,false
DRY_RUN=false

# 启用规则（至少一个）
CHAOS_CHANCE=.001  # 混沌概率规则

基础配置参数

NAMESPACE

• 默认值：""（监控所有命名空间）
• 作用：指定pod-reaper监控的Kubernetes命名空间。
• 说明：依赖Kubernetes服务账户（InClusterConfig）权限，仅能访问服务账户有权限的命名空间和Pod。

GRACE_PERIOD

• 默认值：nil（使用Pod默认优雅关闭周期）
• 作用：控制Pod软终止（SIGTERM）到硬终止（SIGKILL）的等待时间。
• 格式：Go语言time.Duration格式（如"1h15m30s"），0s表示立即硬终止。

SCHEDULE

• 默认值："@every 1m"（每分钟检查一次）
• 作用：配置Pod检查周期。
• 格式：支持Cron表达式（如"* * * * *"，可选秒级精度"* * * * * *"）或间隔格式（如"@every 30s"）。
• 示例："@every 1h2m3s"（每1小时2分3秒）、"12 * * * * *"（每分钟第12秒执行）。

RUN_DURATION

• 默认值："0s"（无限期运行）
• 作用：指定pod-reaper运行时长，到期后立即退出（退出码0）。
• 格式：Go语言time.Duration格式（如"15m"表示15分钟）。
• 注意：
  • 若通过Deployment管理，退出后会被重新调度；
  • 需排除自身Pod（通过EXCLUDE_LABEL）避免自我删除导致运行时长不足。

EVICT

• 默认值：未设置（使用删除操作）
• 作用：启用时使用Kubernetes驱逐API（Eviction API）而非直接删除Pod。
• 说明：尊重PodDisruptionBudget（PDB），若因PDB无法驱逐，将记录警告日志。

DRY_RUN

• 默认值：未设置（等效于false）
• 作用：启用时仅标记符合条件的Pod，不实际删除。
• 有效值：1/t/T/TRUE/true/True（启用）；0/f/F/FALSE/false/False（禁用）。

标签/注解筛选参数

EXCLUDE_LABEL_KEY 和 EXCLUDE_LABEL_VALUES

• 作用：排除带有特定标签的Pod。
• 说明：需同时设置Key和Values（逗号分隔，无空格）。若Pod标签的Key匹配EXCLUDE_LABEL_KEY且Value在EXCLUDE_LABEL_VALUES列表中，则被排除。
• 示例：EXCLUDE_LABEL_KEY=pod-reaper、EXCLUDE_LABEL_VALUES=disabled,false → 排除标签pod-reaper: disabled或pod-reaper: false的Pod。

REQUIRE_LABEL_KEY 和 REQUIRE_LABEL_VALUES

• 作用：仅处理带有特定标签的Pod。
• 说明：需同时设置Key和Values（逗号分隔）。仅当Pod标签的Key匹配REQUIRE_LABEL_KEY且Value在REQUIRE_LABEL_VALUES列表中，才会被考虑。

REQUIRE_ANNOTATION_KEY 和 REQUIRE_ANNOTATION_VALUES

• 作用：仅处理带有特定注解的Pod。
• 说明：逻辑同REQUIRE_LABEL，但基于Pod注解。

日志配置参数

LOG_LEVEL

• 默认值：Info
• 作用：控制日志级别，仅输出指定级别及以上的日志。
• 可选值：Debug、Info、Warning、Error、Fatal、Panic。

LOG_FORMAT

• 默认值：Logrus
• 作用：指定结构化日志格式。
• 可选值：
  • Logrus：默认格式；
  • Fluentd：适配Fluentd/Stackdriver的格式。

日志示例

json
{"level":"info","msg":"loaded rule: chaos chance .3","time":"2017-10-18T17:09:25Z"}
{"level":"info","msg":"executing reap cycle","time":"2017-10-18T17:09:55Z"}
{"level":"info","msg":"reaping pod","pod":"hello-cloud-deployment-3026746346-bj65k","reasons":["was flagged for chaos","has been running for 3m6.257891269s"],"time":"2017-10-18T17:09:55Z"}

核心规则说明

Chaos Chance（混沌概率规则）

• 作用：基于随机概率标记Pod进行删除。
• 启用方式：设置CHAOS_CHANCE为浮点值（范围[0,1)）。生成随机数若小于该值，则标记Pod。
• 示例：

  sh
  SCHEDULE=@every 30s  # 每30秒检查一次
  CHAOS_CHANCE=.01      # 1%概率删除匹配的Pod
  

• 说明：可通过EXCLUDE_LABEL排除关键Pod。

Container Status（容器状态规则）

• 作用：删除包含特定状态容器的Pod。
• 启用方式：设置CONTAINER_STATUSES为逗号分隔的容器状态列表（无空格）。若容器处于Waiting或Terminated状态且状态匹配，则标记Pod。
• 示例：

  sh
  SCHEDULE=@every 10m  # 每10分钟检查一次
  CONTAINER_STATUSES=ImagePullBackOff,ErrImagePull,Error  # 匹配这些容器状态
  

• 注意：不匹配Pod级状态（如Evicted）。

Pod Status（Pod状态规则）

• 作用：根据Pod整体状态删除Pod。
• 启用方式：设置POD_STATUSES为逗号分隔的Pod状态列表（无空格）。若Pod状态匹配，则标记删除。
• 示例：

  sh
  SCHEDULE=@every 10m  # 每10分钟检查一次
  POD_STATUSES=Evicted,Unknown  # 匹配这些Pod状态
  

Duration（运行时长规则）

• 作用：删除运行超过指定时长的Pod。
• 启用方式：设置MAX_DURATION为Go语言time.Duration格式。若Pod运行时间超过该值，则标记删除。
• 示例：

  sh
  SCHEDULE=@every 5m   # 每5分钟检查一次
  MAX_DURATION=2h      # 删除运行超过2小时的Pod
  

Unready（未就绪时长规则）

• 作用：删除未就绪超过指定时长的Pod。
• 启用方式：设置MAX_UNREADY为Go语言time.Duration格式。若Pod未就绪时间超过该值，则标记删除。
• 示例：

  sh
  SCHEDULE=@every 5m   # 每5分钟检查一次
  MAX_UNREADY=10m      # 删除未就绪超过10分钟的Pod
  

部署与使用指南

服务账户权限

pod-reaper依赖Kubernetes服务账户权限，需配置RBAC以允许列出和删除Pod（或使用驱逐API）。

命名空间级权限示例

yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  name: pod-reaper
  namespace: default
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: pod-reaper-role
  namespace: default
rules:
- apiGroups: [""]
  resources: ["pods"]
  verbs: ["get", "list", "delete"]  # 若启用EVICT，需添加"create"（用于创建Eviction）
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: pod-reaper-binding
  namespace: default
subjects:
- kind: ServiceAccount
  name: pod-reaper
  namespace: default
roleRef:
  kind: Role
  name: pod-reaper-role
  apiGroup: rbac.authorization.k8s.io

Kubernetes部署示例

长期运行（Deployment）

yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: pod-reaper
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: pod-reaper
  template:
    metadata:
      labels:
        app: pod-reaper
        pod-reaper: disabled  # 排除自身被删除
    spec:
      serviceAccountName: pod-reaper
      containers:
      - name: pod-reaper
        image: target/pod-reaper:latest
        env:
        - name: NAMESPACE
          value: "default"
        - name: SCHEDULE
          value: "@every 1m"
        - name: EXCLUDE_LABEL_KEY
          value: "pod-reaper"
        - name: EXCLUDE_LABEL_VALUES
          value: "disabled"
        - name: CHAOS_CHANCE
          value: ".005"  # 0.5%混沌概率

一次性运行（Pod）

yaml
apiVersion: v1
kind: Pod
metadata:
  name: pod-reaper-once
  labels:
    pod-reaper: disabled  # 排除自身
spec:
  serviceAccountName: pod-reaper
  restartPolicy: Never  # 一次性运行
  containers:
  - name: pod-reaper
    image: target/pod-reaper:latest
    env:
    - name: SCHEDULE
      value: "@every 30s"  # 每30秒检查一次
    - name: RUN_DURATION
      value: "15m"        # 运行15分钟后退出
    - name: CHAOS_CHANCE
      value: ".3"         # 30%混沌概率

规则组合使用

• 逻辑与：同一pod-reaper实例启用多个规则时，仅当Pod满足所有规则才会被删除。

  sh
  # 示例：删除运行超过2小时且未就绪超过10分钟的Pod
  MAX_DURATION=2h
  MAX_UNREADY=10m
  

• 逻辑或：需部署多个pod-reaper实例，每个实例配置单一规则。

  sh
  # 实例1：混沌概率规则
  CHAOS_CHANCE=.01
  # 实例2：运行时长规则
  MAX_DURATION=2h
  

注意事项

• 自我保护：务必通过EXCLUDE_LABEL为pod-reaper自身添加排除标签，避免自我删除。
• PDB兼容性：启用EVICT可尊重PodDisruptionBudget，适合生产环境。
• 权限控制：最小化服务账户权限，避免跨命名空间过度权限。
• 测试建议：首次使用时启用DRY_RUN=true验证规则效果，再实际执行删除。