What is kubectl port-forward?

In short, it creates a direct, temporary tunnel between your local computer and a Kubernetes pod or service, so you can interact with internal apps like databases, APIs, or dashboards as if they were running locally.

When do you use kubectl port-forward?

Sometimes you need to access something inside your cluster that’s not exposed via a LoadBalancer or Ingress. Maybe you’re testing, debugging, or checking logs, but you don’t want to (or shouldn’t) expose the service externally.

Common use cases:

• Debugging internal microservices.
• Connecting to in-cluster databases.
• Viewing internal dashboards (like Prometheus or Grafana).
• Running local tests on services without exposing them.

How Does kubectl port-forward Work?

It forwards traffic from a local port on your machine to a port inside a Kubernetes pod or service.
Kubernetes handles the connection securely over the API server—no changes to your cluster networking required.

Example Usage

Forward a local port to a pod:

kubectl port-forward pod/my-pod-name 8080:80
Copy Code

This forwards localhost:8080 on your machine to port 80 on my-pod-name.

Forward a local port to a service:

kubectl port-forward svc/my-service 5432:5432
Copy Code

Now you can connect to localhost:5432, and traffic goes to your Kubernetes service on port 5432.

How to kubectl port-forward for Multiple Services

While kubectl port-forward is designed to forward traffic to one resource per command, you can port-forward multiple services at the same time by opening multiple terminal sessions—one per service.

Example setup for multiple services:

Terminal 1 – Forward service A:

kubectl port-forward svc/service-a 8080:80
Copy Code

Terminal 2 – Forward service B:

kubectl port-forward svc/service-b 9090:90
Copy Code

Now, locally, you can access:

• Service A on http://localhost:8080
• Service B on http://localhost:9090

What if you want to automate this?

You can run them in the background or script them. For example, with nohup or &:

kubectl port-forward svc/service-a 8080:80 &
kubectl port-forward svc/service-b 9090:90 &
Copy Code

⚠️ Important: Each port-forward session is independent. If one fails or the pod restarts, you’ll need to restart that individual forward.

For more complex workflows (like managing dozens of port forwards), developers often use tools like:

• kubefwd – which automates port-forwarding multiple services.
• telepresence – for more advanced local development.

Benefits of kubectl port-forward

• Access internal services securely from your laptop.
• No need to expose services externally.
• Quick setup—no changes to manifests or YAML needed.
• Works over your existing kubectl connection.

Limitations

• Stops when your terminal closes.
• One connection per service or pod (no built-in bulk forwarding).
• Not ideal for high-load or production traffic—just for development and debugging.

Similar Concepts