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

    • DisruptionAnalyzer from 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, and kind.
    • 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.

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_all to load data. Stores all resources in instance fields
    _list_all Iteratively retrieve all pages for a Kubernetes list call. None (per-call iteration)
    _fetch_all Invoke 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, K8sData fetches 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.py validates that invoking pdb_detail.render prints the "PDB Detail" header and includes the workload identifier.
  • Unit tests for DisruptionAnalyzer confirm correct matching of PDB selectors and annotation handling.