kubectl Tips #

In daily Kubernetes operations, the kubectl CLI is the main tool connecting us to full control over all resources in the cluster. Although almost all site reliability engineers (SREs) and software engineers know basic commands like kubectl get pods, only a small fraction leverage advanced features to speed up troubleshooting. When incidents happen in production environments, command-line navigation speed directly impacts the Mean Time to Resolution (MTTR) metric. This article presents an in-depth guide to advanced kubectl tips, tricks, and configurations that will significantly increase our operational productivity — from JSONPath output manipulation, advanced debugging techniques without disturbing pod stability, multi-cluster management, to automation with plugins and shell aliases.

Complete Resource Name Shortcut List #

Kubernetes has dozens of resource types. Typing full names like persistentvolumeclaims or customresourcedefinitions repeatedly wastes a lot of time. Therefore, Kubernetes provides official short names (shortnames) for almost every standard object type.

We can memorize the following most crucial short names to save keyboard keystrokes:

To see all short names supported by our currently active cluster (including Custom Resources installed by third-party operators), we can use the following command:

# Shows the complete list of all resources with their API groups, shortnames, and namespace scopes
kubectl api-resources

Advanced Output Manipulation #

By default, kubectl displays information in a simple table format. However, when managing hundreds of objects, we need more specific data representations. kubectl supports advanced output formats using JSONPath expressions, Custom Columns, and pipeline integration with the jq tool.

1. Leveraging JSONPath for Precise Data Extraction #

JSONPath lets us filter and take specific property values from the JSON data structure returned by the Kubernetes API Server. Basic JSONPath syntax in kubectl is always wrapped in single quotes and curly braces: -o jsonpath='{.path.to.field}'.

Here’s a collection of very useful production JSONPath queries:

# 1. Get the list of all Pod names in the current namespace
kubectl get pods -o jsonpath='{.items[*].metadata.name}'

# 2. Show the list of Pod names along with each Pod's internal IP address
kubectl get pods -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.podIP}{"\n"}{end}'

# 3. Get all container image names currently running in the cluster
kubectl get pods -A -o jsonpath='{.items[*].spec.containers[*].image}'

# 4. Check the total CPU and Memory capacity of every Node in the cluster
kubectl get nodes -o jsonpath='{range .items[*]}{.metadata.name}{"\t CPU: "}{.status.capacity.cpu}{"\t MEMORY: "}{.status.capacity.memory}{"\n"}{end}'

# 5. Find containers without CPU limit configurations in the production namespace
kubectl get deploy -n production -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.template.spec.containers[*].resources.limits.cpu}{"\n"}{end}'

2. Designing Custom Column Tables #

If JSONPath queries are too long to read, we can design our own table layouts by defining new column names along with related JSONPath paths using the -o custom-columns=<KEY>:<JSONPath> format.

# Create a custom report for Pod monitoring
kubectl get pods -n production \
  -o custom-columns=\
"POD NAME:.metadata.name,\
POD STATUS:.status.phase,\
POD IP:.status.podIP,\
NODE ALLOCATION:.spec.nodeName,\
RESTART #:.status.containerStatuses[0].restartCount"

The generated output is immediately arranged neatly like this:

POD NAME             POD STATUS   POD IP        NODE ALLOCATION   RESTART #
payment-api-v1-abc   Running      10.244.3.45   node-worker-1     0
billing-job-v2-xyz   Failed       10.244.4.12   node-worker-2     3

3. Pipeline Integration with jq #

For advanced manipulation involving complex condition filtering, grouping, or mathematical operations, we can pipe the raw JSON format to the jq binary.

# 1. Show Pod names that have restarted more than 5 times
kubectl get pods -o json | jq '.items[] | select(.status.containerStatuses[0].restartCount > 5) | {name: .metadata.name, restarts: .status.containerStatuses[0].restartCount}'

# 2. Calculate the total CPU requests usage of all pods in the cluster
kubectl get pods -A -o json | jq '[.items[].spec.containers[].resources.requests.cpu | select(. != null)]'

4. Sorting and Filtering Results #

We can natively sort output lines by specific JSON fields using the --sort-by flag.

# 1. Sort Pods by creation time (newest Pods at the bottom)
kubectl get pods --sort-by=.metadata.creationTimestamp

# 2. Sort Pods by the highest container restart count
kubectl get pods --sort-by='.status.containerStatuses[0].restartCount'

# 3. Show all labels attached to Pod objects
kubectl get pods --show-labels

# 4. Filter Pods by a specific label (app=payment-gateway)
kubectl get pods -l app=payment-gateway

# 5. Filter Pods with set logic conditions (take those running in staging or prod)
kubectl get pods -l 'environment in (staging, production)'

# 6. Filter Pods with negation (ignore Pods labeled tier=frontend)
kubectl get pods -l 'tier!=frontend'

Production-Level Debugging Techniques #

When applications fail, we need direct diagnosis access without disturbing running business processes. Here are debugging techniques using exec, debug, port-forward, and advanced log analysis.

1. kubectl exec vs kubectl debug (Distroless Services) #

Traditionally, we enter the problematic container using the kubectl exec command:

# Enter the main container's interactive shell
kubectl exec -it <pod-name> -- bash

# If the container doesn't have a bash shell, try the sh alternative
kubectl exec -it <pod-name> -- sh

However, in modern production environments applying strict security principles, container images are often packaged in Distroless or Minimal formats (like minimal Alpine). These images don’t have basic utility tools like bash, sh, curl, nslookup, or even ping to minimize the attack surface. If we try kubectl exec into such containers, we get an error saying the shell isn’t found.

To solve this problem, we can insert an Ephemeral Debug Container into the already-running Pod without needing a restart. This debug container runs in the same network and process namespace as our application container.

# Insert an interactive debug container using the netshoot image (complete network toolkit)
kubectl debug -it <pod-name> \
  --image=nicolaka/netshoot \
  --target=<target-container-name>

Inside that ephemeral debug container, we can use all the complete network tools (like tcpdump, curl, dig) to analyze the neighboring main application container.

2. Flexible kubectl port-forward #

We can route network port traffic from our local machine directly into the cluster without creating external Services or Ingresses.

# 1. Forward to a specific Pod port
kubectl port-forward pod/<pod-name> 8080:8080

# 2. Forward to a Deployment port (automatically selects one healthy replica pod)
kubectl port-forward deployment/payment-service 8080:8080

# 3. Forward to an internal Service
kubectl port-forward service/database-service 5432:5432

# 4. Port forward to a non-localhost IP address (so it's accessible from other devices on the same network)
kubectl port-forward service/payment-service 8080:80 --address=0.0.0.0

3. Advanced Log Analysis (kubectl logs) #

Reading raw logs that are too long is very difficult. We must limit log searches using time parameters and filters.

# 1. Follow logs in real-time (stream logs)
kubectl logs -f <pod-name>

# 2. Get logs from a Pod with multiple containers (multi-container pod)
kubectl logs <pod-name> -c <container-name>

# 3. Get logs from all containers in the Pod simultaneously
kubectl logs <pod-name> --all-containers

# 4. Show the last 100 log lines
kubectl logs <pod-name> --tail=100

# 5. Show only logs recorded in the last 30 minutes
kubectl logs <pod-name> --since=30m

# 6. Show logs since an absolute timestamp (ISO-8601)
kubectl logs <pod-name> --since-time=2026-06-17T08:00:00Z

# 7. Include timestamps on every log line
kubectl logs <pod-name> --timestamps

# 8. Get logs by label selector (combining logs from all replica pods)
kubectl logs -l app=payment-service --tail=50

Monitoring Cluster Events in Real-Time #

When a Pod is stuck in a Pending, ImagePullBackOff, or CrashLoopBackOff status, the application’s internal logs are usually empty because the container process hasn’t had a chance to run. The only trusted information source at this phase is Kubernetes Events.

# 1. Monitor state transitions of all objects in the target namespace in real-time
kubectl get events -w

# 2. Show events and sort them by the last event time
kubectl get events --sort-by=.lastTimestamp

# 3. Show events across all namespaces in the cluster to detect global anomalies
kubectl get events -A --sort-by=.lastTimestamp | tail -30

Besides the kubectl get events command, we can read specific failure events at the end of object description output:

# Describing a pod gives container status info and shutdown/scheduling event history
kubectl describe pod <pod-name>

Multi-Cluster Management via Kubeconfig #

Often we must manage several Kubernetes clusters at once (e.g. a staging cluster on cloud provider A and a production cluster on-premise). All access credentials and API server addresses are stored in the kubeconfig configuration file located at ~/.kube/config.

The Kubeconfig Structure #

Kubeconfig divides the configuration into three main elements:

• Clusters: The cluster API Server endpoint URL addresses and related CA certificates.
• Users: Authentication credentials (like access tokens, client certificates, or encryption keys).
• Contexts: Mapping pairs between cluster names, users, and default namespaces.

# 1. View all registered contexts on the local machine
kubectl config get-contexts

# 2. Show the currently active context
kubectl config current-context

# 3. Instantly switch access to another cluster
kubectl config use-context production-gcp-cluster

# 4. Change the default namespace for the current context (avoiding repeated -n typing)
kubectl config set-context --current --namespace=finance-prod

Safely Merging Multiple Kubeconfig Files #

When we download new credential files from cloud providers, they often give us separate config files (like config-staging.yaml). Directly overwriting the built-in ~/.kube/config file would erase our other cluster access. We must merge them safely:

# Merge the old config file with the new config into a temporary file, then overwrite safely
KUBECONFIG=~/.kube/config:~/Downloads/config-staging.yaml kubectl config view --flatten > ~/.kube/merged-config
mv ~/.kube/merged-config ~/.kube/config
chmod 600 ~/.kube/config

Multi-Cluster Navigation Utilities: kubectx and kubens #

Although the kubectl config commands are very powerful, typing them manually is too long. We’re recommended to install the helper tools kubectx (for switching clusters) and kubens (for switching namespaces).

# Switch clusters interactively or directly by name
kubectx production-cluster

# Instantly switch the default namespace
kubens prod-payment

Custom Extensions with the Krew Plugin Manager #

Just like apt for Debian or brew for macOS, krew is the official plugin package manager for kubectl. With Krew, we can extend kubectl CLI capabilities with hundreds of community-made plugin scripts.

1. How to Install Krew #

Run the following installation command in your Unix terminal:

# Download and configure Krew in the user directory
(
  set -x; cd "$(mktemp -d)" &&
  OS="$(uname | tr '[:upper:]' '[:lower:]')" &&
  ARCH="$(uname -m | sed -e 's/x86_64/amd64/' -e 's/arm64/arm64/')" &&
  curl -fsSLO "https://github.com/kubernetes-sigs/krew/releases/latest/download/krew-${OS}_${ARCH}.tar.gz" &&
  tar zxvf "krew-${OS}_${ARCH}.tar.gz" &&
  KREW=./krew-"${OS}_${ARCH}" &&
  "$KREW" install krew
)

# Add the following line to ~/.bashrc or ~/.zshrc so the binary can be executed directly:
export PATH="${KREW_ROOT:-$HOME/.krew}/bin:$PATH"

2. Recommended Essential Plugins for Production #

After Krew is installed, install the following high-productivity plugins:

# 1. kubectl neat: Cleans unnecessary system metadata when exporting YAML manifests
# Very important when we want to export active resources from the cluster to store in Git (GitOps)
kubectl krew install neat
# Usage: kubectl get deploy/payment-api -o yaml | kubectl neat > deploy-clean.yaml

# 2. kubectl tree: Shows resource relationship hierarchies graphically
# Makes it easy to see which Pods were created by the ReplicaSet of a certain Deployment
kubectl krew install tree
# Usage: kubectl tree deploy/payment-api

# 3. kubectl view-secret: Instantly decodes base64 secret contents without needing echo -n | base64 --decode
kubectl krew install view-secret
# Usage: kubectl view-secret db-credentials-secret db-password

# 4. kubectl whoami: Shows the current user/role authorization info in the active cluster
kubectl krew install whoami

# 5. kubectl access-matrix: Checks the RBAC permission matrix (whether our role can create/delete certain resources)
kubectl krew install access-matrix
# Usage: kubectl access-matrix --namespace=default

Shell Customization, Aliases, and Autocomplete #

Typing the word kubectl hundreds of times a day is very tiring. Configuring shortcuts (aliases) and auto-completion features (tab completion) is a mandatory step for maximum efficiency.

1. Enabling Official Autocomplete #

Make sure your shell is configured to automatically complete command arguments when you press the TAB key.

# For Zsh shell users (add to ~/.zshrc):
source <(kubectl completion zsh)

# For Bash shell users (add to ~/.bashrc):
source <(kubectl completion bash)

2. High-Productivity Alias Collection #

Add the following alias shortcuts to your shell profile file (~/.zshrc or ~/.bashrc):

# Basic aliases shortening the main commands
alias k='kubectl'
alias kg='kubectl get'
alias kd='kubectl describe'
alias kl='kubectl logs'
alias kx='kubectl exec -it'
alias kdel='kubectl delete'

# Shortcuts with specific namespace filters to speed up diagnosis
alias kprod='kubectl --namespace production'
alias kdev='kubectl --namespace development'

# Instant monitoring shortcuts
alias kgpo='kubectl get pods'
alias kgdep='kubectl get deployments'
alias kgsvc='kubectl get services'
alias kgsec='kubectl get secrets'

3. Custom Dynamic Shell Functions #

We can also create advanced shell functions accepting dynamic arguments to speed up network troubleshooting or environment cleanup:

# Function 1: Interactive log searching by application label name
klog() {
  kubectl logs -f -l app=$1 --max-log-requests=10 -n ${2:-production}
}
# Usage: 
# klog payment-api           -> logs from app=payment-api in the production namespace
# klog auth-service staging  -> logs from app=auth-service in the staging namespace

# Function 2: Create an instant network ephemeral debug Pod in the default namespace
kping() {
  kubectl run net-debug-pod --rm -it --image=nicolaka/netshoot --restart=Never -- ping $1
}
# Usage: kping 10.244.3.45

kubectl Operations Anti-Patterns #

Although kubectl is very flexible, using it carelessly in production environments can endanger cluster stability and security.

1. Direct Imperative Modifications in Production (Ad-Hoc Mutability) #

// ANTI-PATTERN: Changing application configurations directly using imperative commands.
$ kubectl edit deployment/payment-api -n production
$ kubectl patch service/payment-service -p '{"spec":{"type":"LoadBalancer"}}'

✓ SOLUTION: Apply Declarative GitOps Practices.
All cluster state changes must be declared inside Git repositories 
(e.g. through Helm charts or Kustomize overlays) and applied automatically 
using CI/CD pipelines or reconciliation operators like ArgoCD. Manual changes 
using kubectl edit cause cluster configurations to go out of sync (drift) 
with Git and get forcibly overwritten when the next pipeline runs.

2. Running Debug Pods Without Resource Limits #

Freely running interactive pods using kubectl run in the production cluster without specifying memory or CPU request allocations.

# ANTI-PATTERN: This debug container risks devouring unlimited physical Node resources
kubectl run stress-tester --image=ubuntu -- stress --cpu 4

# ==============================================================================
# CORRECT: Always specify the smallest resource limits if forced to run ad-hoc Pods
kubectl run prod-debug --image=nicolaka/netshoot --rm -it \
  --overrides='{ "spec": { "resources": { "limits": { "cpu": "200m", "memory": "256Mi" } } } }'

If we don’t specify resource limits on the ad-hoc pods we run, those pods enter the BestEffort QoS Class. If such a pod suffers a memory leak or high CPU consumption, it disturbs the stability of other important production Pods running on the same physical Node (noisy neighbor effect).

kubectl Operational Efficiency Audit Checklist #

Use this checklist to measure your command-line navigation readiness and efficiency:

SHELL & SHORTCUT CONFIGURATION:
  □ Shell autocomplete is active and dynamically completes resource names.
  □ Basic alias collections (like 'k' for 'kubectl') are configured in the shell profile.
  □ Official shortnames for core resources are understood and used (po, svc, deploy, pvc).
  □ The 'kubectx' and 'kubens' tools are used for fast multi-cluster context management.

DATA MANIPULATION & FORMATTING:
  □ Can extract specific manifest fields using JSONPath queries without wasting time reading full YAML.
  □ Uses the '-o custom-columns' option to create easy-to-read custom monitoring table reports.
  □ Leverages 'jq' pipelines for complex logic filtering and calculations on JSON output.
  □ Uses the 'kubectl neat' plugin to clean system field metadata when exporting YAML.

DEBUGGING & SECURITY TECHNIQUES:
  □ Ephemeral debug containers ('kubectl debug') are used to debug minimal/distroless pods.
  □ Can route internal cluster ports to local machines using 'kubectl port-forward'.
  □ Log searches are limited with '--since' or '--tail' parameters to speed up error isolation.
  □ Direct 'kubectl edit' modifications on production objects are avoided outside GitOps pipeline paths.
  □ Resource limit override parameters are always included when creating ad-hoc pods in production.

Summary #

• CLI Navigation Speed Is Key — Mastering shortcuts (shortnames) and shell aliases directly reduces typing time and minimizes typos during critical incidents.
• JSONPath for Data Automation — Learn basic JSONPath syntax to filter cluster data specifically instead of manually scanning YAML.
• Use Ephemeral Containers for Debugging — Leave behind the practice of installing tool shells inside main application container images; use kubectl debug with the netshoot image to keep the cluster secure.
• Events as Early Detection — Always check cluster events (kubectl get events) before reading application logs to diagnose scheduling or container image pull failures.
• Manage Kubeconfig Safely — Separate cluster config files between environments and leverage kubectx/kubens to avoid wrong command execution incidents on production clusters.
• Clean Up Manifests — Use the kubectl neat plugin to discard built-in system lines (like managedFields) before saving manifests back into Git version control.

← Previous: Kustomize   Next: Local Development Tools →