K9s NoKill Plugin Documentation

Overview

K9s NoKill is a K9s plugin that surfaces Kubernetes node and workload disruption readiness, combining Karpenter disruption signals with eviction blocker insights. It helps operators:

  • Identify which nodes are being disrupted or cordoned.
  • Understand eviction blockers (Pod Disruption Budgets and karpenter.sh/do-not-disrupt annotations).
  • See workload-level disruption status, including Spot vs. On-Demand distribution.

This plugin integrates seamlessly with K9s, exposing rich, color-coded reports via keyboard shortcuts. It fetches Kubernetes data using the Python client library and renders tables for fast in-terminal analysis .


K9s Configuration Files

These YAML snippets enhance K9s with aliases, views, hotkeys, and plugin commands.

Aliases (k9s/aliases.yml)

Defines shorthand commands for custom resource types:

Alias Resource
np karpenter.sh/v1/nodepools
nc karpenter.sh/v1/nodeclaims
ec2nc karpenter.k8s.aws/v1/ec2nodeclasses
aliases:
  np: karpenter.sh/v1/nodepools
  nc: karpenter.sh/v1/nodeclaims
  ec2nc: karpenter.k8s.aws/v1/ec2nodeclasses

Plugin Snippet (k9s/plugin.yml) 📋

Maps K9s shortcuts to the plugin’s commands, enabling:

  • Shift-W: Workload disruption report
  • Shift-N: Enriched node report
  • Shift-D: Single node detail
  • Shift-B: Node blocker detail
  • Shift-P: PDB detail for a selected workload
  • Shift-8: Filter workloads with do-not-disrupt=true
plugins:
  workload-disruption:
    shortCut: Shift-W
    description: Workload Disruption Report
    scopes: [all]
    command: env
    args:
      - HOME_DIR/.k9s/plugins/nokill/scripts/run.sh
      - workloads
      - --namespace
      - $NAMESPACE
  # … other plugin entries …

Views (k9s/views.yml) & Hotkeys (k9s/hotkeys.yml)

Customize table columns and navigation shortcuts in K9s:

views:
  v1/nodes:
    columns:
      - NODEPOOL:metadata.labels.karpenter\.sh/nodepool
      - FAMILY:metadata.labels.karpenter\.k8s\.aws/instance-family
      - SIZE:metadata.labels.karpenter\.k8s\.aws/instance-size
      - CAP-TYPE:metadata.labels.karpenter\.sh/capacity-type
      - DISRUPTING:spec.taints
hotKeys:
  shift-1:
    shortCut: Shift-1
    description: Nodes
    command: nodes
  # … other hotkey entries …

Installation & Execution

install.sh 🎉

Automates plugin setup:

  • Copies runtime code into ~/.k9s/plugins/nokill
  • Configures a Poetry venv (unless skipped)
  • Emits a K9s snippet in $XDG_CONFIG_HOME/k9s/plugins/nokill.yaml
#!/usr/bin/env bash
echo "Installing plugin code to: $HOME/.k9s/plugins/nokill"
cp -r nokill scripts pyproject.toml poetry.lock "$INSTALL_DIR/"
# … venv setup, snippet creation …
echo "Installation complete!"

scripts/run.sh 🚀

Entry point invoked by K9s and CLI:

  • Activates the in-project venv if present
  • Adds project root to PYTHONPATH
  • Pipes output through less -R -S -K for pager support
#!/usr/bin/env bash
if [ -d "$PROJECT_ROOT/.venv" ]; then source "$PROJECT_ROOT/.venv/bin/activate"; fi
export PYTHONPATH="$PROJECT_ROOT:${PYTHONPATH:-}"
python -m nokill "$@" | less -R -S -K

Package Metadata

pyproject.toml

Defines project metadata and dependencies:

Field Value
name k9s-nokill
version 0.1.0
requires-python >=3.10
dependencies kubernetes>=35,<36, rich>=13.9,<14, tabulate>=0.9,<0.10, pytest>=8,<9

Core Python Modules

Kubernetes Client (nokill/k8s_client.py) 🐳

Provides K8sData, which loads cluster credentials and fetches all needed resources:

class K8sData:
    """Fetches and caches all resources needed for disruption analysis."""
    def __init__(self, context: str | None = None, namespace: str | None = None) -> None:
        """Initialize K8s client and fetch resources."""
        # Try kubeconfig, then in-cluster config
        self.v1 = client.CoreV1Api()
        self.apps_v1 = client.AppsV1Api()
        self.batch_v1 = client.BatchV1Api()
        self.policy_v1 = client.PolicyV1Api()
        self.namespace = namespace
        self._fetch_all(namespace)

Methods

Method Signature Description
_list_all (_list_all(self, list_fn: Callable[..., Any], **kwargs) → List[Any]) Iterates paginated Kubernetes API calls (limit=500).
_fetch_all `(_fetch_all(self, namespace: str None) → None)`

Data Models (nokill/models.py) 📦

Encapsulate Kubernetes objects for reporting:

Class Responsibility
WorkloadWrapper Holds metadata, replica counts, labels, containers.
WorkloadDisruptionStatus Summary of pods, blockers, capacity-type counts.
NodeDisruptionStatus Node taint/cordon status and blocking pods.

Formatting Utilities (nokill/formatting.py) 🎨

Renders rich tables, panels, and status chips:

  • _get_console() configures a shared Rich Console.
  • status_chip(text, level) returns a colored badge.
  • print_header, print_kpis, print_rich_table, print_note wrap Rich and fallback to plain output.

Disruption Analysis (nokill/disruption.py) 🔍

DisruptionAnalyzer builds indices and inspects:

  1. Indexing

    • _index_pods(): maps pods by node and namespace
    • _index_pdbs(): groups PDBs by namespace
    • _index_replicasets(): ties ReplicaSets back to Deployments
  2. Node Checks

    • is_node_disrupting(node): looks for Karpenter disruption taints
    • is_node_cordoned(node): checks spec.unschedulable
  3. Workload Checks

    • pdb_matches_labels(pdb, labels): evaluates matchLabels and matchExpressions
    • analyze_node(node_name): gathers blocking pods for a node
    • analyze_workload(workload_obj, kind): tallies evicting pods, PDB blockers, and annotations
analyzer = DisruptionAnalyzer(K8sData(namespace="default"))
node_status = analyzer.analyze_node("node-1")
workload_status = analyzer.analyze_workload(deployment_obj, "Deployment")

View Renderers

Workload Report (nokill/views/workloads.py) 📊

  • parse_quantity: converts CPU/memory strings to floats
  • fmt_cpu, fmt_mem: format totals for display
  • render: filters workloads, computes KPIs, and prints a color-coded table of:

| TYPE | NAME | NAMESPACE | PODS | REQ-CPU | REQ-MEM | LIM-CPU | LIM-MEM | EVICTING | PDB-BLOCK | NO-DISRUPT | SPOT | ON-DEMAND |

Severity sorted: blockers first, then active evictions


Node Report (nokill/views/nodes.py) 🌳

  • _severity_rank: ranks nodes by disruption/blocking
  • render: builds a table of:

| NAME | STATUS | NODEPOOL | FAMILY | SIZE | CAP-TYPE | DISRUPTING | CORDONED | PODS | EVICT-BLOCKED | BLOCKED-BY |


Node Blocker Detail (nokill/views/node_blockers.py) 🛑

Lists pods blocking eviction on a specific node, noting:

  • Annotation-blocked pods
  • PDB-blocked pods

PDB Detail (nokill/views/pdb_detail.py) 📋

Shows, for a selected workload:

  • Matched PDBs
  • Min/Max unavailable
  • Allowed vs. expected disruptions

Testing

Key Test Suites

Test File Focus
tests/test_disruption.py DisruptionAnalyzer logic with mock fixtures
tests/test_formatting.py Formatting fallbacks and status chips
tests/test_install.py Installer script behavior and snippet creation
tests/test_views_render.py Smoke tests for view renderers

Fixtures use SimpleNamespace to simulate Kubernetes objects and verify analysis outcomes .


Dependencies

  • kubernetes 35.x
  • rich 13.x
  • tabulate, pyyaml, pytest

All specified in pyproject.toml under [project] fileciteturn0file?.


This documentation covers the K9s NoKill plugin’s configuration, installation, data ingestion, analysis, and rendering layers, illustrating how each component contributes to a unified disruption-readiness reporting tool.