kubectl port-forward for local access in Kubernetes - Commands & Configuration

Introduction

Sometimes you want to access an app running inside Kubernetes from your own computer without exposing it publicly. kubectl port-forward lets you connect your local computer to a port inside a Kubernetes pod securely and easily.

When you want to test a web app running inside a pod without changing its service or ingress setup

When you need to connect to a database inside Kubernetes for debugging or data checks

When you want to securely access an internal service without opening firewall ports

When you want to forward traffic from your local machine to a pod port for development

When you want to quickly check logs or metrics exposed on a pod port

Commands

This command lists all pods in the current namespace so you can find the pod name to forward ports from.

Terminal

kubectl get pods

Expected Output

NAME                     READY   STATUS    RESTARTS   AGE

my-app-pod-1234567890   1/1     Running   0          10m

This command forwards your local port 8080 to port 80 on the pod named my-app-pod-1234567890. Now you can access the pod's app at http://localhost:8080 on your computer.

Terminal

kubectl port-forward pod/my-app-pod-1234567890 8080:80

Expected Output

Forwarding from 127.0.0.1:8080 -> 80

Forwarding from [::1]:8080 -> 80

This command tests the connection by sending a request to the forwarded local port. It should return the app's response from inside the pod.

Terminal

curl http://localhost:8080

Expected Output

<html><body>Welcome to my app!</body></html>

Key Concept

kubectl port-forward creates a secure tunnel from your local machine to a pod port, letting you access pod services without exposing them externally.

Common Mistakes

Using the pod name incorrectly or misspelling it in the port-forward command

kubectl cannot find the pod and the port-forward fails with an error

Run 'kubectl get pods' first to copy the exact pod name and use it in the command

Trying to forward to a port that the pod is not listening on

The connection will fail because no service is running on that port inside the pod

Check the pod's container ports or app configuration to confirm the correct port

Not keeping the port-forward command running in the terminal

Port forwarding stops as soon as the command exits, losing the connection

Keep the terminal open or run the command in a separate window or background

Summary

Use 'kubectl get pods' to find the pod name you want to access.

Run 'kubectl port-forward pod-name local-port:pod-port' to forward traffic from your computer to the pod.

Test the connection by accessing the forwarded local port in a browser or with curl.

Practice

1. What is the main purpose of kubectl port-forward in Kubernetes?

easy

A. To connect your local machine to a pod or service port inside the cluster

B. To expose a pod to the internet permanently

C. To create a new Kubernetes service

D. To delete a pod from the cluster

Solution

1. Step 1: Understand the function of port-forward

   kubectl port-forward creates a temporary tunnel from your local machine to a pod or service port inside the Kubernetes cluster.

2. Step 2: Compare other options

   Exposing pods permanently or creating/deleting resources are different commands and purposes.

3. Final Answer:

   To connect your local machine to a pod or service port inside the cluster -> Option A

4. Quick Check:

   Port-forward = local to pod/service connection [OK]

Hint: Port-forward = local access to pod/service port [OK]

Common Mistakes:

• Thinking port-forward exposes pods publicly
• Confusing port-forward with service creation
• Assuming it deletes pods

2. Which of the following is the correct syntax to forward local port 8080 to port 80 of a pod named my-pod?

easy

A. kubectl port-forward my-pod 80:8080

B. kubectl port-forward pod/my-pod 80:8080

C. kubectl port-forward my-pod 8080

D. kubectl port-forward pod/my-pod 8080:80

Solution

1. Step 1: Understand port-forward syntax

   The syntax is kubectl port-forward [resource-type/resource-name] localPort:remotePort. So to forward local 8080 to pod port 80, use 8080:80.

2. Step 2: Identify correct resource format

   Pod resource must be specified as pod/my-pod for clarity and correctness.

3. Final Answer:

   kubectl port-forward pod/my-pod 8080:80 -> Option D

4. Quick Check:

   Syntax = kubectl port-forward pod/name localPort:remotePort [OK]

Hint: Use pod/name and localPort:remotePort format [OK]

Common Mistakes:

• Reversing port numbers (remote:local instead of local:remote)
• Omitting 'pod/' prefix
• Swapping ports in the command

3. Given the command kubectl port-forward svc/my-service 9090:80, what will happen when you open http://localhost:9090 in your browser?

medium

A. You will access the pod's port 9090 directly

B. You will access the service's port 80 through local port 9090

C. You will get a connection refused error

D. The command will fail because services cannot be port-forwarded

Solution

1. Step 1: Understand port-forward to service

   The command forwards local port 9090 to port 80 of the service my-service. So accessing localhost:9090 connects to service port 80.

2. Step 2: Confirm service port-forward support

   Kubectl supports port-forwarding to services, so the command works and forwards traffic correctly.

3. Final Answer:

   You will access the service's port 80 through local port 9090 -> Option B

4. Quick Check:

   Port-forward svc port works = access via local port [OK]

Hint: Local port maps to service port, access via localhost:localPort [OK]

Common Mistakes:

• Thinking services cannot be port-forwarded
• Confusing local and remote ports
• Expecting pod port 9090 instead of service port 80

4. You run kubectl port-forward pod/my-pod 8080:80 but get the error: error: unable to forward port because pod is not running. What is the most likely cause?

medium

A. The pod my-pod is not in Running state

B. You used the wrong port numbers

C. Port-forward does not work with pods

D. You need to specify the namespace explicitly

Solution

1. Step 1: Analyze error message

   The error says the pod is not running, so port-forward cannot connect to it.

2. Step 2: Check pod state requirement

   Port-forward requires the pod to be in Running state to forward ports successfully.

3. Final Answer:

   The pod my-pod is not in Running state -> Option A

4. Quick Check:

   Pod must be Running for port-forward [OK]

Hint: Pod must be Running to port-forward [OK]

Common Mistakes:

• Assuming port numbers cause this error
• Thinking port-forward doesn't work with pods
• Ignoring pod status before port-forward

5. You want to access two different pods pod-a and pod-b running on ports 8080 and 9090 respectively, on your local machine at ports 3000 and 4000 simultaneously. Which commands should you run?

hard

A. kubectl port-forward pod/pod-a 3000:8080; kubectl port-forward pod/pod-b 4000:9090

B. kubectl port-forward pod/pod-a 8080:3000 & kubectl port-forward pod/pod-b 9090:4000

C. kubectl port-forward pod/pod-a 3000:8080 & kubectl port-forward pod/pod-b 4000:9090

D. kubectl port-forward pod/pod-a 3000:8080 pod/pod-b 4000:9090

Solution

1. Step 1: Understand port-forward syntax and concurrency

   Each port-forward command forwards one pod port to a local port. To run two simultaneously, run two commands in parallel using & or separate terminals.

2. Step 2: Verify port mappings

   Local port 3000 maps to pod-a's 8080, and local 4000 maps to pod-b's 9090. The syntax is localPort:remotePort.

3. Step 3: Check command correctness

   kubectl port-forward pod/pod-a 3000:8080 & kubectl port-forward pod/pod-b 4000:9090 correctly runs two commands in background with correct port mappings. kubectl port-forward pod/pod-a 3000:8080; kubectl port-forward pod/pod-b 4000:9090 runs sequentially, blocking second command.

4. Final Answer:

   kubectl port-forward pod/pod-a 3000:8080 & kubectl port-forward pod/pod-b 4000:9090 -> Option C

5. Quick Check:

   Run two port-forwards in parallel with correct local:remote ports [OK]

Hint: Run separate port-forward commands in background for multiple pods [OK]

Common Mistakes:

• Swapping local and remote ports
• Trying to port-forward multiple pods in one command
• Running commands sequentially blocking second port-forward