Workload Disruption Report Feature Documentation

Overview

The Workload Disruption Report renders a summary of Kubernetes workloads’ eviction risk and resource footprints. It aggregates Pod Disruption Budgets (PDBs), “do-not-disrupt” annotations, and node disruption signals to highlight workloads blocking cluster maintenance. This feature empowers operators to quickly identify at-risk deployments, statefulsets, daemonsets, and jobs.

By integrating with the DisruptionAnalyzer, it fits into the K9s NoKill plugin as the workloads view. The report outputs rich tables and key metrics, aiding decisions on node draining and capacity management.

Architecture Overview

flowchart TB
    subgraph PresentationLayer [Presentation Layer]
        WorkloadsView["Workloads View - workloads.render"]
        Formatting["Formatting Module"]
    end
    subgraph BusinessLayer [Business Layer]
        Analyzer["DisruptionAnalyzer analyze_workload"]
    end
    subgraph DataAccessLayer [Data Access Layer]
        K8sClient["K8sClient list resources"]
    end
    WorkloadsView -->|analyze_workload| Analyzer
    Analyzer -->|fetch data| K8sClient
    WorkloadsView -->|print tables & notes| Formatting

Component Structure

1. Presentation Layer

Workloads View (nokill/views/workloads.py)

  • Purpose:

    • Compute per-workload disruption status
    • Aggregate resource requests and limits
    • Render a rich table of workloads and top blockers
  • Key Functions:

Function Signature Description
parse_quantity `parse_quantity(q: str float
fmt_cpu fmt_cpu(cores: float) → str Format CPU cores to “m” or two-decimal places.
fmt_mem fmt_mem(byte_count: float) → str Format memory bytes to Ki/Mi/Gi units.
_severity_rank 🛠️ _severity_rank(is_blocked: bool, evicting_count: int) → int Assign severity based on blocking and eviction.
render `render(analyzer: DisruptionAnalyzer, namespace: str None, type_filter: str

Function Details

def parse_quantity(q: str | float | None) -> float:
    """Parse Kubernetes resource quantity string."""
  • Handles suffixes: m, Ki, Mi, Gi, Ti.
  • Falls back to float conversion or 0.0.
def fmt_cpu(cores: float) -> str:
    """Format CPU cores for display."""
  • Below 1 core: outputs in m (millicores).
  • Otherwise two-decimal representation.
def fmt_mem(byte_count: float) -> str:
    """Format memory bytes for display."""
  • Formats bytes into Ki, Mi, or Gi with appropriate precision.
def _severity_rank(*, is_blocked: bool, evicting_count: int) -> int:
    """Determine display ranking for sorting workloads."""
  • Returns 0 (most severe) to 3 (no issues).
def render(
    analyzer: DisruptionAnalyzer,
    namespace: str | None = None,
    type_filter: str | None = None,
    name_filter: str | None = None,
    do_not_disrupt_only: bool = False,
) -> None:
    """Render workload disruption status."""
  1. Collect workloads by kind (Deploy, Sts, DS, Job).
  2. Filter by namespace, type_filter, name_filter.
  3. Analyze each workload via analyzer.analyze_workload.
  4. Compute total requests, limits, eviction and blocker chips.
  5. Sort by severity and namespace/name.
  6. Print header, KPIs, and main table.
  7. Show top 5 blockers or relevant note.

2. Business Layer

DisruptionAnalyzer (nokill/disruption.py)

  • Role: Provides analyze_workload to assess:
    • Pod counts vs desired replicas
    • Spot vs On-Demand distribution
    • Eviction counts and PDB blockers
    • “Do-not-disrupt” annotations
  • Key Return:
    • WorkloadDisruptionStatus containing metrics and blocker lists.

3. Data Access Layer

K8sClient (nokill/k8s_client.py)

  • Role: Fetch Kubernetes resources for all namespaces or a specific one:
    • Pods, PDBs, Deployments, StatefulSets, DaemonSets, ReplicaSets, Jobs
  • Supplies data maps to DisruptionAnalyzer.

4. Data Models

WorkloadDisruptionStatus (nokill/models.py)

Property Type Description
workload WorkloadWrapper Wrapped workload metadata and spec.
pods_count int Number of selected pods.
desired_replicas int Expected replica count.
spot_count int Pods on spot nodes.
ondemand_count int Pods on on-demand nodes.
evicting_count int Pods currently being evicted.
pdbs List[Any] Matching Pod Disruption Budgets.
blocking_pdbs List[Any] PDBs with zero allowed disruptions.
has_do_not_disrupt bool True if any pod has the annotation.

WorkloadWrapper (nokill/models.py)

Property Type Description
name str Workload name.
namespace str Kubernetes namespace.
kind str Original kind string (e.g., “Deploy”).
replicas int Specified replica count.
ready_replicas int Number of ready pods.
selector_labels Dict[str, str] Label selector from spec.
template_labels Dict[str, str] Pod template labels.
containers List[Any] Container specs for resource totals.
obj Any Original Kubernetes object.

Feature Flow

Render Workload Disruption Report

sequenceDiagram
    participant U as User (K9s)
    participant V as WorkloadsView
    participant B as DisruptionAnalyzer
    participant D as K8sClient
    participant F as Formatting

    U->>V: Trigger workloads.render
    V->>B: analyze_workload(workload_obj, kind)
    B->>D: list pods, deployments, pdbs
    D-->>B: return resource lists
    B-->>V: return WorkloadDisruptionStatus
    V->>F: print_header, print_kpis, print_rich_table
    V-->>U: display report

Key Classes Reference

Class Location Responsibility
WorkloadsView (render) nokill/views/workloads.py CLI rendering of workload disruption report
DisruptionAnalyzer nokill/disruption.py Business logic for disruption analysis
K8sClient nokill/k8s_client.py Data access for Kubernetes resources
WorkloadDisruptionStatus nokill/models.py Model holding analysis results
WorkloadWrapper nokill/models.py Wrapper for workload metadata and spec

Testing Considerations

  • Smoke Tests:
    • Verify header presence ("Workload Disruption Report", "Top blockers").
    • Ensure filtering by do_not_disrupt_only includes jobs ("cleanup").
  • Data Fixtures:
    • Mock deployments, jobs, pods, PDBs, and node annotations to validate table rows and styles.