kubectl port-forward for local access in Kubernetes - Step-by-Step Execution

Process Flow - kubectl port-forward for local access

Start kubectl port-forward

↓

Connect local port to pod port

↓

Listen on local port

↓

Forward traffic to pod

↓

Access pod service locally

↓

Stop port-forward on user interrupt

This flow shows how kubectl port-forward connects a local port to a pod port, allowing local access to pod services.

Execution Sample

Kubernetes

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

This command forwards local port 8080 to port 80 on the pod named 'my-pod'.

Process Table

Step	Action	Local Port	Pod Port	Result
1	Start port-forward command	-	-	kubectl starts listening on local port 8080
2	Connect local port to pod port	8080	80	Traffic on local 8080 will go to pod port 80
3	User accesses localhost:8080	8080	80	Request forwarded to pod's port 80
4	Pod responds	8080	80	Response sent back to local client
5	User stops port-forward	-	-	kubectl stops forwarding and exits

💡 User interrupts port-forward, stopping the connection

Status Tracker

Variable	Start	After Step 1	After Step 2	After Step 3	After Step 4	Final
Local Port Listening	No	Yes (8080)	Yes (8080)	Yes (8080)	Yes (8080)	No
Pod Port Connected	No	No	Yes (80)	Yes (80)	Yes (80)	No
Traffic Flow	None	None	None	Forwarded	Response	Stopped

Key Moments - 3 Insights

Why do we specify two ports like 8080:80 in the command?

The first port (8080) is the local machine port to listen on, and the second port (80) is the pod's port to forward traffic to, as shown in execution_table step 2.

What happens if the local port 8080 is already in use?

kubectl will fail to start port-forward because it cannot listen on the local port, so step 1 in execution_table will not succeed.

Does port-forward keep running after the command finishes?

No, port-forward runs until the user stops it manually, as shown in step 5 where the forwarding stops on user interrupt.

Visual Quiz - 3 Questions

Look at the execution table, at which step does traffic start forwarding from local port to pod port?

A Step 3

B Step 2

C Step 1

D Step 5

💡 Hint

Check the 'Result' column in step 2 where connection is established.

According to variable_tracker, what is the state of 'Local Port Listening' after step 5?

A No

B Yes (8080)

C Unknown

D Listening on pod port

💡 Hint

Look at the 'Local Port Listening' row under 'Final' column.

If the user changes the command to 'kubectl port-forward pod/my-pod 9090:80', what changes in the execution table?

A No change in ports

B Pod Port changes to 9090

C Local Port changes to 9090 in all steps

D Both ports change to 9090

💡 Hint

Refer to the 'Local Port' column in execution_table.

Concept Snapshot

kubectl port-forward <pod-name> <local-port>:<pod-port>
- Forwards local port to pod port
- Allows local access to pod services
- Runs until user stops it
- Local port must be free
- Useful for debugging or accessing pod apps

Full Transcript

kubectl port-forward lets you connect a port on your computer to a port on a Kubernetes pod. You run a command like 'kubectl port-forward pod/my-pod 8080:80'. This means your local port 8080 will send traffic to port 80 on the pod. When you open localhost:8080 in your browser, the request goes to the pod's port 80. The command keeps running and forwarding traffic until you stop it. If the local port is busy, the command won't start. This is useful to access pod services without exposing them externally.

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