Node Disruption Report Feature Documentation

Overview

The Node Disruption Report view provides a concise, ranked table of Kubernetes nodes with their disruption status. It helps users quickly identify:

  • Which nodes are currently being disrupted by Karpenter.
  • Which nodes have eviction blocked by PodDisruptionBudgets (PDBs) or “do-not-disrupt” annotations.
  • Key metrics like total nodes, disrupting nodes, and blocked nodes.

This feature integrates into the K9s NoKill plugin to surface disruption readiness information directly within the K9s interface, enhancing operational visibility and accelerating troubleshooting.

Architecture Overview

flowchart TB
    subgraph PresentationLayer [Presentation Layer]
        NodesView[nokill/views/nodes.py: render]
    end
    subgraph BusinessLayer [Business Layer]
        Analyzer[DisruptionAnalyzer]
    end
    subgraph UtilityLayer [Utilities]
        Formatting[formatting module]
    end
    NodesView --> Analyzer
    NodesView --> Formatting
    Analyzer --> K8sData[K8sData client]

Component Structure

1. Presentation Layer

NodesView (nokill/views/nodes.py)

  • Purpose
    Renders the node disruption report, including ranking, filtering, and formatted output.

  • Key Imports

    • DisruptionAnalyzer from the business layer
    • Formatting helpers: now_label, print_header, print_kpis, print_note, print_rich_table, status_chip
  • Key Functions

    1. _severity_rank

      def _severity_rank(is_disrupting: bool, is_blocked: bool) -> int
      
      • Assigns a numeric rank for sorting:
        • 0: disrupting and blocked
        • 1: blocked only
        • 2: disrupting only
        • 3: neither
    2. render

      def render(analyzer: DisruptionAnalyzer, node_name_filter: str | None = None) -> None
      
      • Responsibilities
        • Optionally filter nodes by name.
        • Analyze each node’s disruption status via analyzer.analyze_node.
        • Collect labels (nodepool, family, size, cap_type) and pod counts.
        • Build a list of blocking reasons (PDBs vs. do-not-disrupt annotations).
        • Tally key metrics: total nodes, disrupting nodes, blocked nodes, and both.
        • Sort rows by severity and name.
        • Render header, KPIs, and a styled rich table.
        • Show a warning note if no nodes match the filter.

2. Business Layer

DisruptionAnalyzer (nokill/disruption.py)

  • Role
    Provides analyze_node(node_name) to yield a NodeDisruptionStatus model containing:
    • is_disrupting
    • eviction_blocked
    • is_cordoned
    • blocking_pods (list of pod objects)

Full implementation not shown here; it indexes K8s resources and evaluates taints, cordon state, PDBs, and annotations.

3. Utilities

Formatting Module (nokill/formatting.py)

  • Helpers Used
    • now_label() – Generates a timestamp.
    • print_header(title, subtitle) – Renders a panel header.
    • print_kpis(kpi_pairs) – Displays key metrics in one row.
    • print_rich_table(columns, rows, row_styles) – Outputs a styled table or fallback.
    • status_chip(text, level) – Returns a colored status indicator.

These ensure consistent, color-rich output suitable for K9s’s pager.

Feature Flow

Node Disruption Report Generation

sequenceDiagram
    participant U as User (K9s)
    participant V as NodesView
    participant A as DisruptionAnalyzer
    participant F as Formatting
    U-->>V: Trigger "Shift-N" (nodes) command
    V->>A: analyze_node for each cluster node
    A-->>V: NodeDisruptionStatus for each node
    V->>F: print_header, print_kpis
    V->>F: print_rich_table with sorted rows/styles
    F-->>U: Display styled table in pager

Integration Points

  • K9s Plugin Snippet (k9s/plugin.yml):
    Binds the nodes command to Shift-N, invoking the render function.
  • Views Configuration (k9s/views.yml):
    Defines additional Kubernetes view columns for enriched node data alongside this report.

Key Functions Reference

Function Location Responsibility
_severity_rank nokill/views/nodes.py Compute sorting rank based on disruption and blocking.
render nokill/views/nodes.py Generate and print the node disruption report.
analyze_node nokill/disruption.py Assess a single node’s disruption status.
status_chip nokill/formatting.py Produce colored status badges for table cells.
print_rich_table nokill/formatting.py Render a formatted table with optional styling.

Dependencies

  • Internal
    • DisruptionAnalyzer for business logic.
    • Formatting utilities for terminal output.
  • External
    • Kubernetes Python client to fetch node data.
    • Rich and Tabulate libraries for styling and fallback.

Testing Considerations

  • Smoke Test

    • test_workloads_and_nodes_render_have_headers in tests/test_views_render.py verifies that invoking nodes.render(...) outputs the “Node Disruption Report” header alongside other report elements.
  • Filter Behavior

    • Supplying --node <name> to the render function limits output to the matching node. Non-matching filters trigger a warning note.

This documentation covers all code constructs present in nokill/views/nodes.py and its immediate dependencies, without external assumptions.