KEP-5695: kubectl reverse port-forward #5697

willianpaixao · 2025-11-18T19:14:22Z

What type of PR is this?
/kind kep

What this PR does / why we need it:
Adds KEP for reverse port-forwarding in kubectl, addressing long-standing issue kubernetes/kubernetes#20227.

Which issue(s) this PR fixes:
Fixes #5695
Addresses kubernetes/kubernetes#20227

Special notes for your reviewer:
This KEP proposes adding `--reverse` flag to `kubectl port-forward` to enable
reverse tunneling (pod → local machine), similar to SSH's `-R` flag.

This has been a requested feature since 2016 and received a PoC implementation
in 2017 (PR kubernetes/kubernetes#57320) that was deferred pending SPDY deprecation.

/sig cli
/sig node

Add reverse port-forwarding capability to kubectl, enabling pods to connect to services running on the developer's local machine. This addresses kubernetes/kubernetes#20227 which has been open since 2016 with significant community interest. Signed-off-by: Willian Paixao <[email protected]>

linux-foundation-easycla · 2025-11-18T19:14:30Z

The committers listed above are authorized under a signed CLA.

✅ login: willianpaixao / name: willian.eth (1b0dd3c, 3799c78, ece5dd7)

k8s-ci-robot · 2025-11-18T19:14:31Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: willianpaixao
Once this PR has been reviewed and has the lgtm label, please assign soltysh for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

keps/sig-cli/OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

k8s-ci-robot · 2025-11-18T19:14:32Z

Welcome @willianpaixao!

It looks like this is your first PR to kubernetes/enhancements 🎉. Please refer to our pull request process documentation to help your PR have a smooth ride to approval.

You will be prompted by a bot to use commands during the review process. Do not be afraid to follow the prompts! It is okay to experiment. Here is the bot commands documentation.

You can also check if kubernetes/enhancements has its own contribution guidelines.

You may want to refer to our testing guide if you run into trouble with your tests not passing.

If you are having difficulty getting your pull request seen, please follow the recommended escalation practices. Also, for tips and tricks in the contribution process you may want to read the Kubernetes contributor cheat sheet. We want to make sure your contribution gets all the attention it needs!

Thank you, and welcome to Kubernetes. 😃

k8s-ci-robot · 2025-11-18T19:14:32Z

Hi @willianpaixao. Thanks for your PR.

I'm waiting for a github.com member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

Copilot

Pull Request Overview

This PR introduces KEP-5695, which proposes adding reverse port-forwarding capability to kubectl port-forward. This feature would enable containers in Kubernetes pods to connect back to services running on a developer's local machine, similar to SSH's -R flag. This addresses a long-standing feature request from 2016 (issue #20227).

Adds a new --reverse flag to kubectl port-forward for reverse tunneling
Introduces protocol extensions to support bidirectional streaming between pods and local machines
Includes comprehensive graduation criteria from alpha (v1.34) through GA (v1.36)

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 7 comments.

File	Description
keps/sig-cli/5695-kubectl-reverse-port-forward/kep.yaml	Defines KEP metadata including feature gates (KubectlReversePortForward), milestones, and basic metrics configuration
keps/sig-cli/5695-kubectl-reverse-port-forward/README.md	Comprehensive KEP documentation covering motivation, design details, test plans, graduation criteria, and production readiness considerations

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-11-18T19:16:59Z

keps/sig-cli/5695-kubectl-reverse-port-forward/README.md

+
+Metrics will expose:
+- `kubectl_portforward_reverse_connections_total`: Counter of reverse port-forward connections
+- `kubectl_portforward_reverse_active_connections`: Gauge of currently active connections


Inconsistent naming: the metric is called kubectl_portforward_reverse_active_connections in line 452 (Monitoring Requirements section), but this metric is not listed in the kep.yaml file (lines 44-46) where only kubectl_portforward_reverse_connections_total and kubectl_portforward_reverse_errors_total are defined. Either add this metric to kep.yaml or remove the reference here.

Suggested change

- `kubectl_portforward_reverse_active_connections`: Gauge of currently active connections

Copilot · 2025-11-18T19:17:00Z

keps/sig-cli/5695-kubectl-reverse-port-forward/README.md

+- Metrics:
+  - `kubectl_portforward_reverse_connections_total` - labeled by status (success/failure)
+  - `kubectl_portforward_reverse_errors_total` - labeled by error type
+  - `kubectl_portforward_reverse_connection_duration_seconds` - histogram
+  - `kubelet_portforward_reverse_listeners_active` - gauge


Additional metrics are mentioned in the SLIs section (kubectl_portforward_reverse_connection_duration_seconds and kubelet_portforward_reverse_listeners_active) that are not listed in the kep.yaml metrics section (lines 44-46). All metrics that will be implemented should be documented in the kep.yaml file.

Copilot · 2025-11-18T19:17:00Z

keps/sig-cli/5695-kubectl-reverse-port-forward/README.md

+**5. Implementation Components:**
+
+- **Port Listener**: Create a TCP listener in the pod's network namespace
+  - Native Go implementation using netns library.


[nitpick] Spelling error: "netns library" should likely specify which library is being referred to. Consider clarifying this as "a Go network namespace library (such as vishvananda/netns)" or similar to be more explicit about the implementation approach.

Suggested change

- Native Go implementation using netns library.

- Native Go implementation using a Go network namespace library (such as [vishvananda/netns](https://github.com/vishvananda/netns)).

keps/sig-cli/5695-kubectl-reverse-port-forward/README.md

keps/sig-cli/5695-kubectl-reverse-port-forward/kep.yaml

keps/sig-cli/5695-kubectl-reverse-port-forward/README.md

Copilot · 2025-11-18T19:17:02Z

keps/sig-cli/5695-kubectl-reverse-port-forward/README.md

+**Example:**
+```bash
+# Run webhook locally
+./my-webhook --port 9443
+
+# Expose it to the API server pod
+kubectl port-forward --reverse -n kube-system api-server-pod 9443:9443
+
+# Now the API server can call https://localhost:9443 for webhook validation
+```


The API server pod example in this user story is not realistic. The API server does not run as a regular pod that can be accessed via kubectl port-forward in this manner. Consider using a more realistic example, such as a webhook server pod that needs to call a locally running service, or a sidecar proxy pod.

I think copilot is right on this

- Detail required unit tests and existing test infrastructure. - Update E2E test requirements. - Update Graduation Criteria to include enabling existing test stubs. - Update Implementation History with test infrastructure preparation. Signed-off-by: Willian Paixao <[email protected]>

Signed-off-by: Willian Paixao <[email protected]>

aojea · 2025-11-19T16:09:55Z

keps/sig-cli/5695-kubectl-reverse-port-forward/README.md

+1. Establish a connection to the kubelet running the target pod
+2. Create a listener in the pod's network namespace on the specified remote port
+3. Forward incoming connections from that port back to kubectl
+4. kubectl will then forward these connections to the specified local port


have you checked how this work in detail?
I think that this is not simple as you describe here, specially since there are parts that are implemented in the runtime itself

aojea · 2025-11-19T16:10:26Z

keps/sig-cli/5695-kubectl-reverse-port-forward/README.md

+# In another terminal, expose it to the pod
+kubectl port-forward --reverse mypod 8080:8080
+
+# Now the pod can access http://localhost:8080 which goes to my local machine


does it means that you go and connect to the pod and from the pod do a request to the server?

aojea · 2025-11-19T16:13:59Z

keps/sig-cli/5695-kubectl-reverse-port-forward/README.md

+
+**2. Kubelet Changes** (`pkg/kubelet/`):
+- Extend PortForward API to support reverse mode
+- Implement pod network namespace listener creation using `socat` or native Go listeners


we removed socat dependency, we should not bring it back

aojea · 2025-11-19T16:14:25Z

keps/sig-cli/5695-kubectl-reverse-port-forward/README.md

+  - Establishes connections to local ports
+  - Forwards traffic bidirectionally
+
+**2. Kubelet Changes** (`pkg/kubelet/`):


you also need to do container runtime changes https://github.com/containerd/containerd/blob/4ab5ee32ad3e1b22cc2f33cf1163ba9df23454cb/internal/cri/streamingserver/server.go#L97 and https://github.com/cri-o/cri-o/blob/e4695a6db271f1f3214e07c3d580d61ef6001b36/server/container_portforward.go#L25

Copilot AI review requested due to automatic review settings November 18, 2025 19:14

k8s-ci-robot added kind/kep Categorizes KEP tracking issues and PRs modifying the KEP directory sig/cli Categorizes an issue or PR as relevant to SIG CLI. sig/node Categorizes an issue or PR as relevant to SIG Node. labels Nov 18, 2025

github-project-automation bot added this to SIG CLI Nov 18, 2025

github-project-automation bot moved this to Needs Triage in SIG CLI Nov 18, 2025

k8s-ci-robot added the needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. label Nov 18, 2025

k8s-ci-robot requested a review from ardaguclu November 18, 2025 19:14

k8s-ci-robot added the cncf-cla: no Indicates the PR's author has not signed the CNCF CLA. label Nov 18, 2025

k8s-ci-robot requested a review from mpuckett159 November 18, 2025 19:14

k8s-ci-robot added the size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. label Nov 18, 2025

Copilot started reviewing on behalf of willianpaixao November 18, 2025 19:14 View session

Copilot finished reviewing on behalf of willianpaixao November 18, 2025 19:16

Copilot AI reviewed Nov 18, 2025

View reviewed changes

k8s-ci-robot added cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. and removed cncf-cla: no Indicates the PR's author has not signed the CNCF CLA. labels Nov 18, 2025

willianpaixao added 2 commits November 19, 2025 11:58

KEP-5695: Add troubleshooting section inspired from KEP-4006

3799c78

Signed-off-by: Willian Paixao <[email protected]>

aojea reviewed Nov 19, 2025

View reviewed changes

	- Native Go implementation using netns library.
	- Native Go implementation using a Go network namespace library (such as [vishvananda/netns](https://github.com/vishvananda/netns)).

KEP-5695: kubectl reverse port-forward #5697

Are you sure you want to change the base?

KEP-5695: kubectl reverse port-forward #5697

Conversation

willianpaixao commented Nov 18, 2025

Uh oh!

linux-foundation-easycla bot commented Nov 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

k8s-ci-robot commented Nov 18, 2025

Uh oh!

k8s-ci-robot commented Nov 18, 2025

Uh oh!

k8s-ci-robot commented Nov 18, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

aojea Nov 19, 2025

Choose a reason for hiding this comment

Uh oh!

aojea Nov 19, 2025

Choose a reason for hiding this comment

Uh oh!

aojea Nov 19, 2025

Choose a reason for hiding this comment

Uh oh!

aojea Nov 19, 2025

Choose a reason for hiding this comment

Uh oh!

aojea Nov 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

linux-foundation-easycla bot commented Nov 18, 2025 •

edited

Loading

aojea Nov 19, 2025 •

edited

Loading