Holepunch

Configure UPnP routers to port-forward to Kubernetes services on your local network.

Use Case

If you run a Kubernetes cluster behind a NAT router (e.g., on a home network) you might use a service such as MetalLB to provide local-network IP addresses to your services. But 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.

This 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. Holepunch automates this process, and configures your router using UPnP to whatever the local network IP is.

Usage

Deploy Holepunch into your cluster. A container image is available at ghcr.io/jameslaverack/holepunch. You can use the provided Makefile to produce the YAML and deploy to your current kube config.

For example, to deploy version v0.1.0:

export IMG='ghcr.io/jameslaverack/holepunch:v0.1.0'
make deploy

Once Holepunch is deployed, annotate services of type LoadBalancer with holepunch/punch-external: "true". Holepunch will then configure your router over UPnP to forward the service's ports to the declared "external IP" of the service.

Using Different External Ports

If you want to expose a different port on your router than the Kubernetes service port, you can map this with an annotation. Holepunch looks for annotations with the prefix holepunch.port/, followed by the service's port number. The value of this annotation is the desired external port. Note that annotations must have string YAML values, so the external port number must be templated as a string.

For example, if a service exposes port 80, the annotation holepunch.port/80: "3000" could be used. This would cause Holepunch to make a UPnP mapping from an external port 3000 to port 80 on the local network.

Limitations

Only LoadBalancer services are supported.
Some routers won't allow some ports (such as 80 and 443) to be configured over UPnP.
Holepunch can't handle more than one router on your network.
To work inside your Kubernetes cluster, the holepunch Pod must bind to the host network and expose some UDP ports. 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.

Service Failed to find router

Hi,

I have a small single node home Server running k3s with kube-vip behind a FritzBox.
I followed the Readme and deployed holepunch to my cluster with make deploy. After annotating a LoadBalancer service with holepunch/punch-external: "true"., I found this in the holepunch-controller-manager log:

2021-12-08T01:09:03.592Z INFO controller-runtime.metrics metrics server is starting to listen {"addr": "127.0.0.1:8080"}
2021-12-08T01:09:03.592Z INFO setup starting manager
I1208 01:09:03.790188 1 leaderelection.go:242] attempting to acquire leader lease holepunch-system/81773bb2.holepunch.jameslaverack.com...
2021-12-08T01:09:03.790Z INFO controller-runtime.manager starting metrics server {"path": "/metrics"}
I1208 01:09:03.827295 1 leaderelection.go:252] successfully acquired lease holepunch-system/81773bb2.holepunch.jameslaverack.com
2021-12-08T01:09:03.889Z DEBUG controller-runtime.manager.events Normal {"object": {"kind":"ConfigMap","namespace":"holepunch-system","name":"81773bb2.holepunch.jameslaverack.com","uid":"28a6b722-bda4-4687-ab21-dc46f96a4dea","apiVersion":"v1","resourceVersion":"3279675"}, "reason": "LeaderElection", "message": "Debian-10-Cloudinit_c6fb0ec5-e81a-44f5-b6c3-73267caf9c4b became leader"}
2021-12-08T01:09:03.989Z INFO controller-runtime.controller Starting EventSource {"controller": "service", "source": "kind source: /, Kind="}
2021-12-08T01:09:04.191Z INFO controller-runtime.controller Starting Controller {"controller": "service"}
2021-12-08T01:09:04.191Z INFO controller-runtime.controller Starting workers {"controller": "service", "worker count": 1}
2021-12-08T01:09:04.191Z DEBUG controller-runtime.controller Successfully Reconciled {"controller": "service", "request": "default/kubernetes"}
2021-12-08T01:09:04.191Z DEBUG controller-runtime.controller Successfully Reconciled {"controller": "service", "request": "teamspeak/teamspeak-tcp"}
2021-12-08T01:09:06.292Z ERROR controllers.Service Failed to find router to configure {"service": "traefik/traefik", "error": "No services found"}
github.com/go-logr/zapr.(*zapLogger).Error
/go/pkg/mod/github.com/go-logr/[email protected]/zapr.go:128
github.com/JamesLaverack/holepunch/controllers.(*ServiceReconciler).Reconcile
/workspace/controllers/service_controller.go:70
sigs.k8s.io/controller-runtime/pkg/internal/controller.(*Controller).reconcileHandler
/go/pkg/mod/sigs.k8s.io/[email protected]/pkg/internal/controller/controller.go:256
sigs.k8s.io/controller-runtime/pkg/internal/controller.(*Controller).processNextWorkItem
/go/pkg/mod/sigs.k8s.io/[email protected]/pkg/internal/controller/controller.go:232
sigs.k8s.io/controller-runtime/pkg/internal/controller.(*Controller).worker
/go/pkg/mod/sigs.k8s.io/[email protected]/pkg/internal/controller/controller.go:211
k8s.io/apimachinery/pkg/util/wait.JitterUntil.func1
/go/pkg/mod/k8s.io/[email protected]/pkg/util/wait/wait.go:152
k8s.io/apimachinery/pkg/util/wait.JitterUntil
/go/pkg/mod/k8s.io/[email protected]/pkg/util/wait/wait.go:153
k8s.io/apimachinery/pkg/util/wait.Until
/go/pkg/mod/k8s.io/[email protected]/pkg/util/wait/wait.go:88
2021-12-08T01:09:06.292Z ERROR controller-runtime.controller Reconciler error {"controller": "service", "request": "traefik/traefik", "error": "No services found"}
github.com/go-logr/zapr.(*zapLogger).Error
/go/pkg/mod/github.com/go-logr/[email protected]/zapr.go:128
sigs.k8s.io/controller-runtime/pkg/internal/controller.(*Controller).reconcileHandler
/go/pkg/mod/sigs.k8s.io/[email protected]/pkg/internal/controller/controller.go:258
sigs.k8s.io/controller-runtime/pkg/internal/controller.(*Controller).processNextWorkItem
/go/pkg/mod/sigs.k8s.io/[email protected]/pkg/internal/controller/controller.go:232
sigs.k8s.io/controller-runtime/pkg/internal/controller.(*Controller).worker
/go/pkg/mod/sigs.k8s.io/[email protected]/pkg/internal/controller/controller.go:211

Any ideas what could be happening here? All services should be able to reach each other and services in network host mode can also reach the router.

jameslaverack / holepunch Goto Github PK

holepunch's Introduction

Holepunch

Use Case

Usage

Using Different External Ports

Limitations

holepunch's People

Contributors

Stargazers

Watchers

Forkers

holepunch's Issues

Recommend Projects

Recommend Topics

Recommend Org