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_map for 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, kind
  • replicas, ready_replicas
  • selector_labels, template_labels
  • containers
  • Underlying obj reference

Dependencies

  • kubernetes client → K8sData fetches resources.
  • typing → static type annotations.
  • Internal models (NodeDisruptionStatus, WorkloadDisruptionStatus, WorkloadWrapper).

Testing Considerations

  • Unit tests in tests/test_disruption.py verify:
    • 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.