debug
kubectl port-forward
Forwards one or more local ports to a pod, service, or deployment inside the cluster via the API server. Ideal for reaching internal services (databases, admin UIs) from your laptop without exposing them publicly.
kubectl port-forward TYPE/NAME [LOCAL_PORT:]REMOTE_PORT [...] [flags]Common flags
| Flag | Purpose |
|---|---|
| --address | Local addresses to bind (default 127.0.0.1; use 0.0.0.0 to expose on LAN). |
| -n, --namespace | Namespace of the target resource. |
| --pod-running-timeout | How long to wait for at least one pod to be running (default 1m). |
Examples
kubectl port-forward svc/postgres 5432:5432Reach an in-cluster Postgres from localhost:5432.
kubectl port-forward deploy/api 8080:80Map local 8080 to the api pod's container port 80.
kubectl port-forward -n monitoring svc/grafana 3000:3000 --address 0.0.0.0Expose Grafana to your local network.
Gotcha
The tunnel dies if the target pod restarts; wrap it in a loop for long sessions. Forwarding to a Service picks a single backing pod, not the load-balanced VIP.
Related commands
kubectl proxy
Runs a local HTTP proxy that authenticates as your kubeconfig user and forwards requests to the Kubernetes API server. Useful for exploring the raw API with curl or serving the dashboard behind localhost auth.
kubectl exec
Executes a command inside a running container. Use -it for an interactive TTY shell; omit them for a one-shot command whose stdout you want to capture for scripts.
kubectl get
Lists one or more resources of a given type from the cluster. It is the primary read command for pods, services, deployments, and any other Kubernetes object, with flexible output formats for scripting and inspection.
kubectl logs
Prints container logs from a pod, deployment, or other workload. Supports streaming, previous-instance recovery after crashes, and selecting a specific container in multi-container pods.
kubectl cp
Copies files and directories between your local filesystem and a container in a pod. Uses tar under the hood, so the target container must have a working tar binary on its PATH.