{"id":41990210,"url":"https://github.com/kroderdev/kube-edge-router","last_synced_at":"2026-01-29T03:01:03.407Z","repository":{"id":334137035,"uuid":"1140204317","full_name":"KroderDev/kube-edge-router","owner":"KroderDev","description":"Kubernetes Operator that exposes LoadBalancer services through remote Edge VPS nodes with public IPv4 addresses via WireGuard tunnels and nftables DNAT rules.","archived":false,"fork":false,"pushed_at":"2026-01-26T07:34:15.000Z","size":85,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-26T14:14:56.632Z","etag":null,"topics":["edge-computing","golang","kubernetes","loadbalancer","nftables","operator","wireguard"],"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/KroderDev.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-23T00:50:48.000Z","updated_at":"2026-01-26T07:34:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/KroderDev/kube-edge-router","commit_stats":null,"previous_names":["kroderdev/kube-edge-router"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/KroderDev/kube-edge-router","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KroderDev%2Fkube-edge-router","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KroderDev%2Fkube-edge-router/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KroderDev%2Fkube-edge-router/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KroderDev%2Fkube-edge-router/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KroderDev","download_url":"https://codeload.github.com/KroderDev/kube-edge-router/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KroderDev%2Fkube-edge-router/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28794530,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-26T21:49:50.245Z","status":"ssl_error","status_checked_at":"2026-01-26T21:48:29.455Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["edge-computing","golang","kubernetes","loadbalancer","nftables","operator","wireguard"],"created_at":"2026-01-26T00:31:56.428Z","updated_at":"2026-01-28T02:02:40.579Z","avatar_url":"https://github.com/KroderDev.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Kube Edge Router\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Go Version](https://img.shields.io/badge/Go-1.25-00ADD8.svg)](https://go.dev/)\n[![Downloads](https://img.shields.io/github/downloads/KroderDev/kube-edge-router/total.svg)](https://github.com/KroderDev/kube-edge-router/releases)\n\nA Kubernetes Operator that exposes LoadBalancer services through remote Edge VPS nodes with public IPv4 addresses.\n\n## Overview\n\n**kube-edge-router** bridges internal Kubernetes services to the public internet through edge nodes connected via WireGuard tunnels. It automates the management of `nftables` forwarding rules on edge VPS nodes.\n\n```mermaid\nflowchart TB\n    subgraph Internet\n        User([User])\n    end\n    \n    subgraph Edge[\"Edge VPS (edge-us-east-01)\"]\n        PIP[Public IP\u003cbr/\u003e203.0.113.10]\n        NFT[nftables\u003cbr/\u003eDNAT]\n        WG1[WireGuard\u003cbr/\u003ewg0]\n    end\n    \n    subgraph Core[\"Core Cluster\"]\n        Controller[kube-edge-router\u003cbr/\u003eController]\n        EN[EdgeNode CRD]\n        SVC[Service\u003cbr/\u003etype: LoadBalancer]\n        MLB[MetalLB\u003cbr/\u003e172.16.10.200]\n    end\n    \n    User --\u003e|:25565| PIP\n    PIP --\u003e NFT\n    NFT --\u003e WG1\n    WG1 --\u003e|WireGuard Tunnel| MLB\n    MLB --\u003e SVC\n    \n    Controller --\u003e|SSH| NFT\n    Controller --\u003e EN\n    Controller --\u003e|Watch| SVC\n```\n\n## Reconciliation Flow\n\n```mermaid\nsequenceDiagram\n    participant S as Service\n    participant C as Controller\n    participant EN as EdgeNode\n    participant E as Edge VPS\n    \n    S-\u003e\u003eC: Create Service (LoadBalancer)\n    C-\u003e\u003eEN: Find available Public IP\n    EN--\u003e\u003eC: 203.0.113.10 available\n    C-\u003e\u003eE: SSH: Apply nftables DNAT\n    E--\u003e\u003eC: Rules applied\n    C-\u003e\u003eEN: Mark IP as allocated\n    C-\u003e\u003eS: Patch status.loadBalancer.ingress\n```\n\n## Features\n\n- 🌐 **Multi-Edge Support**: Manage multiple edge VPS nodes with different public IP pools\n- 🔒 **Zero-Trust Edge**: Control plane pushes config; edge nodes are stateless gateways\n- 🔄 **Automatic Reconciliation**: Watches LoadBalancer services and syncs rules\n- 📦 **CRD-Based**: `EdgeNode` custom resource for declarative edge management\n\n## Prerequisites\n\nThe Edge Node VPS must be provisioned with the following:\n*   **OS**: Linux (Debian 12+ recommended)\n*   **Networking**: `nftables` (enabled), `WireGuard`\n*   **Firewall**: UFW **MUST BE DISABLED**. The controller manages `nftables` directly.\n*   **Kernel**: Forwarding enabled (`net.ipv4.ip_forward=1`)\n*   **SSH**: Key-based access for the controller.\n\n## Installation\n\n```bash\n# Install CRDs\nkubectl apply -f config/crd/bases/\n\n# Deploy controller\nkubectl apply -k config/default/\n```\n\n## Usage\n\n### 1. Create an EdgeNode\n\n```yaml\napiVersion: networking.edge-router.io/v1alpha1\nkind: EdgeNode\nmetadata:\n  name: edge-us-east-01\nspec:\n  managementIP: \"10.10.0.2\"      # WireGuard IP\n  sshSecretRef: \"edge-ssh-key\"    # Secret with SSH private key\n  publicIPs:\n    - address: \"203.0.113.10\"\n      interface: \"enp1s0\"\n```\n\n### 2. Annotate a Service\n\n```yaml\napiVersion: v1\nkind: Service\nmetadata:\n  name: my-app\n  annotations:\n    edge-router.io/edge-routed: \"true\"\nspec:\n  type: LoadBalancer\n  ports:\n    - port: 8080\n```\n\n### 3. Annotate a Namespace (Recommended for vClusters)\n\nTo expose ALL LoadBalancer services within a namespace automatically:\n\n```yaml\napiVersion: v1\nkind: Namespace\nmetadata:\n  name: tenant-a\n  annotations:\n    edge-router.io/edge-routed: \"true\"\n```\n\nThe controller will:\n1. Detect the internal VIP assigned by MetalLB\n2. Allocate an available public IP from an EdgeNode\n3. SSH to the edge and apply nftables rules\n4. Update the Service status with the public IP\n\n## Configuration\n\n| Environment Variable | Description | Default |\n|---------------------|-------------|---------|\n| `SSH_TIMEOUT` | SSH connection timeout | `10s` |\n| `RECONCILE_INTERVAL` | Forced reconcile interval | `5m` |\n\n## Development\n\n```bash\n# Prerequisites\ngo 1.25+\nkubebuilder 3.x\n\n# Run locally\nmake run\n\n# Run tests\nmake test\n\n# Build image\nmake docker-build IMG=your-registry/kube-edge-router:tag\n```\n\n## Build Process\n\n### Build-Time Versioning\nThe `Makefile` automatically injects the git version into the binary:\n*   **Release**: Uses the git tag (e.g., `v0.3.2`).\n*   **Development**: Uses the tag + commit hash + dirty status (e.g., `v0.3.2-4-g9c5a1b-dirty`).\n\nTo override the version manually:\n```bash\nmake build VERSION=custom-v1.0.0\n```\n\n## Architecture\n\nThis project follows Hexagonal Architecture. See [AGENTS.md](AGENTS.md) for details.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkroderdev%2Fkube-edge-router","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkroderdev%2Fkube-edge-router","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkroderdev%2Fkube-edge-router/lists"}