How-To Guide

Explore the Cluster with k9s

Type: How-To (Task-oriented)

Related: Access kubectl | Query Loki Logs

Goal: Use k9s to inspect, monitor, and interact with the KUP6S cluster efficiently.

Time: ~10 minutes to learn basics

What is k9s?

k9s is a terminal-based UI for Kubernetes that provides a fast, interactive way to navigate and manage cluster resources. It’s like kubectl on steroids with real-time updates and keyboard-driven navigation.

When to use k9s:

• Quick cluster inspection and troubleshooting

• Viewing logs across multiple pods

• Real-time resource monitoring

• Interactive debugging sessions

When to use alternatives:

• kubectl: Scripting, automation, CI/CD

• Grafana: Long-term metrics, dashboards, alerts

• Lens/OpenLens: GUI preference, multi-cluster management

Prerequisites

• kubectl configured for KUP6S cluster

• k9s installed (see Tutorial: First Deployment)

Step 1: Launch k9s

Start k9s with your current kubectl context:

# Use current context
k9s

# Or specify context explicitly
k9s --context kup6s

What you’ll see:

• Top banner: Cluster name, K8S version, context

• Resource list: Pods by default

• Bottom bar: Available actions and shortcuts

• Header: Current namespace, filter status

Step 2: Navigate Between Resource Types

Quick Navigation (Colon Commands)

Press : to enter command mode, then type the resource type:

Command	Resource	Description
:pod	Pods	All pods in namespace
:deploy	Deployments	Deployment objects
:svc	Services	Service objects
:node	Nodes	Cluster nodes
:ns	Namespaces	All namespaces
:pvc	PVCs	Persistent volume claims
:ing	Ingresses	Ingress rules
:cm	ConfigMaps	Configuration maps
:secret	Secrets	Secret objects
:events	Events	Cluster events

Example workflow:

:pod    → View all pods
:svc    → Switch to services
:deploy → Switch to deployments

Keyboard Navigation

Key	Action
↑/↓ or j/k	Move up/down in list
Enter	Describe selected resource
Esc	Go back/exit
Ctrl+C or :q	Quit k9s
/	Filter resources
?	Help menu (all shortcuts)

Step 3: Filter and Search

Namespace Filtering

Change namespace:

0           → Show all namespaces
:ns         → List all namespaces
Enter       → Select namespace

Or filter to specific namespace:

:pod -n argocd        → Pods in argocd namespace

Text Filtering

Press / to enter filter mode, then type search term:

/nginx      → Show only resources matching "nginx"
/Esc        → Clear filter

Case-insensitive search by default.

Example: Find all Longhorn pods:

:pod
/longhorn

Step 4: View Logs

Single Pod Logs

1. Navigate to pod: :pod

2. Select pod with ↑/↓

3. Press l (lowercase L) → View logs

Log viewer controls:

Key	Action
↑/↓	Scroll logs
PgUp/PgDn	Page up/down
g	Go to top
G	Go to bottom
f	Toggle auto-scroll (follow)
w	Toggle line wrap
/	Search in logs
Esc	Exit log viewer

Multi-Container Pods

If pod has multiple containers:

1. Press l → Shows container selector

2. Select container with Enter

3. View logs for that container

Previous Container Logs

View logs from crashed/restarted container:

1. Navigate to pod

2. Press p → Previous logs

Step 5: Describe Resources

Get detailed information about a resource:

1. Navigate to resource type (:pod, :deploy, etc.)

2. Select resource

3. Press d → Describe (like kubectl describe)

Describe view:

• YAML definition

• Events related to resource

• Status conditions

Press Esc to return to list.

Step 6: Shell Into Containers

Open an interactive shell in a container:

1. Navigate to pod: :pod

2. Select pod

3. Press s → Shell

Default shell: /bin/sh

If pod has multiple containers:

• Select container first

• Then shell opens in that container

Exit shell: Type exit or press Ctrl+D

Step 7: Port Forwarding

Forward a port from a pod to your local machine:

1. Navigate to pod: :pod

2. Select pod

3. Press Shift+F → Port forward

Enter port mapping:

8080:80      → Local 8080 → Pod 80
:3000        → Random local → Pod 3000

Stop port-forward: Ctrl+C in k9s

Use forwarded port:

# In another terminal
curl localhost:8080

Step 8: Edit Resources

Warning: Direct editing bypasses GitOps. Only use for debugging.

1. Navigate to resource

2. Press e → Edit in $EDITOR

3. Save and exit → Resource updated

Better approach: Edit in Git, sync via ArgoCD.

Step 9: Delete Resources

Warning: Deletion is immediate and permanent.

1. Navigate to resource

2. Press Ctrl+D → Delete

3. Confirm deletion

Safer for app resources: Delete via ArgoCD/Git.

Step 10: View Resource YAML

View the full YAML definition:

1. Navigate to resource

2. Press y → YAML view

Shows complete Kubernetes manifest.

Press Esc to return.

Step 11: Monitor Node Resources

Check node CPU/memory usage:

:node       → List all nodes

Node view shows:

• CPU usage (%)

• Memory usage (%)

• Pod count

• Age

Drill into node:

1. Select node

2. Press Enter → Node details

3. See pods running on that node

Step 12: Check Events

View cluster events (warnings, errors):

:events

Event view:

• Sorted by timestamp (most recent first)

• Filter by type: <number> (shown in header)

• Useful for debugging pod failures, scheduling issues

Common event types:

• Warning - Potential issues

• Normal - Standard operations

• Error - Failures

Common Workflows

Debug a Crashing Pod

:pod
/my-app                → Filter to your app
Select pod
l                      → View logs
p                      → View previous logs (if crashed)
d                      → Describe (see events)

Check Resource Usage

:node                  → Overall node usage
:pod
Shift+S                → Sort by CPU/memory

Find Why Service Not Working

:svc                   → List services
Select service
d                      → Describe (check endpoints)
:pod                   → Check backing pods
:ing                   → Check ingress rules

Investigate Storage Issues

:pvc                   → List PVCs
Select PVC
d                      → Check status, events
:pod                   → Find pods using it

Tips and Tricks

Custom Resource Definitions (CRDs)

k9s supports CRDs too:

:clusters.postgresql.cnpg.io     → CNPG clusters
:externalsecrets                 → External Secrets
:applications.argoproj.io        → ArgoCD apps

Sorting

Press Shift+S in any list view to change sort order:

• Name

• Namespace

• Age

• CPU/Memory (if applicable)

Watch Mode

k9s auto-refreshes by default. Change interval:

:xray <resource>     → Detailed real-time view

Context Switching

Switch kubectl context without restarting k9s:

:ctx                 → List contexts
Select context       → Switch

Pulse (Overview)

:pulse               → High-level cluster overview

Shows summary of pods, deployments, services, etc.

When NOT to Use k9s

Production Changes

❌ Don’t: Edit or delete production resources in k9s

✅ Do: Make changes via Git → ArgoCD

Automation

❌ Don’t: Script k9s commands

✅ Do: Use kubectl for scripts and CI/CD

Long-term Monitoring

❌ Don’t: Keep k9s open 24/7 for metrics

✅ Do: Use Grafana dashboards for monitoring

Sharing with Team

❌ Don’t: Describe issues verbally from k9s

✅ Do: Use kubectl get/describe for shareable output

Troubleshooting

k9s Won’t Start

Error: cannot connect to cluster

Solution:

# Check kubectl works
kubectl get nodes

# Check current context
kubectl config current-context

# If wrong context
k9s --context kup6s

Resource Not Found

Error: No resources found

Solution:

• Check namespace: Press 0 to show all namespaces

• Check RBAC: Ensure your user has permissions

• Verify resource exists: kubectl get <resource>

Performance Issues

Symptom: k9s slow or unresponsive

Solution:

• Filter resources: /filter-term

• Switch to specific namespace (not all)

• Increase refresh interval (advanced config)

Further Reading

• k9s Documentation

• How-To: Access Grafana - For long-term monitoring

• How-To: Query Loki Logs - For advanced log searching

• Tutorial: First Deployment - Includes k9s installation