Implement Custom Bind Address for Port Forwarding

[geoffreyPerrin]

Overview

This pull request introduces a new feature that allows users to specify a custom bind address for port forwarding within the kr8s project. This enhancement provides greater flexibility in network configurations and enhances usability for environments requiring specific binding settings.

Changes

• Added functionality to choose a custom bind address for port forwarding.
• Updated relevant methods to handle the additional parameter for the bind address.
• Ensured backward compatibility with existing function calls by setting default bind address values.

Impact

• Users can now define a specific bind address when setting up port forwarding, offering better control over network traffic routing.
• No impact on existing functionality; all previous configurations without a specified bind address will continue to work as before.

Tests

• Conducted tests to ensure that the new feature works as expected in various scenarios.
• Ensured that all existing tests pass without modifications, confirming backward compatibility.

How to Test

1. Update to the latest version of the kr8s project.
2. Utilize the new parameter for specifying the bind address in your port forwarding setup.
3. Verify that the port forwarding works as expected with the custom bind address.

Your feedback and suggestions on this feature are greatly appreciated!

[codecov]

Codecov Report

Attention: 8 lines in your changes are missing coverage. Please review.

Comparison is base (e4548f1) 94.72% compared to head (86d8ef4) 94.70%.
Report is 2 commits behind head on main.

Files	Patch %	Lines
kr8s/portforward.py	0.00%	4 Missing ⚠️
kr8s/_objects.py	80.00%	2 Missing ⚠️
kr8s/_portforward.py	92.85%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #267      +/-   ##
==========================================
- Coverage   94.72%   94.70%   -0.03%     
==========================================
  Files          27       27              
  Lines        2768     2814      +46     
==========================================
+ Hits         2622     2665      +43     
- Misses        146      149       +3     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[jacobtomlinson]

This change seems like a good idea, thanks!

One of our core goals here is to make the API "feel" as close to kubectl as possible. Here are a couple of examples of setting the explicit address taken from kubectl port-forward --help.

# Listen on port 8888 on all addresses, forwarding to 5000 in the pod
kubectl port-forward --address 0.0.0.0 pod/mypod 8888:5000
  
# Listen on port 8888 on localhost and selected IP, forwarding to 5000 in the pod
kubectl port-forward --address localhost,10.19.21.23 pod/mypod 8888:5000

Three things stand out to me after reading the help:

• The flag is --address so we should probably call the kwarg address instead of bind_address
• You can specify multiple addresses, we should allow the same. Probably as an iterable rather than a comma-separated string though.
• By default kubectl only listens on the 127.0.0.1 loopback address and you have to explicitly set 0.0.0.0 to listen on all addresses. We should probably update our default to do the same.

A few other things need doing before we can merge:

• Can you update the Service.portforward() method too?
• Can you add an example to the docstrings, similar to the one from kubectl port-forward --help?
• Can you add a small test to ensure it is listening on the expected address?

[jacobtomlinson]

Also, you seem to be new to GitHub, welcome! Your PR is well written.

Two bits of advice for future PRs:

• It's always good to open an issue before a PR to check that the feature is desirable before putting in the time to build it. In this case I'm excited to add this option, but it might've gone a different way.
• In your "How to test section" it would've made my life much easier if you had included a copy/pasteable code snippet that I could've used to give this change a spin.

[jacobtomlinson]

I'm not sure this works as expected any more because with multiple servers we will yield multiple times, which doesn't make sense for a context manager.

Once we have called start_serving on all the servers we probably just need to yield the port number for the first server.

[jacobtomlinson]

This is looking great!

I appreciate you moving the examples around, but we are not quite there. If you could move the examples from docs/index.md to docs/examples/pod_operations.md that would be great. I like to keep the examples on the homepage/README pretty simple, then dive deeper into extra config options in the examples section.

Also if you could run the linter and make sure pre-commit is happy we should be good to merge.

[jacobtomlinson]

Thanks for continuing to iterate on this!

[jacobtomlinson]

Perfect, this seems like a great solution. Thanks for diving in.

[jacobtomlinson]

Thanks for bearing with me and iterating on this so much. It looks like things are good to merge now.