k9s Reference: Commands, Shortcuts, Popeye, XRay & Plugin Configuration

# Install:
brew install derailed/k9s/k9s    # macOS
# Or: https://github.com/derailed/k9s/releases (single binary)

# Launch:
k9s                              # uses current kubectl context
k9s --context my-cluster         # specific context
k9s --namespace production       # start in a specific namespace
k9s --readonly                   # read-only mode (no mutations)
k9s --kubeconfig ~/.kube/config  # explicit kubeconfig

# Config location:
# macOS: ~/.config/k9s/config.yaml
# Linux: $XDG_CONFIG_HOME/k9s/config.yaml

# config.yaml — key settings:
k9s:
  refreshRate: 2                 # screen refresh in seconds
  maxConnRetry: 5
  readOnly: false
  noExitOnCtrlC: false
  ui:
    enableMouse: true
    headless: false
    logoless: true               # hides the k9s logo for more screen space
    crumbsless: false
    noIcons: false
  skipLatestRevCheck: true       # disable update check notification

# Skins (custom colors):
# Download from https://github.com/derailed/k9s/tree/master/skins
# Place in: ~/.config/k9s/skins/
# Reference in config.yaml: ui.skin: dracula

# Resource navigation:
:pods              # go to Pods view (: opens command mode)
:deploy            # Deployments
:svc               # Services
:cm                # ConfigMaps
:secret            # Secrets
:nodes             # Nodes
:pvc               # PersistentVolumeClaims
:ing               # Ingresses
:cj                # CronJobs
:events            # Events (great for debugging)
:hpa               # HorizontalPodAutoscalers

# Type any resource shortname or full name:
:pod               # same as :pods
:persistentvolumeclaims
:crb               # ClusterRoleBindings

# Navigation keys:
?          # help (full shortcut list)
ESC        # back / cancel
CTRL+C     # quit k9s
/          # filter/search (fuzzy — type partial name)
ENTER      # view details / drill into resource
l          # logs for selected pod
e          # edit resource (kubectl edit equivalent)
d          # describe resource (kubectl describe)
s          # shell into pod (exec -it)
CTRL+K     # kill/delete resource
CTRL+D     # diff resource vs live cluster

# Namespace switching:
CTRL+A     # show all namespaces
:ns        # list namespaces and switch with ENTER

# Context switching:
CTRL+E     # switch between active clusters/contexts

# In :pods view:
l           # view logs for selected pod
CTRL+S      # save logs to file
t           # toggle log timestamps
f           # toggle full-screen logs
w           # toggle log wrap
s           # shell/exec into selected pod
CTRL+L      # clear log buffer

# Multi-container pods:
# When you press l on a multi-container pod, k9s shows a container picker
# Press ESC to go back to pod list

# Port forwarding (without leaving k9s):
SHIFT+F     # port-forward selected pod
# Enter local port → remote port → creates forward in background
# :pf         # view + manage active port forwards

# Copy pod name (for use in other terminals):
CTRL+Y      # yank (copy) the selected resource name to clipboard

# Filter pods by name or label:
/frontend   # fuzzy filter — shows only pods matching "frontend"
CTRL+R      # clear filter

# Sort columns:
# Click column header in mouse mode, or:
SHIFT+Sort  # toggle sort on focused column

# Describe a pod (equivalent to kubectl describe):
d           # opens scrollable describe view

# View events for a pod:
SHIFT+E     # show events related to selected resource

# Pulses — real-time cluster health dashboard:
:pulses     # shows CPU/memory/pod/error counts per namespace
            # auto-refreshes, quick overview of cluster health

# XRay — resource dependency graph:
:xray deployments      # shows Deployments → ReplicaSets → Pods tree
:xray services         # shows Services → Endpoints → Pods
:xray ingresses        # Ingress → Service → Pods chain
# Useful for: "why is my deployment not serving traffic?"

# Benchmarking (HTTP benchmarks from within k9s):
# Select a Service → CTRL+B → configure/run HTTP benchmark
# Displays results in-UI. Requires hey CLI on PATH.

# Popeye — cluster linter (k9s includes it):
:popeye     # scans cluster for misconfigurations
# Checks: resource limits, liveness probes, RBAC issues, image tags using :latest
# Scores each namespace A-F. Opens a report in k9s UI.

# Pulse navigation:
:pods       # go back to pods from any view
# Most views are drillable — ENTER goes deeper, ESC goes back

# aliases.yaml — short names for custom resources (CRDs):
# ~/.config/k9s/aliases.yaml
aliases:
  dp: v1/deployments
  ro: argoproj.io/v1alpha1/rollouts    # alias for Argo Rollouts
  es: external-secrets.io/v1beta1/externalsecrets
  so: keda.sh/v1alpha1/scaledobjects   # KEDA ScaledObjects
  vs: networking.istio.io/v1beta1/virtualservices  # Istio VirtualServices

# hotkeys.yaml — custom keyboard shortcuts:
# ~/.config/k9s/hotkeys.yaml
hotKeys:
  shift-1:
    shortCut: Shift-1
    description: "Go to namespace production"
    command: ns production
  shift-2:
    shortCut: Shift-2
    description: "Go to pods"
    command: pods

# plugins.yaml — extend k9s with external commands:
# ~/.config/k9s/plugins.yaml
plugins:
  stern:                              # tail logs across multiple pods
    shortCut: Ctrl-L
    description: "Multi-pod logs via stern"
    scopes: [pods]
    command: stern
    background: false
    args:
      - --tail
      - "100"
      - "{{.Name}}"

  kubectl-debug:
    shortCut: Shift-D
    description: "Debug pod with ephemeral container"
    scopes: [pods]
    command: kubectl
    args: [debug, -it, "{{.Name}}", --image=busybox, -n, "{{.Namespace}}"]