Generic Useful kubectl Commands (with --kubeconfig & port-forwarding)
Introduction
If you work with Kubernetes daily, you know that kubectl is your best friend—and sometimes your worst enemy.
Whether you're debugging a failing pod at 2 AM or just trying to check if your deployment rolled out successfully,
having a solid arsenal of kubectl commands at your fingertips can save you hours of frustration.
This guide is a collection of the commands I find myself using constantly. It's not meant to be exhaustive (the official kubectl docs are great for that), but rather a practical reference for the everyday tasks: inspecting deployments, tailing logs, debugging pods, managing ConfigMaps and Secrets, and—one of my favorites—port-forwarding to access services locally without exposing them to the internet.
One thing you'll notice: all commands include the --kubeconfig flag. In production environments,
you often work with multiple clusters, and explicitly specifying the kubeconfig file prevents those "oops, wrong cluster"
moments we've all experienced. Of course, you can export KUBECONFIG as an environment variable to avoid
repetition—I'll show you how later.
Working with Deployments
Deployments are the bread and butter of Kubernetes workloads. When something goes wrong, these commands help you quickly understand what's happening and take action.
Get basic info
Start simple—get a quick overview of your deployment's status, replicas, and age:
kubectl --kubeconfig=/path/to/kubeconfig.yaml get deployment <name> -n <namespace>Describe a deployment (full debug info)
When things aren't working as expected, describe is your go-to command.
It shows everything: events, conditions, replica sets, and any recent errors.
kubectl --kubeconfig=/path/to/kubeconfig.yaml describe deployment <name> -n <namespace>Get deployment YAML
Need to see the full configuration? This dumps the deployment spec in YAML format, useful for debugging or creating templates:
kubectl --kubeconfig=/path/to/kubeconfig.yaml get deployment <name> -n <namespace> -o yamlShow rollout status
After applying changes, track the rollout in real-time to see if your new version is deploying successfully:
kubectl --kubeconfig=/path/to/kubeconfig.yaml rollout status deployment/<name> -n <namespace>Undo last rollout
Deployed a breaking change? No problem. This command rolls back to the previous revision—a lifesaver when things go south:
kubectl --kubeconfig=/path/to/kubeconfig.yaml rollout undo deployment/<name> -n <namespace>Inspecting Pods
Pods are where your containers actually run. Most debugging sessions start here, especially when containers are crashing
or stuck in Pending or CrashLoopBackOff states.
List pods in a namespace
The simplest command to see all pods in a namespace, including their status and restart counts:
kubectl --kubeconfig=/path/to/kubeconfig.yaml get pods -n <namespace>List pods created by a deployment (label selector)
Deployments create pods with specific labels. Use label selectors to filter and see only the pods managed by a particular app:
kubectl --kubeconfig=/path/to/kubeconfig.yaml get pods -n <namespace> -l app=<appname>Describe a pod
This is where the magic happens. describe pod shows you container states, recent events, volume mounts,
and most importantly—why a pod is failing. Look at the "Events" section at the bottom for clues.
kubectl --kubeconfig=/path/to/kubeconfig.yaml describe pod <pod-name> -n <namespace>Get full pod YAML (spec + volumes)
Need to see the complete pod specification including environment variables, volumes, and resource limits?
kubectl --kubeconfig=/path/to/kubeconfig.yaml get pod <pod-name> -n <namespace> -o yamlTailing and Analyzing Logs
Logs are your window into what's actually happening inside containers. Whether you're debugging application errors or tracking down performance issues, these commands are essential.
Simple logs from a pod
Basic log retrieval—shows you what the container has been outputting recently:
kubectl --kubeconfig=/path/to/kubeconfig.yaml logs <pod> -n <namespace>Logs of pods selected by label (aggregates logs from all matching pods)
When you have multiple replicas, this aggregates logs from all pods matching the label. Super handy for seeing patterns across your deployment:
kubectl --kubeconfig=/path/to/kubeconfig.yaml logs -n <namespace> -l app=<appname>Follow logs
The -f flag works just like tail -f—it streams logs in real-time. Essential for watching live activity:
kubectl --kubeconfig=/path/to/kubeconfig.yaml logs -f <pod> -n <namespace>Logs for a specific container in a pod
Pods can have multiple containers (sidecars, init containers, etc.). Use -c to specify which container's logs you want:
kubectl --kubeconfig=/path/to/kubeconfig.yaml logs <pod> -c <container> -n <namespace>ConfigMaps & Secrets
ConfigMaps and Secrets are how you inject configuration and sensitive data into your pods. Managing them properly is crucial—especially Secrets, which require extra care.
List ConfigMaps
kubectl --kubeconfig=/path/to/kubeconfig.yaml get configmap -n <namespace>View ConfigMap YAML
kubectl --kubeconfig=/path/to/kubeconfig.yaml get configmap <name> -n <namespace> -o yamlDescribe ConfigMap
kubectl --kubeconfig=/path/to/kubeconfig.yaml describe configmap <name> -n <namespace>Describe Secret (metadata)
kubectl --kubeconfig=/path/to/kubeconfig.yaml describe secret <name> -n <namespace>View Secret (base64 decode) — caution: secrets are sensitive
Secrets are base64-encoded (not encrypted!) in Kubernetes. This command decodes them for viewing.
Be careful—never run this in production logs or share the output publicly.
The jq command formats the output nicely:
kubectl --kubeconfig=/path/to/kubeconfig.yaml get secret <name> -n <namespace> -o jsonpath="{.data}" \
| jq -r 'to_entries[] | "\(.key)=\(.value | @base64d)"'Services & Networking
Services expose your pods to the network. When connectivity issues arise, these commands help you understand how traffic is being routed.
List services
kubectl --kubeconfig=/path/to/kubeconfig.yaml get svc -n <namespace>Describe a service
kubectl --kubeconfig=/path/to/kubeconfig.yaml describe svc <name> -n <namespace>Cluster Events
Events are Kubernetes' way of telling you what's happening under the hood. They're time-limited (usually kept for about an hour), so checking them early in your debugging process is important.
List all events
kubectl --kubeconfig=/path/to/kubeconfig.yaml get events -n <namespace>Filter events for a specific object
When you're debugging a specific pod or deployment, filter events to see only what's relevant. This cuts through the noise in busy clusters:
kubectl --kubeconfig=/path/to/kubeconfig.yaml get events -n <namespace> \
--field-selector involvedObject.name=<name>Interactive Debugging & Access
Sometimes you need to get "inside" a container to poke around, or access a service that isn't exposed externally. These commands are your friends for hands-on debugging.
Exec into a pod (shell)
Open an interactive shell inside a running container. Perfect for checking files, testing network connectivity,
or running diagnostic commands. Note that some minimal containers might only have /bin/sh instead of bash:
kubectl --kubeconfig=/path/to/kubeconfig.yaml exec -it <pod> -n <namespace> -- /bin/bash
# or use /bin/sh if bash is not presentPort-forward to a pod (localPort:remotePort)
This is one of my most-used commands. It creates a secure tunnel from your local machine to a pod, letting you access services as if they were running on localhost. No need to expose ports publicly!
kubectl --kubeconfig=/path/to/kubeconfig.yaml port-forward pod/<pod-name> 8080:80 -n <namespace>Namespace Management
Namespaces are how Kubernetes organizes resources. In multi-tenant clusters or environments with many teams, they're essential for isolation.
List namespaces
kubectl --kubeconfig=/path/to/kubeconfig.yaml get nsApplying & Managing Resources
Beyond inspecting, you need to create, update, and delete resources. These commands handle the lifecycle of your Kubernetes objects.
Apply manifests in a folder
kubectl --kubeconfig=/path/to/kubeconfig.yaml apply -f ./deploy/Delete a resource file
kubectl --kubeconfig=/path/to/kubeconfig.yaml delete -f <file.yaml>Dry-run apply (client-side diff)
Before making changes to a live cluster, always dry-run! This shows you what would happen without actually applying it. It's saved me from many mistakes:
kubectl --kubeconfig=/path/to/kubeconfig.yaml apply -f <file.yaml> --dry-run=client -o yamlPro Tips: Simplifying Your Workflow
Typing --kubeconfig=/path/to/kubeconfig.yaml on every command gets old fast.
Here are some tricks to streamline your workflow.
Export KUBECONFIG to avoid repeating the flag
Set KUBECONFIG as an environment variable in your shell session. Now all kubectl commands will use this config automatically:
export KUBECONFIG=/path/to/kubeconfig.yaml
# then omit --kubeconfig in following commands:
kubectl get pods -n <namespace>Use a different kubeconfig for a single command
Need to quickly switch contexts for one command? Prefix it with the environment variable—no permanent changes needed:
KUBECONFIG=/path/to/kubeconfig.yaml kubectl get pods -n <namespace>Port-Forwarding Deep Dive
Port-forwarding deserves special attention because it's such a versatile tool. Whether you're testing a database connection, debugging a web service, or accessing an admin panel, port-forwarding lets you work as if everything were local. Here's a comprehensive look at different scenarios.
1) Pod → local port (single port)
The most basic form: forward a single port from a pod to your local machine.
After running this, you can access the service at http://localhost:8080:
kubectl --kubeconfig=/path/to/kubeconfig.yaml port-forward pod/<pod-name> 8080:80 -n <namespace>
# access locally at http://localhost:80802) Service → local port
Instead of targeting a specific pod, forward to a service. Kubernetes will automatically route to one of the backing pods—great when you don't care which pod handles the request:
kubectl --kubeconfig=/path/to/kubeconfig.yaml port-forward svc/<service-name> 8080:80 -n <namespace>3) Multiple ports at once
Need to forward HTTP and HTTPS? Or a web server and a metrics endpoint? Just list them all:
kubectl --kubeconfig=/path/to/kubeconfig.yaml port-forward pod/<pod-name> 8080:80 8443:443 -n <namespace>4) Port-forward from a Deployment
Deployments don't have a direct port-forward option, but you can grab the first pod from the deployment and forward to it. This one-liner does the trick:
POD=$(kubectl --kubeconfig=/path/to/kubeconfig.yaml get pod -n <namespace> -l app=<appname> -o jsonpath="{.items[0].metadata.name}")
kubectl --kubeconfig=/path/to/kubeconfig.yaml port-forward pod/$POD 8080:80 -n <namespace>5) Background port-forwarding
Sometimes you want port-forwarding to run in the background while you do other work. This approach redirects output to a log file and saves the process ID so you can kill it later. Note: For production use, consider a more robust solution like a systemd service or supervisor process:
kubectl --kubeconfig=/path/to/kubeconfig.yaml port-forward pod/<pod-name> 8080:80 -n <namespace> > /tmp/portforward.log 2>&1 &
echo $! > /tmp/portforward.pid
# to stop:
kill $(cat /tmp/portforward.pid)6) Dealing with port conflicts
Already have something running on port 8080? No problem—just pick a different local port. The remote port (the one in the container) stays the same:
kubectl --kubeconfig=/path/to/kubeconfig.yaml port-forward pod/<pod-name> 18080:80 -n <namespace>7) Debugging service-to-pod mapping
Ever wonder which pods are actually backing a service? Check the endpoints—they show you the exact pod IPs and ports that the service routes to:
kubectl --kubeconfig=/path/to/kubeconfig.yaml get endpoints <service-name> -n <namespace> -o yamlWrapping Up
These commands form the backbone of my daily Kubernetes workflow. I've probably run kubectl logs -f
and kubectl port-forward thousands of times at this point—they're that useful.
The key to mastering kubectl is muscle memory. Keep this reference handy, but more importantly, use these commands regularly. Over time, you'll develop intuition for which command to reach for in different situations.
Remember: Kubernetes can be complex, but having the right tools at your fingertips makes all the difference. Whether you're troubleshooting production issues or exploring a new cluster, these commands will serve you well.
Happy debugging! 🚀