PDB Detail Feature Documentation
Overview
The PDB Detail feature renders a detailed view of Pod Disruption Budgets (PDBs) associated with a specific Kubernetes workload. Users invoke this view within K9s to see which PDBs match a given deployment, statefulset, or daemonset, and whether any are currently blocking pod evictions. This helps operators quickly identify disruption blockers at the workload level.
This view integrates into the broader k9s-nokill plugin, which provides disruption-readiness insights across nodes and workloads. By combining PDB details with eviction status, it adds valuable context to capacity management and maintenance workflows.
Architecture Overview
flowchart TB
subgraph PresentationLayer [Presentation Layer]
PDBDetailView[PDB Detail View]
end
subgraph BusinessLayer [Business Layer]
Analyzer[DisruptionAnalyzer]
end
subgraph DataAccessLayer [Data Access Layer]
K8sData[K8sData]
end
PDBDetailView --> Analyzer
Analyzer --> K8sData
K8sData --> KubernetesAPI[Kubernetes API]
Component Structure
1. Presentation Layer
PDB Detail View (nokill/views/pdb_detail.py)
-
Purpose and responsibilities
The view locates the target workload, invokes disruption analysis, and renders a header, key metrics, and a table of matching PDBs with styling to highlight blocked budgets. -
Key Imports
DisruptionAnalyzerfrom business layer- Formatting utilities:
print_header,print_kpis,print_note,print_rich_table,status_chip
-
Key Function
def render( analyzer: DisruptionAnalyzer, namespace: str, name: str, kind: str ) -> None: """Render PDB details for a workload.""" ...- Identifies workload by
namespace,name, andkind. - Calls
analyzer.analyze_workload(...). - Prints a panel header
"PDB Detail"and workload info. - Displays KPIs: matched PDBs, blocking PDBs, pod count vs. desired replicas.
- If no PDBs are found, issues a warning note.
- Otherwise, builds a table with columns PDB NAME, MIN AVAIL, MAX UNAVAIL, ALLOWED, and EXPECTED, styling rows red when
allowed == 0.
- Identifies workload by
2. Business Layer
DisruptionAnalyzer (nokill/disruption.py)
-
Purpose
Encapsulates logic to analyze disruptions, including matching pods to PDBs and assessing blocking conditions. -
Key Method
Method Description Returns analyze_workload Compute disruption status for the given workload object, returning matched and blocking PDBs along with pod counts and eviction signals. WorkloadDisruptionStatus
3. Data Access Layer
K8sData (nokill/k8s_client.py)
-
Purpose
Fetches and caches Kubernetes resources required for disruption analysis: nodes, pods, PDBs, deployments, statefulsets, daemonsets, replicasets, and jobs. -
Methods
Method Description Caching Citation __init__Initialize API clients and invoke _fetch_allto load data.Stores all resources in instance fields _list_allIteratively retrieve all pages for a Kubernetes list call. None (per-call iteration) _fetch_allInvoke specific list calls (e.g., list_node,list_pod_disruption_budget,list_pod, workload lists) to populate cached attributes.Writes to self.nodes,self.pods, etc.
4. Data Models
WorkloadDisruptionStatus
The analyze_workload method returns this status model, capturing metrics and PDB associations:
| Property | Type | Description |
|---|---|---|
workload |
WorkloadWrapper |
Wrapped object with metadata and spec details. |
pods_count |
int |
Number of pods belonging to the workload. |
desired_replicas |
int |
Expected replica count (or parallelism). |
spot_count |
int |
Count of pods on Spot instances. |
ondemand_count |
int |
Count of pods on On-Demand instances. |
evicting_count |
int |
Number of pods currently marked for eviction. |
pdbs |
List[Any] |
All PDB objects matching workload selectors. |
blocking_pdbs |
List[Any] |
Subset of pdbs where disruptions_allowed == 0. |
has_do_not_disrupt |
bool |
True if any pod has the karpenter.sh/do-not-disrupt annotation. |
Feature Flows
Primary Flow: Render PDB Detail
sequenceDiagram
participant U as User
participant S as run.sh
participant CLI as Nokill CLI
participant Data as K8sData
participant Analyzer as DisruptionAnalyzer
participant View as PDBDetailView
U->>S: Trigger PDB Detail (Shift-P)
S->>CLI: Invoke `nokill pdb-detail --namespace N --name X --kind Y`
CLI->>Data: initialize(`<context>`, namespace)
Data-->>CLI: cached resources
CLI->>Analyzer: analyze_workload(workload, kind)
Analyzer->>Data: query pods, PDBs, selectors
Analyzer-->>View: WorkloadDisruptionStatus
View->>Console: print_header, print_kpis, print_rich_table
Integration Points
- Mapped in K9s plugin configuration: Press Shift-P on a workload to launch PDB Detail .
Key Classes Reference
| Class | Location | Responsibility |
|---|---|---|
| PDB Detail View | nokill/views/pdb_detail.py |
Presentation: render table of PDBs for workload. |
| DisruptionAnalyzer | nokill/disruption.py |
Business logic for disruption analysis. |
| K8sData | nokill/k8s_client.py |
Data access: fetch and cache Kubernetes objects. |
| WorkloadDisruptionStatus | nokill/models.py |
Model encapsulating workload disruption metrics. |
| Formatting Utilities | nokill/formatting.py |
Console output helpers: tables, panels, chips. |
Error Handling
- If the specified workload is not found, the view prints an error note and returns early.
- If no matching PDBs exist, a warning note is displayed.
{
"title": "Workload Not Found",
"content": "The view prints an error note when the specified workload cannot be located."
}
Caching Strategy
- On initialization,
K8sDatafetches all relevant resources once (nodes, pods, PDBs, workloads) and retains them in-memory for the duration of the CLI invocation.
Dependencies
- kubernetes client
- rich for formatted console output
- tabulate as a plain-text fallback
- pyyaml, pytest, poetry for development and testing
Testing Considerations
- Smoke test in
tests/test_views_render.pyvalidates that invokingpdb_detail.renderprints the"PDB Detail"header and includes the workload identifier. - Unit tests for
DisruptionAnalyzerconfirm correct matching of PDB selectors and annotation handling.