Disruption Data Models Feature Documentation

Overview

The nokill/models.py module defines the core data models used throughout the disruption analysis logic. These classes act as plain‐old Python data containers, providing structured access to:

  • Workload metadata and runtime state (via WorkloadWrapper).
  • Per‐workload disruption results, including eviction blockers and capacity counts (WorkloadDisruptionStatus).
  • Per‐node disruption results, detailing if a node is cordoned or blocking eviction (NodeDisruptionStatus).

Together, these models power reporting views in the Nokill K9s plugin, enabling consistent table rendering and status computation across nodes and workloads.

Architecture Overview

classDiagram
    class WorkloadWrapper {
        +str name
        +str namespace
        +str kind
        +int replicas
        +int ready_replicas
        +Dict selector_labels
        +Dict template_labels
        +List containers
        +Any obj
    }

    class WorkloadDisruptionStatus {
        +WorkloadWrapper workload
        +int pods_count
        +int desired_replicas
        +int spot_count
        +int ondemand_count
        +int evicting_count
        +List pdbs
        +List blocking_pdbs
        +bool has_do_not_disrupt
        +bool is_eviction_blocked()
    }

    class NodeDisruptionStatus {
        +Any node
        +bool is_disrupting
        +bool is_cordoned
        +bool eviction_blocked
        +List blocking_pods
    }

    WorkloadDisruptionStatus --> WorkloadWrapper

This class diagram shows how the workload disruption status embeds a WorkloadWrapper, and how node and workload statuses stand alone.

Component Structure

Data Models 📦

WorkloadWrapper (nokill/models.py)

A simple container for Kubernetes workload details, used as input to disruption analysis.

  • Purpose: Holds identifying and specification data from a workload object.
  • Properties:
Name Type Description
name str Workload resource name.
namespace str Kubernetes namespace of the workload.
kind str Resource kind (e.g., Deployment, Job).
replicas int Desired total replicas or parallelism.
ready_replicas int Currently ready replicas.
selector_labels Dict[str, str] Label selectors for matching pods.
template_labels Dict[str, str] Pod template labels from the workload spec.
containers List[Any] List of container specs in the pod template.
obj Any Original Kubernetes API object.

WorkloadDisruptionStatus (nokill/models.py)

Captures computed disruption metrics and blockers for a given workload.

  • Purpose: Represents results of analyzing one workload for eviction readiness.
  • Properties:
Name Type Description
workload WorkloadWrapper Wrapped workload metadata.
pods_count int Number of pods currently running for this workload.
desired_replicas int Expected pod count according to spec.
spot_count int Pods scheduled on spot capacity nodes.
ondemand_count int Pods scheduled on on-demand capacity nodes.
evicting_count int Number of pods currently being evicted/disrupted.
pdbs List[Any] All matching PodDisruptionBudget objects.
blocking_pdbs List[Any] Subset of pdbs with zero allowed disruptions.
has_do_not_disrupt bool True if any pod carries the do-not-disrupt annotation.
  • Computed Property:

    @property
    def is_eviction_blocked(self) -> bool:
        """Check if eviction is blocked by PDBs or annotations."""
        return bool(self.blocking_pdbs) or self.has_do_not_disrupt
    

NodeDisruptionStatus (nokill/models.py)

Holds disruption state for a single node instance.

  • Purpose: Summarizes whether a node is in disruption and what pods block eviction.
  • Properties:
Name Type Description
node Any Original Kubernetes Node object.
is_disrupting bool True if the node is currently marked as disrupting.
is_cordoned bool True if the node is cordoned (unschedulable).
eviction_blocked bool True if eviction is blocked by any pod.
blocking_pods List[Any] List of Pod objects preventing eviction.

Key Classes Reference

Class Location Responsibility
WorkloadWrapper nokill/models.py Encapsulate workload metadata for analysis.
WorkloadDisruptionStatus nokill/models.py Store per-workload disruption metrics and blockers.
NodeDisruptionStatus nokill/models.py Store per-node disruption state and blocking pods.

Dependencies 🔧

  • dataclasses: Provides the @dataclass decorator for boilerplate-free models.
  • typing: Defines generic types (Dict, List, Any) for model annotations.

Testing Considerations

  • Models are plain data holders; unit tests can create instances with mock values.
  • Verify is_eviction_blocked toggles correctly when blocking_pdbs or has_do_not_disrupt change.
  • Ensure fields map accurately from DisruptionAnalyzer outputs into these dataclasses.