The Complete K9s Cheatsheet

K9s is a powerful terminal-based UI for managing Kubernetes clusters. This comprehensive cheatsheet covers everything you need to know for efficient cluster navigation and management.

Getting Started

Installation Options

# Go
go install github.com/derailed/k9s@latest

# Homebrew (macOS/Linux)
brew install derailed/k9s/k9s

# MacPorts (macOS)
sudo port install k9s

# Snap (Linux)
sudo snap install k9s

# Pacman (Arch Linux)
pacman -S k9s

# Scoop (Windows)
scoop install k9s

# Chocolatey (Windows)
choco install k9s

Launching K9s

# Use default kubeconfig
k9s

# Use specific kubeconfig
k9s --kubeconfig /path/to/kubeconfig

# Use specific context
k9s --context production-cluster

# Start in specific namespace
k9s --namespace kube-system

# Launch in readonly mode
k9s --readonly

# Run without splash screen
k9s --headless

# Check configuration info
k9s info

Essential Workflows

Getting to Resources (Start Here!)

Step 1: Navigate to resource type

:pod          # List all pods
:deploy       # List deployments  
:svc          # List services
:ns           # List namespaces
:node         # List nodes
:pvc          # List persistent volume claims
:secret       # List secrets
:cm           # List configmaps

Step 2: Filter if needed

/<filter>     # Filter by name (regex)
/!<filter>    # Exclude filter
/-l app=web   # Filter by label
/-f nginx     # Fuzzy search

Step 3: Perform action

• Use arrow keys or j/k to select
• Press action key (see operations below)

Common Management Workflows

Scaling Deployments

1. Type :deploy to list deployments
2. Use j/k to select deployment
3. Press s to scale
4. Enter desired replica count
5. Press Enter to apply

Viewing Pod Logs

1. Type :pod to list pods
2. Select pod with j/k
3. Press l to view logs
4. Use w to toggle line wrap
5. Press 0 to tail from beginning

Accessing Pod Shell

1. Type :pod to list pods
2. Select running pod
3. Press s to shell into pod
4. If multi-container, select container

Managing Secrets

1. Type :secret to list secrets
2. Select secret
3. Press x to decode and view contents
4. Press Esc to return to list

Port Forwarding

1. Type :pod to list pods
2. Select pod
3. Press Shift+f to open port-forward menu
4. Configure local and remote ports
5. Connection runs in background

Core Navigation

Universal Navigation Keys

Key	Action
j / k	Move down / up
h / l	Move left / right
Ctrl+f / Ctrl+b	Page down / up
g / G	Go to top / bottom
Enter	Select item
Esc	Back to previous view
:q or Ctrl+c	Quit k9s

Resource Listing Commands

Command	Description
:<resource>	List any Kubernetes resource
:<resource> <namespace>	List resources in specific namespace
:aliases or Ctrl+a	Show all available aliases
:crd	List custom resource definitions
:apiservices	List API services
:events or :ev	View cluster events (great for troubleshooting)

Context and Namespace Management

Command	Description
:ctx	List and select contexts
:ctx <context>	Switch to specific context
:namespace	Select namespace interactively
0-9	Quick switch to favourite namespaces
u	Mark current namespace as favourite (adds +)

Filtering and Search

Filter	Description	Example
/<pattern>	Regex filter	/nginx
/!<pattern>	Inverse regex filter	/!kube-system
/-l <selector>	Filter by labels	/-l app=web,env=prod
/-f <term>	Fuzzy match	/-f web

Resource Operations

View and Inspection

Key	Action	Notes
y	View YAML	Full resource definition
d	Describe resource	Detailed info + events
v	View resource	Formatted display
e	Edit resource	Opens in editor
Enter	Drill into resource	Navigate to related resources

Logs and Debugging

Key	Action	Notes
l	View logs	For pods/containers
w	Toggle line wrap	In log view
0	Show all logs	From beginning
1-9	Show last N logs	e.g., 3 = last 300 lines
f	Follow logs	Real-time streaming
s	Shell into container	Interactive shell

Resource Management

Key	Action	Prerequisites
s	Scale resource	Must be in :deploy, :sts, etc.
r	Restart/reload	Deployments, daemonsets
Ctrl+l	Rollback	Deployments with history
Ctrl+d	Delete (with confirmation)	Any resource
Ctrl+k	Kill (force delete)	Any resource

Multi-select Operations

Key	Action
Space	Select/deselect item
Ctrl+d	Delete all selected
Ctrl+a	Select all visible

Display and Formatting

Column Management

Key	Action
Ctrl+w	Toggle wide columns
Ctrl+e	Hide/show header
f	Fullscreen mode
Ctrl+s	Save output to file

Column Sorting

Shortcut	Sort By
Shift+c	CPU usage
Shift+m	Memory usage
Shift+s	Status
Shift+p	Namespace
Shift+n	Name
Shift+o	Node
Shift+i	IP address
Shift+a	Age
Shift+t	Restart count
Shift+r	Pod readiness

Auto-refresh and State

Key	Action
r	Toggle auto-refresh
Ctrl+r	Manual refresh
Ctrl+z	Toggle error state display

Special Views and Features

XRay View (Resource Relationships)

View dependencies and relationships between resources:

:xray deploy webapp    # Show deployment relationships
:xray pod nginx-123    # Show pod relationships

Pulse View (Cluster Dashboard)

General cluster health and information:

:pulse

Directory View (Local Filesystem)

Browse and manage local files:

:dir /tmp                    # Browse /tmp directory
:dir /tmp/k9s-screens-root  # Common location for saved files

Helm Integration

Manage Helm releases:

:helm                 # List all Helm releases
:helm kube-system     # List releases in specific namespace

Advanced Features

Port Forwarding Workflow

1. Navigate to pods: :pod
2. Select target pod
3. Press Shift+f for port-forward menu
4. Configure ports (local:remote)
5. Establish connection
6. Use pf alias to manage active forwards

Benchmarking (HTTP Load Testing)

1. Set up port forwarding to your service
2. Press Ctrl+b to start HTTP benchmark
3. Results saved to /tmp for analysis
4. Configure via $HOME/.k9s/bench-<context>.yml

Secret Management Workflow

1. Navigate to secrets: :secret
2. Select secret to examine
3. Press x to decode and view contents
4. Press Esc to return to secret list
5. Use y to view full YAML including encoded data

Understanding the Display

Resource Status Indicators

• ● Green: Healthy/Running
• ● Yellow: Warning/Pending
• ● Red: Error/Failed
• + after namespace: Favourite namespace
• * after namespace: Default namespace

CPU and Memory Metrics

• %CPU/R: Percentage of requested CPU
• %CPU/L: Percentage of CPU limit
• %MEM/R: Percentage of requested memory
• %MEM/L: Percentage of memory limit
• CPU/A: Allocatable CPU

Container Status

• READY: Running containers / total containers
• PROBES(L:R): Liveness and Readiness probe status
• RESTARTS: Container restart count

Configuration and Customisation

Configuration Files

K9s stores configuration in $HOME/.k9s/ or $XDG_CONFIG_HOME/k9s/:

File	Purpose
config.yml	Main k9s configuration
views.yml	Custom column views
alias.yml	Custom resource aliases
hotkey.yml	Custom keyboard shortcuts
plugin.yml	Plugin management
skins/	Custom colour schemes

Sample Configuration

# ~/.k9s/config.yml
k9s:
  refreshRate: 2
  maxConnRetry: 5
  readOnly: false
  noExitOnCtrlC: false
  ui:
    enableMouse: false
    headless: false
    logoless: false
  skipLatestRevCheck: false
  disablePodCounting: false
  shellPod:
    image: busybox:1.35.0
    namespace: default
    limits:
      cpu: 100m
      memory: 100Mi
  logger:
    tail: 1000
    buffer: 5000
    sinceSeconds: -1

Custom Views with JQ Support

# ~/.k9s/views.yml  
k9s:
  views:
    v1/pods:
      sortColumn: AGE:desc
      columns:
        - AGE
        - NAMESPACE
        - NAME
        - STATUS
        - IMG:.spec.containers[0].image|split(":")|.[0]
        - VERSION:.spec.containers[0].image|split(":")|.[-1]

Environment Variables

Variable	Purpose
K9S_SKIN	Set skin theme
KUBECONFIG	Specify kubeconfig paths
K9S_CONFIG_DIR	Override config directory

Troubleshooting Workflows

Pod Not Starting

1. :pod → find problem pod
2. d to describe (check events)
3. :events to see cluster events
4. y to examine YAML configuration
5. l to check container logs if available

Service Not Accessible

1. :svc → find service
2. d to describe service
3. Enter to drill into endpoints
4. :pod → verify pod labels match service selector
5. Use port-forward to test connectivity

Resource Quotas/Limits

1. :ns → select namespace
2. Look for quota indicators in display
3. :resourcequota or :limitrange to check limits
4. :node to check cluster capacity

Performance Issues

1. :node → check node resources
2. Sort by CPU/Memory with Shift+c / Shift+m
3. :pod → identify resource-heavy pods
4. Use :top pod or :top node for detailed metrics

Plugin System

K9s supports plugins for extended functionality. Popular plugins include:

• kube-score: Security and best practice scoring
• kubectl-df-pv: Disk usage for persistent volumes
• kubectl-neat: Clean YAML output
• stern: Advanced log tailing

Plugin repository: https://github.com/derailed/k9s/tree/master/plugins

Common Gotchas and Tips

Workflow Tips

1. Always start with resource type: :pod, :deploy, etc.
2. Use fuzzy search: /-f is often faster than exact matches
3. Favourite your namespaces: Press u for quick access
4. Save before copying: Use Ctrl+s then browse with :dir /tmp
5. Multi-cluster setup: Use $KUBECONFIG with multiple paths

Performance Tips

1. Reduce refresh rate in busy clusters
2. Use readonly mode (--readonly) for investigation
3. Filter early to reduce data processing
4. Close unused views to free memory

Common Issues

• “Permission denied”: Check RBAC permissions
• “Connection refused”: Verify cluster connectivity
• “Resource not found”: Check if CRDs are installed
• Editing reverted: Scale down operator/controller first

Keyboard Shortcuts Summary Card

Action	Key	Context
Navigate	j/k	Any view
Select	Enter	Any list
Filter	/pattern	Any list
Back	Esc	Any view
Describe	d	Resource selected
YAML	y	Resource selected
Edit	e	Resource selected
Logs	l	Pod/container
Shell	s	Pod
Scale	s	Deployment/StatefulSet
Delete	Ctrl+d	Any resource
Port Forward	Shift+f	Pod
Full Screen	f	Any view
Wide View	Ctrl+w	Any list
Save	Ctrl+s	Any view

---

This cheatsheet reflects k9s v0.50+ features. For the latest updates, check the official k9s repository.