Kubernetes port-forwarding lets you access a service running inside your cluster from your local machine, as if it were running locally.
Here’s how it works:
kubectl port-forward pod/my-pod-12345 8080:80
This command tells kubectl to establish a connection to the my-pod-12345 pod. It then forwards traffic from your local machine’s port 8080 to port 80 inside that pod. You can then access your application by navigating to http://localhost:8080 in your browser or using tools like curl.
You can also port-forward to a service, which is often more useful as it abstracts away the individual pods:
kubectl port-forward service/my-service 9000:80
This command forwards local port 9000 to port 80 of the my-service service. kubectl will automatically select a healthy pod backing that service and establish the connection.
This is incredibly useful for debugging. Instead of deploying your application to a remote environment and trying to debug it there, you can run it locally, expose it via port-forward, and then connect your local debugger or inspect logs directly.
Let’s say you have a web application running in a Kubernetes pod, and you want to test a new feature that involves an API call. You can port-forward to the pod running your web application and then make requests from your local machine using curl or your browser.
# Forward local port 5000 to port 3000 on the pod
kubectl port-forward pod/webapp-pod-abcde 5000:3000
# In another terminal, make a request to your local port
curl http://localhost:5000/api/v1/new-feature
The request hits your local port 5000, kubectl forwards it to port 3000 on the webapp-pod-abcde, and the response comes back the same way.
You can also forward multiple ports simultaneously. If your application has a web interface on port 80 and an API on port 8080, you can do:
kubectl port-forward pod/my-app-pod 8080:80,9090:8080
This forwards local port 8080 to port 80 on the pod, and local port 9090 to port 8080 on the pod.
The trick to port-forwarding is understanding that kubectl is acting as a proxy. It establishes a connection to the Kubernetes API server, which then instructs the kubelet on the node where your pod is running to set up a tunnel. Your local kubectl client then communicates over this tunnel.
This means that the kubectl port-forward command needs to keep running for the connection to stay active. If you close the terminal or interrupt the kubectl process, the port-forwarding stops.
A common pattern for development is to have a kubectl port-forward command running in one terminal while you work on your code and test it in another.
You can also use port-forward to access databases or other backend services running within your cluster. For instance, if you have a PostgreSQL database running in a pod:
kubectl port-forward service/postgres-db 5432:5432
Now, you can connect your local PostgreSQL client (like psql or pgAdmin) to localhost:5432 and interact with your database directly.
When port-forwarding to a service, kubectl selects one of the pods backing that service. If the selected pod dies, kubectl will attempt to reconnect to another healthy pod. However, it’s not a perfectly seamless failover; you might experience a brief interruption. For consistent access during development, port-forwarding directly to a specific pod is sometimes preferred, though it means you’ll need to manually update the port-forward command if that pod is replaced.
The kubectl port-forward command relies on the Kubernetes API server and the kubelet. If either of those are inaccessible from your local machine, port-forwarding won’t work. Ensure your kubeconfig is correctly set up and that you have network access to your cluster’s API endpoint.
The kubectl port-forward command is fundamentally a client-side operation that leverages the control plane to establish a connection. It doesn’t involve creating any Kubernetes resources like Services or Ingresses. This makes it ideal for ephemeral debugging sessions without altering your cluster’s configuration.
When you use kubectl port-forward, the traffic is routed through the Kubernetes API server. This means that network policies and firewalls that apply to the API server can affect your ability to port-forward. If you are having trouble connecting, check if your network allows outbound connections to the Kubernetes API server on its designated port (usually 443).
The next hurdle you’ll likely encounter is understanding how to manage multiple port-forwarding sessions efficiently, especially when dealing with complex microservice architectures.