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
floatconversion or0.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, orGiwith appropriate precision.
def _severity_rank(*, is_blocked: bool, evicting_count: int) -> int:
"""Determine display ranking for sorting workloads."""
- Returns
0(most severe) to3(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."""
- Collect workloads by kind (Deploy, Sts, DS, Job).
- Filter by
namespace,type_filter,name_filter. - Analyze each workload via
analyzer.analyze_workload. - Compute total requests, limits, eviction and blocker chips.
- Sort by severity and namespace/name.
- Print header, KPIs, and main table.
- Show top 5 blockers or relevant note.
2. Business Layer
DisruptionAnalyzer (nokill/disruption.py)
- Role: Provides
analyze_workloadto assess:- Pod counts vs desired replicas
- Spot vs On-Demand distribution
- Eviction counts and PDB blockers
- “Do-not-disrupt” annotations
- Key Return:
WorkloadDisruptionStatuscontaining 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_onlyincludes jobs ("cleanup").
- Verify header presence (
- Data Fixtures:
- Mock deployments, jobs, pods, PDBs, and node annotations to validate table rows and styles.