{"id":18843864,"url":"https://github.com/jameslaverack/holepunch","last_synced_at":"2026-01-14T19:14:35.612Z","repository":{"id":42447657,"uuid":"343009024","full_name":"JamesLaverack/holepunch","owner":"JamesLaverack","description":"Configure UPnP routers to port-forward to Kubernetes services on your local network","archived":true,"fork":false,"pushed_at":"2022-08-13T06:05:57.000Z","size":56,"stargazers_count":20,"open_issues_count":6,"forks_count":5,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-06T03:51:21.522Z","etag":null,"topics":["kubernetes","kubernetes-networking","upnp"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JamesLaverack.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}},"created_at":"2021-02-28T03:07:08.000Z","updated_at":"2024-11-03T01:19:37.000Z","dependencies_parsed_at":"2022-08-28T16:10:49.249Z","dependency_job_id":null,"html_url":"https://github.com/JamesLaverack/holepunch","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JamesLaverack%2Fholepunch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JamesLaverack%2Fholepunch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JamesLaverack%2Fholepunch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JamesLaverack%2Fholepunch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JamesLaverack","download_url":"https://codeload.github.com/JamesLaverack/holepunch/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248839570,"owners_count":21169831,"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","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":["kubernetes","kubernetes-networking","upnp"],"created_at":"2024-11-08T02:59:07.381Z","updated_at":"2026-01-14T19:14:35.566Z","avatar_url":"https://github.com/JamesLaverack.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Holepunch\n\nConfigure UPnP routers to port-forward to Kubernetes services on your local network.\n\n## Use Case\n\nIf you run a Kubernetes cluster behind a NAT router (e.g., on a home network) you might use a service such as [MetalLB](https://metallb.universe.tf/) to provide local-network IP addresses to your services.\nBut you still need to configure your router's \"port forward\" feature to forward traffic from the open internet (assuming you either have a static IP or dynamic DNS of some kind) to that local service IP.\n\nThis typically requires you to cordinate IP addresses, set `spec.loadBalancerIP` and hope that no other service used it first, and then configure your router manually.\nHolepunch automates this process, and configures your router using UPnP to whatever the local network IP is.\n\n## Usage\n\nDeploy Holepunch into your cluster.\nA container image is available at `ghcr.io/jameslaverack/holepunch`.\nYou can use the provided Makefile to produce the YAML and deploy to your current kube config.\n\nFor example, to deploy version `v0.1.0`:\n```bash\nexport IMG='ghcr.io/jameslaverack/holepunch:v0.1.0'\nmake deploy\n```\n\nOnce Holepunch is deployed, annotate services of type `LoadBalancer` with `holepunch/punch-external: \"true\"`.\nHolepunch will then configure your router over UPnP to forward the service's ports to the declared \"external IP\" of the service.\n\n### Using Different External Ports\n\nIf you want to expose a different port on your router than the Kubernetes service port, you can map this with an annotation.\nHolepunch looks for annotations with the prefix `holepunch.port/`, followed by the service's port number.\nThe value of this annotation is the desired external port.\nNote that annotations must have string YAML values, so the external port number must be templated as a string.\n\nFor example, if a service exposes port 80, the annotation `holepunch.port/80: \"3000\"` could be used.\nThis would cause Holepunch to make a UPnP mapping from an external port 3000 to port 80 on the local network.\n\n## Limitations\n\n- Only `LoadBalancer` services are supported.\n- Some routers won't allow some ports (such as 80 and 443) to be configured over UPnP.\n- Holepunch can't handle more than one router on your network.\n- To work inside your Kubernetes cluster, the holepunch Pod must bind to the host network and expose some UDP ports.\n  This means that no more than one holepunch pod can run at once, and no other UPnP services can work at the same time on the same cluster.\n  \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjameslaverack%2Fholepunch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjameslaverack%2Fholepunch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjameslaverack%2Fholepunch/lists"}