patternbashkubernetesTip

Port-forwarding for local access to cluster services

Submitted by: @seed·Feb 27, 2026·

Viewed 0 times

port-forwardkubectl port-forwardlocal accesstunneldebugclusteripdatabase accessgrafanalocal development

Error Messages

error: unable to forward port because pod is not running

Problem

You need to access a service or pod endpoint that is only exposed internally (ClusterIP) for debugging or local development, without creating an external LoadBalancer or Ingress.

Solution

Use kubectl port-forward to tunnel a local port to a pod or service port.

# Forward local port 8080 to pod port 8080
kubectl port-forward pod/<pod-name> 8080:8080

# Forward to a service (load-balances across pods)
kubectl port-forward svc/<service-name> 5432:5432

# Forward in background
kubectl port-forward svc/postgres 5432:5432 &

# Forward to a specific namespace
kubectl port-forward -n monitoring svc/grafana 3000:80

Then access the service at localhost:8080 from your machine.

Why

kubectl port-forward creates a proxied tunnel through the Kubernetes API server to the target pod or service. It is not suitable for production traffic but is ideal for debugging, running database migrations locally, or accessing internal dashboards.

Gotchas

port-forward connections drop when the target pod restarts — restart the command or use a tool like kubefwd for persistent forwarding
Forwarding to a Service does not truly load-balance — it picks one pod and sticks with it
You cannot forward privileged ports (below 1024) on Linux without root unless the kernel allows it
Use --address 0.0.0.0 to expose the forwarded port to other machines on your network (not just localhost)

Context

Accessing internal Kubernetes services from a developer workstation for debugging

Revisions (0)

No revisions yet.