📋 Node Blocker Detail Feature Documentation

Overview

The Node Blocker Detail view presents eviction blocker information for a single Kubernetes node. It helps operators understand why a node cannot be drained by listing pods that prevent eviction. This detail view is part of the NoKill plugin for K9s, which surfaces Karpenter disruption signals and eviction blockers in a concise console UI.

In practice, when a user requests node blocker details (e.g., via Shift-B in K9s), the plugin invokes this view. It queries the disruption analyzer for the selected node, displays overall disruption status and eviction block state, then enumerates each blocking pod with its reason.

Architecture Overview

sequenceDiagram
    participant K9sPlugin as NoKill Plugin
    participant View as node_blockers.render
    participant Analyzer as DisruptionAnalyzer
    participant Formatter as Formatting Module

    K9sPlugin->>View: invoke render(analyzer, node_name)
    View->>Analyzer: analyze node
    Analyzer-->>View: return NodeStatus
    alt status missing
        View->>Formatter: print_note (error)
    else
        View->>Formatter: print_header
        View->>Formatter: print_kpis
        alt has blocking pods
            loop per pod
                View->>Analyzer: fetch PDBs & match labels
            end
            View->>Formatter: print_rich_table
        else
            View->>Formatter: print_note (info)
        end
    end

Component Structure

Presentation Layer

node_blockers.render (nokill/views/node_blockers.py)

  • Purpose

Renders eviction blocker details for a specific node to the console.

  • Key Parameters
    • analyzer: Instance of DisruptionAnalyzer.
    • node_name: str – name of the node to inspect.
  • Behavior
    1. Retrieve NodeStatus via analyzer.analyze_node(node_name).
    2. If missing, emit an error note and exit.
    3. Print detail header and key performance indicators (KPIs).
    4. If blocking pods exist, build and render a styled table; otherwise print an informational note.

Business Layer

The view relies on the DisruptionAnalyzer to supply analysis and grouping data:

  • analyze_node(node_name: str) → NodeStatus | None

Provides a summary of whether the node is disrupting and if eviction is blocked, plus the list of blocking pods.

  • pdbs_by_namespace

Mapping of namespace → list of PodDisruptionBudget objects for label matching.

  • pdb_matches_labels(pdb, labels: dict) → bool

Determines if a PDB applies to a given pod’s labels.

Dependencies

Module Responsibility
..disruption.DisruptionAnalyzer Business logic for disruption and blocker analysis
..formatting Console formatting: headers, KPI cards, tables, status chips

Function Reference

Function Signature Description
render (analyzer: DisruptionAnalyzer, node_name: str) → None Print the “Node Blocker Detail” view.

render()

Signature

def render(analyzer: DisruptionAnalyzer, node_name: str) -> None

Execution Steps

  • Call analyzer.analyze_node(node_name).
  • If result is None:
    • print_note(f"Node {node_name} not found.", "error")
    • Return.
  • Display header with node name.
  • Render three KPI cards:
    • Disrupting: YES/NO with error/ok chip.
    • Eviction Blocked: YES/NO with error/ok chip.
    • Blocking Pods: count of pods.
  • If no blocking pods:
    • print_note("No blocking pods found.", "info")
    • Return.
  • For each blocking pod:
    • If annotation karpenter.sh/do-not-disrupt=true present:
      • Reason chip: Annotation (warn)
      • Details: the annotation key
      • Row style: yellow
    • Else:
      • Reason chip: PDB (error)
      • Collect matching PDB names with zero allowed disruptions.
      • Details: comma-separated PDB names
      • Row style: bold red
  • Render a rich table with columns POD, NAMESPACE, REASON, DETAILS.

Key Snippet

status = analyzer.analyze_node(node_name)
if not status:
    print_note(f"Node {node_name} not found.", "error")
    return

print_header("Node Blocker Detail", f"Node: {node_name}")
print_kpis([
    ("Disrupting", status_chip("YES", "error") if status.is_disrupting else status_chip("NO", "ok")),
    ("Eviction Blocked", status_chip("YES", "error") if status.eviction_blocked else status_chip("NO", "ok")),
    ("Blocking Pods", str(len(status.blocking_pods))),
])
if not status.blocking_pods:
    print_note("No blocking pods found.", "info")
    return
# Build rows for each blocking pod...
print_rich_table(
    ["POD", "NAMESPACE", "REASON", "DETAILS"],
    rows,
    row_styles=row_styles,
)

Output Structure

Section Description
Header Title “Node Blocker Detail” with subtitle showing node name
KPI Cards Summary cards for disrupting, eviction-blocked, and blocker count
Blocking Table List of pods blocking eviction with reasons and details
Notes Informational or error notes when no data or on lookup failure

Error Handling

{
    "title": "Node Not Found",
    "content": "If the analyzer returns no status, the view prints an error note and exits without further output."
}

Testing Considerations

  • test_detail_views_render in tests/test_views_render.py verifies:
    • The header Node Blocker Detail appears.
    • KPI values reflect analyzer state.
    • Pod-level details render correctly for annotated and PDB-blocked pods.

Key Classes & Methods Reference

Class / Function Location Responsibility
render nokill/views/node_blockers.py Entry point for rendering node blocker details
DisruptionAnalyzer nokill/disruption.py Supplies node eviction and disruption analysis
print_header nokill/formatting.py Renders section headers in console
print_kpis nokill/formatting.py Renders KPI cards
print_rich_table nokill/formatting.py Renders styled tables
status_chip nokill/formatting.py Creates colored status indicators

This documentation covers all functionality present in nokill/views/node_blockers.py without extrapolation beyond the source code.