descheduler/pkg/framework/plugins/podlifetime/README.md

PodLifeTime Plugin

What It Does

The PodLifeTime plugin evicts pods that have been running for too long. You can configure a maximum age threshold, and the plugin evicts pods older than that threshold. The oldest pods are evicted first.

How It Works

The plugin examines all pods across your nodes and selects those that exceed the configured age threshold. You can further narrow down which pods are considered by specifying:

• Which namespaces to include or exclude
• Which labels pods must have
• Which states pods must be in (e.g., Running, Pending, CrashLoopBackOff)

Once pods are selected, they are sorted by age (oldest first) and evicted in that order. Eviction stops when limits are reached (per-node limits, total limits, or Pod Disruption Budget constraints).

Use Cases

• Resource Leakage Mitigation: Restart long-running pods that may have accumulated memory leaks, stale cache, or resource leaks

  args:
    maxPodLifeTimeSeconds: 604800  # 7 days
    states: [Running]
  

• Ephemeral Workload Cleanup: Remove long-running batch jobs, test pods, or temporary workloads that have exceeded their expected lifetime

  args:
    maxPodLifeTimeSeconds: 7200  # 2 hours
    states: [Succeeded, Failed]
  

• Node Hygiene: Remove forgotten or stuck pods that are consuming resources but not making progress

  args:
    maxPodLifeTimeSeconds: 3600  # 1 hour
    states: [CrashLoopBackOff, ImagePullBackOff, ErrImagePull]
    includingInitContainers: true
  

• Config/Secret Update Pickup: Force pod restart to pick up updated ConfigMaps, Secrets, or environment variables

  args:
    maxPodLifeTimeSeconds: 86400  # 1 day
    states: [Running]
    labelSelector:
      matchLabels:
        config-refresh: enabled
  

• Security Rotation: Periodically refresh pods to pick up new security tokens, certificates, or patched container images

  args:
    maxPodLifeTimeSeconds: 259200  # 3 days
    states: [Running]
    namespaces:
      exclude: [kube-system]
  

• Dev/Test Environment Cleanup: Automatically clean up old pods in development or staging namespaces

  args:
    maxPodLifeTimeSeconds: 86400  # 1 day
    namespaces:
      include: [dev, staging, test]
  

• Cluster Health Freshness: Ensure pods periodically restart to maintain cluster health and verify workloads can recover from restarts

  args:
    maxPodLifeTimeSeconds: 604800  # 7 days
    states: [Running]
    namespaces:
      exclude: [kube-system, production]
  

• Rebalancing Assistance: Work alongside other descheduler strategies by removing old pods to allow better pod distribution

  args:
    maxPodLifeTimeSeconds: 1209600  # 14 days
    states: [Running]
  

• Non-Critical Stateful Refresh: Occasionally reset tolerable stateful workloads that can handle data loss or have external backup mechanisms

  args:
    maxPodLifeTimeSeconds: 2592000  # 30 days
    labelSelector:
      matchLabels:
        stateful-tier: cache
  

Configuration

Parameter	Description	Type	Required	Default
maxPodLifeTimeSeconds	Pods older than this many seconds are evicted	uint	Yes	-
namespaces	Limit eviction to specific namespaces (or exclude specific namespaces)	Namespaces	No	nil
labelSelector	Only evict pods matching these labels	metav1.LabelSelector	No	nil
states	Only evict pods in specific states (e.g., Running, CrashLoopBackOff)	[]string	No	nil
includingInitContainers	When checking states, also check init container states	bool	No	false
includingEphemeralContainers	When checking states, also check ephemeral container states	bool	No	false

Discovering states

Each pod is checked for the following locations to discover its relevant state:

1. Pod Phase - The overall pod lifecycle phase:

   • Running - Pod is running on a node
   • Pending - Pod has been accepted but containers are not yet running
   • Succeeded - All containers terminated successfully
   • Failed - All containers terminated, at least one failed
   • Unknown - Pod state cannot be determined

2. Pod Status Reason - Why the pod is in its current state:

   • NodeAffinity - Pod cannot be scheduled due to node affinity rules
   • NodeLost - Node hosting the pod is lost
   • Shutdown - Pod terminated due to node shutdown
   • UnexpectedAdmissionError - Pod admission failed unexpectedly

3. Container Waiting Reason - Why containers are waiting to start:

   • PodInitializing - Pod is still initializing
   • ContainerCreating - Container is being created
   • ImagePullBackOff - Image pull is failing and backing off
   • CrashLoopBackOff - Container is crashing repeatedly
   • CreateContainerConfigError - Container configuration is invalid
   • ErrImagePull - Image cannot be pulled
   • CreateContainerError - Container creation failed
   • InvalidImageName - Image name is invalid

By default, only regular containers are checked. Enable includingInitContainers or includingEphemeralContainers to also check those container types.

Example

apiVersion: descheduler/v1alpha2
kind: DeschedulerPolicy
profiles:
  - name: default
    plugins:
      deschedule:
        enabled:
          - name: PodLifeTime
    pluginConfig:
      - name: PodLifeTime
        args:
          maxPodLifeTimeSeconds: 86400  # 1 day
          namespaces:
            include:
              - default
          states:
            - Running

This configuration evicts Running pods in the default namespace that are older than 1 day.