Disruption Analyzer Feature Documentation
Overview
The Disruption Analyzer processes Kubernetes cluster data to identify nodes and workloads affected by disruption signals and eviction blockers. It consumes a snapshot of resources (nodes, pods, PDBs, ReplicaSets, workloads) and provides two core analyses:
- Node analysis: Detects Karpenter disruption taints, cordoned state, and pods blocking eviction via PDBs or annotations.
- Workload analysis: Determines per-workload pod counts, eviction status, capacity-type distribution (Spot vs. On-Demand), and PDB/annotation blockers.
This functionality underpins the K9s NoKill plugin by supplying structured status objects used by rich CLI views to inform operational decisions.
Architecture Overview
flowchart TB
subgraph "Data Access Layer"
K8sData[K8sData]
end
subgraph "Business Layer"
DA[DisruptionAnalyzer]
end
subgraph "Data Models"
NDS[NodeDisruptionStatus]
WDS[WorkloadDisruptionStatus]
end
K8sData --> DA
DA --> NDS
DA --> WDS
Component Structure
1. Data Access Layer
K8sData (nokill/k8s_client.py)
- Fetches and caches Kubernetes resources:
- Nodes, Pods, PodDisruptionBudgets
- Deployments, StatefulSets, DaemonSets, ReplicaSets, Jobs
- Exposes lists and a
node_mapfor lookups.
2. Business Layer
DisruptionAnalyzer 🛡️ (nokill/disruption.py)
- Purpose: Analyze disruption readiness and eviction blockers for nodes and workloads .
- Key Properties:
data: K8sData— snapshot of cluster resources.pods_by_node: Dict[str, List[Any]]— pods indexed by node name.pods_by_namespace: Dict[str, List[Any]]— pods indexed by namespace.pdbs_by_namespace: Dict[str, List[Any]]— PDBs indexed by namespace.replicaset_owner: Dict[(str,str), str]— maps ReplicaSet(namespace, name)to Deployment name.
- Key Methods:
__init__(data: K8sData) -> None
Initializes indexes by calling _index_pods, _index_pdbs, and _index_replicasets.
_index_pods() -> None
Builds pods_by_node and pods_by_namespace from data.pods.
_index_pdbs() -> None
Builds pdbs_by_namespace from data.pdbs.
_index_replicasets() -> None
Resolves ReplicaSet → Deployment ownership via owner_references.
is_node_disrupting(node: Any) -> bool
Returns True if node has a Karpenter disruption taint.
is_node_cordoned(node: Any) -> bool
Returns True if node.spec.unschedulable is set.
pdb_matches_labels(pdb: Any, labels: Dict[str,str]) -> bool
Implements matchLabels + matchExpressions semantics to test if a PDB applies to pod labels.
analyze_node(node_name: str) -> Optional[NodeDisruptionStatus]
Gathers pods on the node, filters out mirror/DaemonSet pods, detects do-not-disrupt annotations and blocking PDBs, and returns a status object.
_pod_belongs_to_workload(...) -> bool
Determines if a pod belongs to a workload by ownerReferences (Deployment, StatefulSet, DaemonSet, Job) or falls back to label selector.
analyze_workload(workload_obj: Any, kind: str) -> WorkloadDisruptionStatus
Selects pods for the workload, tallies Spot vs. On-Demand, counts evicting pods (nodes marked disrupting), detects annotations/PDB blockers, and returns a status wrapper.
3. Data Models
NodeDisruptionStatus (nokill/models.py)
| Property | Type | Description |
|---|---|---|
node |
Any | Original Kubernetes Node object |
is_disrupting |
bool | True if node has a disruption taint |
is_cordoned |
bool | True if node is unschedulable |
eviction_blocked |
bool | True if eviction is blocked by pods/PDBs |
blocking_pods |
List[Any] | Pods preventing eviction (annotations/PDB) |
WorkloadDisruptionStatus (nokill/models.py)
| Property | Type | Description |
|---|---|---|
workload |
WorkloadWrapper | Metadata wrapper for the workload object |
pods_count |
int | Number of pods matching the workload |
desired_replicas |
int | Target replica count (includes Jobs/DS/STs logic) |
spot_count |
int | Pods on Spot instances |
ondemand_count |
int | Pods on On-Demand instances |
evicting_count |
int | Pods on nodes marked disrupting |
pdbs |
List[Any] | All PDBs matching workload selector |
blocking_pdbs |
List[Any] | PDBs with disruptions_allowed == 0 |
has_do_not_disrupt |
bool | True if any pod has the do-not-disrupt annotation |
is_eviction_blocked (property) |
bool | True if PDBs block or annotation present |
WorkloadWrapper (nokill/models.py)
Wraps raw workload spec/status and exposes:
name,namespace,kindreplicas,ready_replicasselector_labels,template_labelscontainers- Underlying
objreference
Dependencies
- kubernetes client →
K8sDatafetches resources. - typing → static type annotations.
- Internal models (
NodeDisruptionStatus,WorkloadDisruptionStatus,WorkloadWrapper).
Testing Considerations
- Unit tests in
tests/test_disruption.pyverify:- PDB selector matching including matchExpressions.
- Do-not-disrupt annotation blocking.
- ReplicaSet→Deployment ownership resolution.
- Workload pod association fallback to selector when ownerReferences absent.
This analyzer forms the core business logic of the NoKill plugin, supplying structured disruption status objects used by CLI views for node, workload, and PDB reporting.