Understanding Internal Ports and kubectl Port-Forward in Kubernetes

When working with Kubernetes, you often need to expose an application for testing or debugging without altering external ingress. kubectl offers port-forward, a command that bridges a local port to a port inside the cluster. This is where the concept of an internal port becomes critical.

The internal port is the port number your Kubernetes Service or Pod listens on inside the cluster network. In a deployment spec or a service YAML, this is defined as targetPort for Services and containerPort for containers. External ports, defined as port in a Service, are what other in-cluster resources connect to. When you run:

kubectl port-forward svc/my-service 8080:80

you map your local machine’s port 8080 to the internal port 80 of that Service. Kubernetes routes the request from your terminal into the cluster network, hitting the Pod or Pods behind the Service on their internal port.

For Pods, the mapping is direct:

kubectl port-forward pod/my-pod 9090:9090

This lets you hit localhost:9090 to talk straight to the Pod’s process, bypassing any Service routing. This is essential when testing an application before exposing it more broadly or when confirming that an internal port is open and responding.

You can find the internal port by inspecting the Service or Pod manifest:

kubectl get svc my-service -o yaml
kubectl get pod my-pod -o yaml

Look for ports: → targetPort for Services, and containerPort for Pods. These are the internal endpoints your workloads expect. If your kubectl connection fails, the internal port is often the first thing to verify. Wrong port mapping means silent timeouts, 502s, or hanging requests.

kubectl port-forward is not meant for production traffic. It’s a developer’s tool to temporarily bridge the gap between your local machine and the cluster. For production, rely on proper Services, ingress, or load balancer configs. But for quick tests, debugging, or when working behind restrictive firewalls, an internal port forward is often the fastest route to the truth.

Know the difference between the local port, the service port, and the internal port. Misunderstanding this can lead to hours of wasted troubleshooting. Get it right, and you have a precise way to see exactly what’s running inside Kubernetes.

Want to skip the manual setup and see internal ports in action with zero YAML editing? Try it on hoop.dev and get a live connection to your cluster in minutes.