Port Forwarding

Kuberniq makes it easy to forward local ports to pod containers, giving you direct access to services running inside your cluster from your local machine. The port forwarding feature includes intelligent port suggestions, session tracking, and one-click controls.

Kuberniq port forwarding view showing service detail with port forward controls Services list showing available services with port mappings for forwarding

Starting a Port Forward

To start a port forward, open any pod's detail panel and look for the Port Forward section. Kuberniq reads the pod spec and automatically suggests port forwards based on the container port definitions. For example, if a container declares a port named http on container port 8080, Kuberniq suggests forwarding localhost:8080 to pod:8080.

You can accept the suggested ports or customize them:

  • Local port — The port on your machine where traffic will be received. If the suggested port is already in use, Kuberniq selects the next available port.
  • Remote port — The container port to forward traffic to.

Click Start to initiate the port forward. Once active, you can access the service at localhost:<local-port> from your browser, curl, or any other tool.

Intelligent Port Suggestions

Kuberniq inspects the pod's container spec to find declared ports and uses them to pre-fill the port forward dialog. It reads the containerPort definitions from each container, including the port name, number, and protocol. Common patterns are recognized:

  • Ports named http or web (typically 80 or 8080)
  • Ports named https or tls (typically 443 or 8443)
  • Ports named grpc (typically 9090 or 50051)
  • Ports named metrics or prometheus (typically 9090 or 9091)
  • Database ports (5432 for PostgreSQL, 3306 for MySQL, 6379 for Redis, 27017 for MongoDB)

Multiple Sessions

You can run multiple port-forward sessions simultaneously. Each session appears in the port forwarding panel with its own status indicator and controls. This is useful when you need to access multiple services at the same time — for example, forwarding both a web server and its database for local development.

Sessions can target different pods in the same cluster, or pods across different clusters if you have multiple clusters connected.

Session Tracking

Each active port-forward session is tracked with the following information:

  • Pod name and namespace
  • Container name
  • Local port and remote port
  • Status: active, starting, or stopped
  • Cluster context

The status indicator uses color coding: green for active sessions, yellow for sessions that are starting, and gray for stopped sessions.

Start and Stop Controls

Each session has a one-click start/stop toggle. Click Stop to terminate the port forward and release the local port. Click Start to re-establish it. Stopped sessions remain in the list so you can quickly restart them without re-entering the port configuration.

External Port-Forward Detection

Kuberniq is compatible with port-forward sessions started outside the application — for example, via kubectl port-forward in a terminal. While Kuberniq does not manage externally created sessions, it detects local port conflicts and warns you if a suggested port is already in use, preventing binding errors.

Automatic Cleanup

When you disconnect from a cluster (by closing its tab or switching to a different context), all port-forward sessions associated with that cluster are automatically stopped and their local ports are released. This prevents orphaned port forwards from accumulating and consuming local ports. You can also close all sessions manually from the port forwarding panel.