{"id":30778198,"url":"https://github.com/snakeice/kube-tunnel","last_synced_at":"2025-09-05T05:53:40.227Z","repository":{"id":306141610,"uuid":"1025137586","full_name":"snakeice/kube-tunnel","owner":"snakeice","description":"auto kubernetes port forward based on service url like http://service.namespace.svc.cluster.local","archived":false,"fork":false,"pushed_at":"2025-09-04T04:25:20.000Z","size":50539,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-04T06:24:31.338Z","etag":null,"topics":["forward-proxy","kubernetes","mesh","proxy","service-mesh"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/snakeice.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-23T19:30:38.000Z","updated_at":"2025-09-04T04:24:53.000Z","dependencies_parsed_at":"2025-07-23T23:00:00.324Z","dependency_job_id":"6a588c19-3a68-4678-ba0d-3ff9fa488337","html_url":"https://github.com/snakeice/kube-tunnel","commit_stats":null,"previous_names":["snakeice/kube-tunnel"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/snakeice/kube-tunnel","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snakeice%2Fkube-tunnel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snakeice%2Fkube-tunnel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snakeice%2Fkube-tunnel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snakeice%2Fkube-tunnel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/snakeice","download_url":"https://codeload.github.com/snakeice/kube-tunnel/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snakeice%2Fkube-tunnel/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273666007,"owners_count":25146273,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-04T02:00:08.968Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["forward-proxy","kubernetes","mesh","proxy","service-mesh"],"created_at":"2025-09-05T05:53:38.710Z","updated_at":"2025-09-05T05:53:40.207Z","avatar_url":"https://github.com/snakeice.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🚇 kube-tunnel\n\n\u003e A high-performance Kubernetes service proxy with intelligent protocol detection and automatic service discovery\n\n[![Go Version](https://img.shields.io/badge/go-%3E%3D1.25.0-blue.svg?style=flat-square)](https://golang.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://github.com/snakeice/kube-tunnel/pulls)\n\nTransform how you access Kubernetes services with DNS-style routing and zero-config port forwarding. No more manual `kubectl port-forward` commands—just use standard HTTP clients with Kubernetes service names.\n\n## ✨ Features\n\n- 🚀 **Multi-Protocol Support** — HTTP/1.1, HTTP/2 (h2/h2c) and gRPC on a single port\n- ⚡ **Auto Port-Forwarding** — Automatic, cached port-forwards to healthy pods\n- 🌐 **Virtual DNS Interface** — Isolated DNS mode to avoid VPN/hosts conflicts\n- 🏠 **Free Local IP** — Smart allocation (127.0.0.2+) to prevent localhost collisions\n- � **Universal Port Handling** — Handle ALL ports on virtual interface with intelligent port matching\n- �📊 **Health Monitoring** — Lightweight monitoring with Prometheus metrics\n- 🔧 **Zero Configuration** — Works out-of-the-box with sensible defaults\n\n## 🚀 Quick Start\n\n### Installation\n\n```bash\ngit clone https://github.com/snakeice/kube-tunnel\ncd kube-tunnel\ngo build -o kube-tunnel ./cmd\n```\n\n### Basic Usage\n\n1. **Start the proxy** (auto-configures DNS):\n\n```bash\n./kube-tunnel\n```\n\n1. **Start with common options**:\n\n```bash\n# Enable debug logging\n./kube-tunnel -verbose\n\n# Use virtual interface mode for enhanced port handling\n./kube-tunnel -virtual\n\n# Custom port and virtual IP\n./kube-tunnel -port=8080 -virtual -virtual-ip=10.8.0.1\n```\n\n1. **Access services** using Kubernetes DNS names:\n\n```bash\n# HTTP requests\ncurl http://my-service.default.svc.cluster.local/api\n\n# gRPC calls\ngrpcurl api.default.svc.cluster.local:80 list\n\n# HTTPS (with self-signed certs)\ncurl -k https://secure-service.default.svc.cluster.local/health\n```\n\n### 🔌 Enhanced Dual Virtual Interface Architecture\n\nWith virtual interface enabled, kube-tunnel automatically creates **two dedicated virtual interfaces** for optimal performance and conflict resolution:\n\n```bash\n# Enable virtual interface mode (creates both interfaces automatically)\n./kube-tunnel -virtual\n\n# Both interfaces created:\n# • kube-dns0    (10.8.0.1) - DNS resolution for *.svc.cluster.local\n# • kube-proxy0  (10.8.0.2) - Port forwarding to Kubernetes services\n```\n\nNow access services on **ANY port** without conflicts:\n\n```bash\n# Access services on their actual ports\ncurl http://frontend.default.svc.cluster.local:3000/\ncurl http://api.default.svc.cluster.local:8080/health\ncurl http://metrics.monitoring.svc.cluster.local:9090/metrics\n\n# gRPC services on their native ports\ngrpcurl -plaintext grpc-service.default.svc.cluster.local:50051 list\n```\n\n**Architecture Benefits:**\n\n- 🎯 **DNS Interface** (`kube-dns0`) — Dedicated for DNS resolution of Kubernetes services\n- 🔌 **Proxy Interface** (`kube-proxy0`) — Dedicated for kubectl port-forward sessions\n- 🚫 **No Port Conflicts** — Universal port handler redirects traffic efficiently  \n- ⚡ **Auto Port Matching** — Tries to match requested ports, falls back gracefully\n- 📝 **Clear Separation** — Each interface has a single, focused responsibility\n\nThe system automatically:\n\n- 🎯 **Tries to match ports** — Uses the same port for Kubernetes port-forwarding when available\n- 🔄 **Falls back gracefully** — Uses random ports when requested port is unavailable  \n- 📝 **Logs port mapping** — Shows which ports were matched vs. assigned\n\n1. **Monitor status** via built-in dashboard:\n\n```bash\n# Open http://localhost:80/dashboard in your browser\n```\n\n## ⚙️ Configuration\n\n### Command Line Options\n\n| Flag           | Description                   | Default       | Environment Variable  |\n| -------------- | ----------------------------- | ------------- | --------------------- |\n| `-port`        | Port to run proxy on          | `80`          | -                     |\n| `-verbose`     | Enable verbose/debug logging  | `false`       | `LOG_LEVEL=debug`     |\n| `-virtual`     | Enable virtual interface mode | `false`       | `KTUN_USE_VIRTUAL`    |\n| `-virtual-ip`  | Virtual interface IP address  | auto-allocate | `KTUN_VIRTUAL_IP`     |\n| `-health`      | Enable health monitoring      | `true`        | `KTUN_HEALTH_ENABLED` |\n| `-dns-ip`      | DNS server bind IP address    | `127.0.0.1`   | `KTUN_DNS_IP`         |\n| `-max-retries` | Maximum retry attempts        | `2`           | `KTUN_RETRY_MAX`      |\n| `-config`      | Path to config file (YAML)    | -             | -                     |\n| `-help`        | Show help message             | -             | -                     |\n\n\u003e **💡 Tip**: Environment variables take precedence over command line flags. This allows for flexible configuration in different deployment scenarios.\n\n### YAML Configuration\n\nThe application now supports YAML configuration files that can be specified with the `-config` flag:\n\n```bash\n# Run with a specific config file\n./kube-tunnel -config config.yaml\n```\n\nSee [config.example.yaml](config.example.yaml) for all available configuration options and [CONFIG.md](CONFIG.md) for details about the configuration system.\n\n### Environment Variables\n\nAll environment variables use the `KTUN_` prefix for better organization. See [ENV_VARS.md](ENV_VARS.md) for complete documentation.\n\n#### 🏥 Health Monitoring\n\n```bash\nexport KTUN_HEALTH_ENABLED=true         # Enable health monitor\nexport KTUN_HEALTH_INTERVAL=30s         # Interval between health checks\nexport KTUN_HEALTH_TIMEOUT=2s           # Timeout for health checks\nexport KTUN_HEALTH_MAX_FAIL=3           # Maximum failures before marking unhealthy\n```\n\n#### ⚡ Performance Tuning\n\n```bash\nexport KTUN_MAX_IDLE=200                # Maximum idle connections\nexport KTUN_MAX_IDLE_HOST=50            # Maximum idle connections per host\nexport KTUN_MAX_CONNS_HOST=100          # Maximum connections per host\nexport KTUN_FORCE_HTTP2=true            # Force HTTP/2 usage\nexport KTUN_READ_TIMEOUT=30s            # Read timeout\nexport KTUN_WRITE_TIMEOUT=30s           # Write timeout\nexport KTUN_GRPC_TIMEOUT=\"30S\"          # Timeout for gRPC requests\n```\n\n#### 🌐 Network \u0026 Virtual Interface Configuration\n\n```bash\n# Core Network Settings\nexport KTUN_DNS_IP=127.0.0.1            # DNS server bind IP\nexport KTUN_FORWARD_IP=127.0.0.1        # Port forward bind IP\nexport KTUN_USE_VIRTUAL=true            # Enable dual virtual interface mode\n\n# DNS Virtual Interface (for DNS resolution)\nexport KTUN_VIRTUAL_NAME=kube-dns0      # DNS interface name\nexport KTUN_VIRTUAL_IP=10.8.0.1         # DNS interface IP\n\n# Port-Forward Virtual Interface (for kubectl port-forwards)\nexport KTUN_PF_VIRTUAL_NAME=kube-proxy0 # Port-forward interface name  \nexport KTUN_PF_VIRTUAL_IP=10.8.0.2      # Port-forward interface IP\n\n# IP Range Configuration\nexport KTUN_IP_RANGES=\"10.8.0.0/24,10.9.0.0/24\"  # Custom IP ranges for allocation\n```\n\n\u003e **🔧 Dual Interface Mode**: When `KTUN_USE_VIRTUAL=true`, both interfaces are automatically created:\n\u003e\n\u003e - **DNS Interface** handles `*.svc.cluster.local` resolution  \n\u003e - **Port-Forward Interface** handles kubectl port-forward sessions\n\u003e - **No configuration required** — Works out of the box with smart defaults!\n\n#### 🔄 Retry Configuration\n\n```bash\nexport KTUN_RETRY_MAX=2                 # Maximum retry attempts\nexport KTUN_RETRY_DELAY=100ms           # Base delay between retries\n```\n\n#### 🛠️ Development \u0026 Debugging\n\n```bash\nexport KTUN_SKIP_HEALTH=false           # Skip health checks\nexport KTUN_DISABLE_FALLBACK=false      # Disable protocol fallback\nexport LOG_LEVEL=debug                  # Enable debug logging\n```\n\n\u003e **📖 Complete Documentation**: For all available environment variables and migration guide from old variable names, see [ENV_VARS.md](ENV_VARS.md)\n\n#### 🔄 Quick Configuration Examples\n\n```bash\n# Basic setup with dual virtual interfaces (recommended)\nexport KTUN_USE_VIRTUAL=true\n./kube-tunnel\n# Creates: kube-dns0 (10.8.0.1) + kube-proxy0 (10.8.0.2)\n\n# Custom interface names and IPs\nexport KTUN_USE_VIRTUAL=true\nexport KTUN_VIRTUAL_NAME=my-dns-if\nexport KTUN_VIRTUAL_IP=192.168.100.10\nexport KTUN_PF_VIRTUAL_NAME=my-proxy-if  \nexport KTUN_PF_VIRTUAL_IP=192.168.100.11\n./kube-tunnel\n\n# Performance optimized setup\nexport KTUN_USE_VIRTUAL=true\nexport KTUN_MAX_IDLE=500\nexport KTUN_MAX_CONNS_HOST=200\nexport KTUN_FORCE_HTTP2=true\n./kube-tunnel\n\n# Development with extensive logging\nexport KTUN_USE_VIRTUAL=true\nexport LOG_LEVEL=debug\nexport KTUN_HEALTH_ENABLED=false\n./kube-tunnel\n```\n\n### 🔍 Verifying Virtual Interfaces\n\nWhen virtual interface mode is enabled, you can verify the interfaces were created correctly:\n\n```bash\n# Check both virtual interfaces are created\nip addr show | grep -E \"(kube-dns0|kube-proxy0)\"\n\n# Expected output:\n# 47: kube-dns0: \u003cBROADCAST,NOARP,UP,LOWER_UP\u003e ... inet 10.8.0.1/24 scope global kube-dns0\n# 48: kube-proxy0: \u003cBROADCAST,NOARP,UP,LOWER_UP\u003e ... inet 10.8.0.2/24 scope global kube-proxy0\n\n# Check DNS configuration\nresolvectl status | grep -A 5 kube-dns0\n\n# Test DNS resolution\ndig @10.8.0.1 api.default.svc.cluster.local\n```\n\n## 🔧 How It Works\n\n### Architecture Overview\n\n```mermaid\ngraph TB\n    subgraph \"Client Applications\"\n        A1[🌐 HTTP Client]\n        A2[📱 gRPC Client]\n        A3[🔧 curl/wget]\n    end\n\n    subgraph \"kube-tunnel Core\"\n        B1[🎯 DNS Server\u003cbr/\u003ePort 5353]\n        B2[🚇 HTTP Proxy\u003cbr/\u003ePort 80/443]\n        B3[📊 Dashboard\u003cbr/\u003e/dashboard]\n        B4[💾 Cache Layer]\n        B5[� Health Monitor]\n    end\n\n    subgraph \"Dual Virtual Interface Architecture\"\n        C1[🌐 DNS Interface\u003cbr/\u003ekube-dns0 (10.8.0.1)]\n        C2[� Port-Forward Interface\u003cbr/\u003ekube-proxy0 (10.8.0.2)]\n        C3[📡 Universal Port Handler\u003cbr/\u003eANY:PORT → 10.8.0.2:80]\n    end\n\n    subgraph \"Kubernetes Cluster\"\n        D1[🎯 Service Discovery]\n        D2[🏠 Pod Selection]\n        D3[🔌 kubectl port-forward]\n        D4[📦 Target Pods]\n    end\n\n    A1 --\u003e B1\n    A2 --\u003e B1\n    A3 --\u003e B1\n\n    B1 -.-\u003e|*.svc.cluster.local| B2\n    B1 -.-\u003e|Forward other queries| E1[🌍 System DNS]\n\n    B2 --\u003e B4\n    B2 --\u003e B5\n    B4 --\u003e D1\n    D1 --\u003e D2\n    D2 --\u003e D3\n    D3 --\u003e D4\n\n    B2 -.-\u003e|Dual Interface Mode| C1\n    C1 -.-\u003e|DNS Resolution| B1\n    C1 -.-\u003e|Port Redirection| C3\n    C3 --\u003e C2\n    C2 --\u003e D3\n\n    B3 -.-\u003e|Monitor| B5\n    B5 -.-\u003e|Health Checks| D4\n\n    D4 -.-\u003e|Responses| B2\n    B2 -.-\u003e|Responses| A1\n    B2 -.-\u003e|Responses| A2\n    B2 -.-\u003e|Responses| A3\n\n    style B1 fill:#e1f5fe\n    style B2 fill:#f3e5f5\n    style C1 fill:#fff3e0\n    style C2 fill:#fff3e0\n    style D3 fill:#e8f5e8\n```\n\n### Request Flow Diagram\n\n```mermaid\nsequenceDiagram\n    participant C as Client\n    participant DNS as DNS Server\n    participant P as HTTP Proxy\n    participant K8S as Kubernetes API\n    participant POD as Target Pod\n    participant CACHE as Cache Layer\n    participant HEALTH as Health Monitor\n\n    Note over C,POD: Initial Service Discovery \u0026 Setup\n    C-\u003e\u003eDNS: Query: api.default.svc.cluster.local\n    DNS-\u003e\u003eP: Resolve to proxy IP (127.0.0.2)\n    DNS--\u003e\u003eC: Return proxy IP\n\n    Note over C,POD: Request Processing\n    C-\u003e\u003eP: HTTP/gRPC Request\n    P-\u003e\u003eCACHE: Check cached port-forward\n\n    alt Cache Miss\n        CACHE-\u003e\u003eK8S: Discover service \u0026 pods\n        K8S--\u003e\u003eCACHE: Return healthy pods\n        CACHE-\u003e\u003eK8S: Create port-forward\n        K8S--\u003e\u003eCACHE: Port-forward ready (localPort)\n        CACHE-\u003e\u003eHEALTH: Register port-forward\n    else Cache Hit\n        CACHE--\u003e\u003eP: Return cached localPort\n    end\n\n    P-\u003e\u003eHEALTH: Check backend health\n    HEALTH-\u003e\u003ePOD: HEAD /health (optional)\n    POD--\u003e\u003eHEALTH: Health status\n    HEALTH--\u003e\u003eP: Backend status\n\n    P-\u003e\u003ePOD: Forward request (127.0.0.1:localPort)\n    POD--\u003e\u003eP: Response\n    P-\u003e\u003eHEALTH: Update metrics\n    P--\u003e\u003eC: Return response\n\n    Note over C,POD: Background Monitoring\n    loop Every 30s\n        HEALTH-\u003e\u003ePOD: Health check\n        POD--\u003e\u003eHEALTH: Status update\n    end\n```\n\n### Component Interaction\n\n```mermaid\ngraph TD\n    subgraph \"DNS Resolution Layer\"\n        A[DNS Query *.svc.cluster.local] --\u003e B{Query Type?}\n        B --\u003e|A Record| C[Return Proxy IP]\n        B --\u003e|AAAA Record| D[No IPv6 Support]\n        B --\u003e|Other Domains| E[Forward to System DNS]\n    end\n\n    subgraph \"Protocol Detection Layer\"\n        F[Incoming Request] --\u003e G{Protocol Detection}\n        G --\u003e|HTTP/1.1| H[Standard HTTP Handler]\n        G --\u003e|HTTP/2| I[H2C Handler]\n        G --\u003e|gRPC| J[gRPC Headers + Timeouts]\n        G --\u003e|HTTPS| K[TLS Termination]\n    end\n\n    subgraph \"Service Discovery Layer\"\n        L[Parse Service Name] --\u003e M[Kubernetes API Call]\n        M --\u003e N{Service Exists?}\n        N --\u003e|Yes| O[Select Healthy Pod]\n        N --\u003e|No| P[Return 404]\n        O --\u003e Q[Create/Reuse Port-Forward]\n    end\n\n    subgraph \"Enhanced Port Handling\"\n        R[Virtual Interface Request] --\u003e S{Port Specified?}\n        S --\u003e|Yes| T[Try Exact Port Match]\n        S --\u003e|No| U[Use Default Port]\n        T --\u003e V{Port Available?}\n        V --\u003e|Yes| W[Direct Port Mapping]\n        V --\u003e|No| X[Fallback to Random Port]\n        U --\u003e W\n        X --\u003e W\n    end\n\n    C --\u003e F\n    H --\u003e L\n    I --\u003e L\n    J --\u003e L\n    K --\u003e L\n    Q --\u003e R\n    W --\u003e Y[Forward to Pod]\n    Y --\u003e Z[Return Response]\n\n    style C fill:#e1f5fe\n    style L fill:#f3e5f5\n    style Q fill:#e8f5e8\n    style W fill:#fff3e0\n```\n\n### Key Features Flow\n\n1. **DNS Interception** — Captures `*.svc.cluster.local` DNS queries via local DNS server\n2. **Protocol Detection** — Automatically detects HTTP/1.1, HTTP/2, gRPC, and HTTPS protocols\n3. **Service Discovery** — Uses Kubernetes API to find services and select healthy pods\n4. **Smart Port Forwarding** — Creates and caches port-forwards with intelligent port matching\n5. **Virtual Interface** — Optional enhanced mode supporting any port on dedicated interface\n6. **Health Monitoring** — Continuous health checks with Prometheus metrics and dashboard\n7. **Request Proxying** — Forwards requests with protocol-specific optimizations\n8. **Response Delivery** — Returns responses transparently with performance metrics\n\n## 📊 Monitoring \u0026 Health\n\n### Built-in Endpoints\n\n| Endpoint          | Description             |\n| ----------------- | ----------------------- |\n| `/health`         | Basic health check      |\n| `/health/status`  | Detailed service health |\n| `/health/metrics` | Health metrics (JSON)   |\n| `/metrics`        | Prometheus metrics      |\n| `/dashboard`      | Real-time web dashboard |\n\n### Quick Health Check\n\n```bash\n# Basic status\ncurl http://localhost:80/health\n\n# Detailed metrics\ncurl http://localhost:80/health/metrics | jq\n```\n\n## 🛠️ Troubleshooting\n\n### 🔍 DNS Resolution Issues\n\n```bash\n# Check if DNS server is running\nnetstat -tulnp | grep :5353\n\n# Manual DNS testing (find the actual DNS port in logs)\ndig @127.0.0.1 -p 5353 service.namespace.svc.cluster.local\n\n# Test virtual interface DNS (if enabled)\nexport KTUN_USE_VIRTUAL=true\nLOG_LEVEL=debug ./kube-tunnel\n\n# Debug DNS resolution\nexport KTUN_DNS_IP=127.0.0.1\nLOG_LEVEL=debug ./kube-tunnel 2\u003e\u00261 | grep -i dns\n```\n\n### ❌ Service Not Found\n\n```bash\n# Verify service exists\nkubectl get svc -n \u003cnamespace\u003e\n\n# Check permissions\nkubectl auth can-i get services\nkubectl auth can-i create pods/portforward\n\n# Enable debug logging\nLOG_LEVEL=debug ./kube-tunnel\n```\n\n### � Network \u0026 Virtual Interface Issues\n\n```bash\n# Check IP allocation\nLOG_LEVEL=debug ./kube-tunnel 2\u003e\u00261 | grep \"local IP\"\n\n# Test IP availability\nfor i in {2..10}; do\n  ping -c1 -W1 127.0.0.$i 2\u003e/dev/null \u0026\u0026 \\\n  echo \"127.0.0.$i in use\" || echo \"127.0.0.$i available\"\ndone\n\n# Force specific virtual interface IP\nexport KTUN_VIRTUAL_IP=127.0.0.50\nexport KTUN_USE_VIRTUAL=true\n./kube-tunnel\n\n# Configure custom IP ranges\nexport KTUN_IP_RANGES=\"127.0.0.0/24,10.0.0.0/24\"\n./kube-tunnel\n```\n\n## ✨ Architecture Highlights\n\n### 🔧 Dual Virtual Interface Design\n\nkube-tunnel now features an intelligent **dual virtual interface architecture** that eliminates port conflicts and optimizes performance:\n\n```bash\n# Automatic Interface Creation (when KTUN_USE_VIRTUAL=true)\nkube-dns0    (10.8.0.1)  # DNS resolution for *.svc.cluster.local  \nkube-proxy0  (10.8.0.2)  # kubectl port-forward sessions\n```\n\n**Key Benefits:**\n\n- ✅ **Zero Port Conflicts** — DNS and port-forwarding use dedicated interfaces\n- ✅ **Automatic Separation** — No manual configuration required  \n- ✅ **Intelligent Routing** — Universal port handler efficiently redirects traffic\n- ✅ **Clear Semantics** — Interface names reflect their specific purposes\n- ✅ **Enhanced Performance** — Optimized for both DNS resolution and port forwarding\n\n### 🚀 What's New\n\n- **Smart Interface Naming**: `kube-dns0` and `kube-proxy0` instead of generic dummy names\n- **Always-On Dual Mode**: When virtual interfaces are enabled, both are automatically created\n- **Conflict-Free Operation**: Separate IP spaces eliminate universal port handler conflicts\n- **Simplified Configuration**: No need for separate flags or complex setup\n\n## 🤝 Contributing\n\nWe welcome contributions! Here's how to get started:\n\n1. **Fork** the repository\n1. **Create** a feature branch (`git checkout -b feature/awesome-feature`)\n1. **Commit** your changes (`git commit -m 'Add awesome feature'`)\n1. **Push** to the branch (`git push origin feature/awesome-feature`)\n1. **Open** a Pull Request\n\n### Development Setup\n\n```bash\n# Clone and setup\ngit clone https://github.com/snakeice/kube-tunnel\ncd kube-tunnel\ngo mod download\ngo build -o kube-tunnel ./cmd\n\n# Run tests\ngo test ./...\n\n# Run performance tests\n./scripts/perf-test.sh --dry-run  # Validate without running\n./scripts/perf-test.sh            # Full performance test suite\n\n# Test virtual interface functionality\nsudo ./scripts/test-virtual-interface.sh quick         # Quick virtual interface tests\nsudo ./scripts/test-virtual-interface.sh comprehensive # Comprehensive tests\n\n# Health monitoring demo\n./scripts/health-demo.sh --help                        # Show options\n./scripts/health-demo.sh --virtual-interface          # Test with virtual interface\n```\n\n### Testing Scripts\n\nkube-tunnel includes comprehensive testing scripts:\n\n- **`scripts/perf-test.sh`** — Performance testing with virtual interface support\n- **`scripts/health-demo.sh`** — Health monitoring demonstration\n- **`scripts/test-virtual-interface.sh`** — Virtual interface functionality tests\n\n#### Virtual Interface Testing\n\n```bash\n# Test virtual interface support\nexport USE_VIRTUAL_INTERFACE=true\nexport VIRTUAL_INTERFACE_IP=127.0.0.10\nexport VIRTUAL_INTERFACE_NAME=kube-dummy0\n\n# Run performance tests with virtual interface\n./scripts/perf-test.sh\n\n# Test health monitoring with virtual interface\n./scripts/health-demo.sh --virtual-interface --vi-ip 127.0.0.10\n```\n\n## 📄 License\n\nThis project is licensed under the **MIT License** - see the [`LICENSE`](LICENSE) file for details.\n\n---\n\n**⭐ Star this repo if kube-tunnel helps you!**\n\nMade with ❤️ for the Kubernetes community\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsnakeice%2Fkube-tunnel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsnakeice%2Fkube-tunnel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsnakeice%2Fkube-tunnel/lists"}