txn2/kubefwd

This is a significant release with major improvements to stability, auto-reconnection capabilities, graceful shutdown handling, and modernized build infrastructure. This release includes contributions from multiple community members and addresses long-standing feature requests.

v1.23.1 contins minor update to brew configuraton

Highlights

• Auto-reconnect on pod changes (BETA): kubefwd now automatically reconnects when pods are rescheduled, restarted, or replaced during rolling updates
• Graceful shutdown with cleanup: Proper cleanup of hosts file entries and allocated IPs on shutdown
• Multi-platform Docker images: Native ARM64 support for Apple Silicon Macs and ARM servers
• Go 1.24: Updated to the latest Go version with improved performance and security

New Features

Auto-Reconnect Architecture (BETA) (PR #296, #273)

kubefwd now uses a more stable informer-based architecture that automatically detects and handles pod lifecycle events. When pods are deleted, rescheduled, or replaced (such as during deployments or rolling updates), kubefwd will automatically re-establish port forwards without requiring a restart.

This addresses one of the most requested features (Issue #21) and significantly improves the development experience when working with dynamic workloads.

Graceful Shutdown Handling

• Hosts file entries are now properly cleaned up on shutdown
• Allocated IP addresses are removed from the loopback interface
• Session-specific hostnames are tracked and removed during cleanup
• Thread-safe shutdown mechanism prevents race conditions during cleanup

New Command Line Flags

--purge-stale-ips / -p

Remove outdated kubefwd host entries from /etc/hosts before startup. This cleans up any stale entries that may have been left from previous sessions that did not shut down cleanly.

sudo kubefwd svc -n default --purge-stale-ips

--refresh-backup / -b

Allow overwriting existing hosts file backups. By default, kubefwd preserves the original backup; this flag allows refreshing it.

sudo kubefwd svc -n default --refresh-backup

--timeout / -t (PR #276)

Added configurable timeout option for port forward connections.

--hosts-path Custom Hosts File Path (PR #299)

Support for specifying a custom hosts file path, useful for containerized environments or testing.

Improvements

Error Handling

• Replaced panic() and os.Exit() calls with proper error returns throughout the codebase
• IP allocation errors now include bounds checking with proper error handling
• Invalid reservation formats now log warnings instead of failing silently
• Improved error logging with additional context for failed connections

Logging Enhancements

• Kubernetes client-go klog output is now redirected through logrus with custom formatting
• Improved log messaging for better debugging
• Added log output for stale entry counts during housekeeping
• Suppressed log output for shell completion commands

Resource Management

• Fixed TCP connection leak in fwdnet - connections are now properly closed
• Thread-safe closure of manual stop channel using sync.Once
• Improved cleanup handling prevents resource leaks

Hostname Handling (PR #241)

• Hostnames are now properly sanitized: only alphanumeric characters and dashes are allowed
• Leading and trailing dashes are stripped
• Invalid characters are replaced with dashes
• Fixes Issue #240

Build and Infrastructure

Multi-Platform Docker Images

Docker images are now built for both linux/amd64 and linux/arm64 platforms:

• txn2/kubefwd:latest - Alpine-based, multi-arch
• txn2/kubefwd:v1.23.0 - Version-tagged, multi-arch
• txn2/kubefwd:latest_alpine-3 - Alpine 3, multi-arch
• txn2/kubefwd:latest_ubuntu-24.04 - Ubuntu 24.04 LTS, multi-arch

Users on Apple Silicon Macs (M1/M2/M3) and ARM-based cloud instances (AWS Graviton, etc.) can now run kubefwd containers natively without emulation.

Base Image Updates

• Ubuntu Docker image updated from 20.04 to 24.04 LTS (supported until 2029)
• Alpine remains at version 3 (latest)
• Improved Dockerfile practices with --no-install-recommends and proper cleanup

Go 1.24

• Migrated to Go 1.24 with toolchain specification
• Updated all dependencies to latest compatible versions
• Static binaries with CGO disabled for maximum compatibility

GoReleaser v2 Configuration

• Migrated to dockers_v2 for simplified multi-platform Docker builds
• Fixed deprecated configuration options
• Excluded problematic Windows ARM builds
• Improved archive naming conventions

Dependency Updates

Security and compatibility updates for:

• golang.org/x/crypto - v0.45.0
• golang.org/x/net - v0.38.0
• golang.org/x/oauth2 - v0.27.0
• golang.org/x/text - v0.3.8
• google.golang.org/protobuf - v1.33.0
• gopkg.in/yaml.v3 - v3.0.1
• github.com/sirupsen/logrus - v1.8.3

Bug Fixes

• Fixed race condition during graceful shutdown where cleanup goroutine could still write to hosts file (PR #301)
• Fixed pod deletion listener to properly detect and handle pod removal (PR #273)
• Fixed resource leak with unclosed TCP connections in fwdnet
• Fixed hostname sanitization for special characters (Issue #240)
• Removed unreachable code paths
• Removed deprecated ioutil package usage (PR #281)

Documentation

• Added comprehensive CLAUDE.md for AI-assisted development
• Expanded README with installation instructions, advanced usage examples, and troubleshooting
• Added IP address allocation scheme documentation
• Expanded README_PACKAGING.md with testing, development, and release documentation
• Added pre-release checklist and GoReleaser configuration details

Breaking Changes

None. This release is fully backward compatible with v1.22.x.

Contributors

Thanks to all contributors who made this release possible:

• @TWRaven - Auto-reconnect informer architecture
• @trinsic-id - Auto-reconnect work
• @yutachaos - Timeout option
• @Bernold1 - Graceful shutdown race condition fix
• @ndj888 - Custom hosts path support
• @stmcginnis - ioutil deprecation fix
• @hosswald - Hostname sanitization
• @loganlinn - Completion command log suppression
• @testwill - Code cleanup
• @cjimti - Code cleanup / Maintainer

Installation

Homebrew (macOS/Linux)

brew install txn2/tap/kubefwd

Docker

docker pull txn2/kubefwd:v1.23.0

Binary Downloads

Download pre-built binaries from the GitHub Releases page.

Available for:

• Linux (amd64, arm64, arm, 386)
• macOS (amd64, arm64)
• Windows (amd64, 386)

Package Managers

• APK (Alpine): kubefwd_arm64.apk, kubefwd_amd64.apk
• DEB (Debian/Ubuntu): kubefwd_arm64.deb, kubefwd_amd64.deb
• RPM (RHEL/CentOS/Fedora): kubefwd_arm64.rpm, kubefwd_amd64.rpm

Upgrade Notes

Upgrading from v1.22.x should be seamless. If you experience any stale hosts file entries from previous versions, use the new --purge-stale-ips flag on first run:

sudo kubefwd svc -n default --purge-stale-ips

Changelog

• 8b44083e43cb9a5cb793862ba4a715f0eaf875d5 Add //goland:noinspection DuplicatedCode annotations to suppress duplicate code warnings across test files
• d1744907155250ae9c621c0b4fa9e423e27520c1 Add //goland:noinspection DuplicatedCode annotations to suppress duplicate code warnings in global_informer_test.go
• 6381db138dc1d666a23c04ac69594d3756d17ec9 Add CountStaleEntries function and log preserved kubefwd host entries during housekeeping
• 4763fbec14385d0bdfe574f197aadb211e619595 Add ResetRegistry function for IP registry reset to support test isolation
• de3ec69edd6c847375555b2c6ebccaaa9d8521e8 Add forceRefresh option to BackupHostFile for conditional backup overwriting and update related test cases
• b8a6011e30ece7db94c49d578dd7b13bf55c73a6 Add purge-stale-ips flag to remove outdated kubefwd host entries prior to startup
• e42eedcc2727dc22602abf26eb9996ffec7fb1ab Add refresh-backup flag to conditionally allow overwriting existing hosts file backups
• 072f26a603cc7260baf0ad4bfda30c98154b83cd Add comprehensive CLAUDE.md file detailing architecture, usage, and contribution policies. Expand README with installation instructions, advanced usage examples, key features, and troubleshooting section. Update .gitignore for artifacts.
• 6ff40ea73de4d8cb4b2e3ce01b98ef94202b018c Add graceful shutdown handling with hosts file cleanup and support for allocated IP removal
• 1b76d9e100e6e99a857f306331a98730eb470790 Add integration tests, including pod reconnects, deployment scaling, rolling updates, cleanup processes, and container-based forwarding.
• 70c09a9fe8854ee4254b2e13ae5ea7461d5a2dc6 Add warning log for invalid reservation format in applyCLIPassedReservations
• 99c05eca8e623d9b95e04613b961a2d138956236 Added timeout option
• 7ba914a1d03ae233a8629b86ab7fb56795d0cff6 Bump github.com/sirupsen/logrus from 1.8.1 to 1.8.3
• 76a2f120318c70ee95a85dcbe91787fe2660d847 Bump golang.org/x/crypto from 0.1.0 to 0.17.0
• 145d7fa252a473e32ed5b20f854816b8b523da53 Bump golang.org/x/crypto from 0.21.0 to 0.31.0
• 772d4dc044d8ac4271ae5db17ac3f3a266394dda Bump golang.org/x/crypto from 0.36.0 to 0.45.0
• 6511a4f1914b0ef4f769c3f9dae95382cc6fcac5 Bump golang.org/x/net from 0.17.0 to 0.23.0
• 70c7b75ca4166069e689bf2349d95e31b550dc11 Bump golang.org/x/net from 0.23.0 to 0.36.0
• 836bfda0a9860d14913193fa86bb8337df30e563 Bump golang.org/x/net from 0.36.0 to 0.38.0
• 47e73f9bea0883021eb6458d14d1b7e50c34a174 Bump golang.org/x/net from 0.7.0 to 0.17.0
• f8746ad9cd49505ab4697e0809284d074e68a464 Bump golang.org/x/oauth2
• 15e5a4dedc3fc871a8d00601fb6e161f32da57e6 Bump google.golang.org/protobuf from 1.27.1 to 1.33.0
• caffbee6e9e80dae6bc2c8cab3b28a31b0c08c6f Bump gopkg.in/yaml.v3 from 3.0.0 to 3.0.1
• 05d770aae956e9973608580c5329783e6b69efd7 Bump gopkg.in/yaml.v3 from 3.0.0-20210107192922-496545a6307b to 3.0.0
• b4d697f2ff581b2f22a7f7062fca23187fc5ce74 Document IP address allocation scheme and examples
• 74d4bf7b70f8d9a8a6e494688e41b345a06abb8b Document purge-stale-ips flag usage and update related examples
• 5256a836c75529d0f33664fb6850041574503bcb Document refresh-backup flag and update usage example
• d3d8b2f52fa86a29f842753ce97550c7a90e0b7d Drop use of deprecated ioutils package
• 358783be104adc15b12ad6727eb2dfd9ced04cf7 Ensure proper closure of TCP connection in fwdnet to prevent resource leaks
• a47eb0b81acb66bef8a402d52b8651ab74786a03 Ensure thread-safe closure of ManualStopChan with sync.Once, improve cleanup handling in fwdport.go
• 84d723efa84b3558a03f706b29d4de88b6a56fe0 Expand .gitignore to include kubefwd
• 9968a9725c31b80676bd08f4c88507091c4d6f40 Expand README_PACKAGING.md with comprehensive testing, development, and release documentation, including test commands, pre-release checklist, and GoReleaser configuration details.
• 43120175a15e95cf08932a7b4ae81000bc93c44a Handle IP allocation errors with bounds check, replace panics with proper error handling
• 7d864f3d1a68f8c644441cd8749cbd8a43f3f4d5 Improve error handling in ReadyInterface: replace panic and os.Exit with proper error returns
• 6d39342ed546346cc12e879b819ca3ee7e12f601 Improve error logging with additional context for failed connections and enhance klog filtering for better log clarity
• dffe117299963438796949412c64971b9818fe97 Improve log messaging in fwdport.go and redirect k8s client-go klog output through logrus with custom formatting
• d0c98b854c7594d444575ee6f98b5f2af457ae25 Introduce container-based integration testing framework for privileged tests, add supporting documentation, scripts for KIND setup, and new fwdport auto-reconnect tests.
• b8155bedac37955365b3c534e7218eba4c97f1a9 Merge remote-tracking branch 'origin/master'
• 549e839db364020e5af87ff4e4bac6b8fd732d43 Migrate to multi-platform Docker images using dockers_v2, update Dockerfile base images, and improve build configuration with platform-specific support.
• 983786fffdf21e3f57ac72a5f86670969ff17b66 PR review + clean up some tests
• c99b61fa0666970a05fe3cd8d3edf5c647b05f85 Refactor tests to improve error handling and cleanup in temporary file and directory operations
• 4a27cbb8ccbb08fb14309dc43550230cf849f83e Remove unused code, redundant comments, and improve consistency in error messages.
• 7d16734bf4a7f280d72d9ca3dbacd089fb7cf732 Replace ClientSet types with kubernetes.Interface, improve locking in RemoveServicePod, handle error in hostfile backup, and enhance shutdown mechanism in service registry.
• 3536f8170c8c0865e54eeb5e5d52fca0092cd22c Track and remove session-specific hostnames for improved cleanup handling
• 5604f7c1254304116f86c9092ecc406ce60ac843 Update .goreleaser.yml for schema validation, optimized archives, and enhanced Docker image configuration
• 96d160b4f38d08627e69069920a37cea070a6383 Update go.mod and go.sum to revise dependencies, migrate to Go 1.24, and include toolchain specification
• ff7518f4e3e16f7e00ceb664938ebc50d131c63e Update tests to replace panic checks with error handling for out-of-bounds cases in GetIp
• 588b36b3e76d8872d3f157db525477073d6b76cf chore: no need to use fmt.Sprintf
• 80564ce23befb5d40ec2afc0b27bcf7f7cb233ca chore: stop concurrency race while the cleanup goroutine is still trying to write to the hosts file when gracefully shutting down the process
• 1cc7a7a6bf9b6e0c59f68688162ef393a35aad00 feat: Add customer hosts path support.
• ca0a37f7305ed3a2b76a6005b79f99d8b6e3d78d feat: Add customer hosts path support.Document update
• bb12c193e53b3c11051bbf32f66bf6401d5758bc fix: Listen for pod deletion
• fade62050e8458ab8a158eed115e17da1321a8bc fix: Remove random formatting issues
• 1bfc17b9006b4c352d627be2cf5882c834787fd8 rework pod event listener to use more stable informer architecture