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-disruptannotations). - 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 -Kfor 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 RichConsole.status_chip(text, level)returns a colored badge.print_header,print_kpis,print_rich_table,print_notewrap Rich and fallback to plain output.
Disruption Analysis (nokill/disruption.py) 🔍
DisruptionAnalyzer builds indices and inspects:
-
Indexing
_index_pods(): maps pods by node and namespace_index_pdbs(): groups PDBs by namespace_index_replicasets(): ties ReplicaSets back to Deployments
-
Node Checks
is_node_disrupting(node): looks for Karpenter disruption taintsis_node_cordoned(node): checksspec.unschedulable
-
Workload Checks
pdb_matches_labels(pdb, labels): evaluatesmatchLabelsandmatchExpressionsanalyze_node(node_name): gathers blocking pods for a nodeanalyze_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 floatsfmt_cpu,fmt_mem: format totals for displayrender: 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/blockingrender: 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] fileciteturn0file?.
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.