Note: This page documents the latest development version of STUNner. See the documentation for the stable version here.
Ever wondered how to deploy your real-time communications infrastructure into the cloud? Frightened away by the complexities of Kubernetes container networking, and the surprising ways in which it may interact with your UDP/RTP media? Indeed, Kubernetes was built for HTTP/TCP, while WebRTC and VoIP media is UDP/RTP that simply does not fit into the cloud-native model. The usual answer is host networking and thousands of open UDP ports, just to get a per-pod public address for UDP/RTP endpoints.
STUNner is a media gateway that makes real-time media just another Kubernetes workload. It exposes only a single external port (two for VoIP) to ingest all real-time media into the cluster in a standards-compliant way. This allows STUNner to relay your media service running in ordinary, unprivileged Kubernetes pods, removing all operational friction that hinders Kubernetes real-time services today.
STUNner speaks all the media protocols of the real-time communications world:
- WebRTC: a STUN/TURN gateway for browsers and WebRTC clients to reach your media servers (LiveKit, Janus, Jitsi, mediasoup, Elixir WebRTC, and the like), with full browser compatibility and no change to your existing WebRTC codebase.
- SIP and RTP (experimental): a SIP and RTP gateway for SIP trunks, so carriers can deliver phone calls to SIP servers like LiveKit SIP running in the cluster, with no host networking and no public RTP port range.
STUNner implements the Kubernetes Gateway API, so you configure it with the same YAML manifests as the rest of your workload.
Real-time media lacks a virtualization story: there is no easy way to deploy a WebRTC media server or a SIP gateway into Kubernetes and benefit from the resiliency, scalability, and high availability features we have come to expect from modern network services. WebRTC deployments end up relying on public STUN servers and hosted TURN services to connect clients behind a NAT, and SIP deployments end up on dedicated hosts with public addresses and wide exposed RTP port ranges.
The main goal of STUNner is to allow anyone to deploy their own real-time media infrastructure into Kubernetes, without relying on any external service other than the cloud provider's standard hosted Kubernetes offering. STUNner can act as a standalone STUN/TURN server that WebRTC clients and media servers use for NAT traversal (headless model), or as a gateway that ingests WebRTC media into the cluster through a public STUN/TURN server (media-plane model), or as a gateway that connects SIP trunks to SIP servers deployed into a Kubernetes cluster (SIP model, experimental). Your application servers, media servers and SIP servers then run in ordinary Kubernetes pods, managed, scaled, monitored and troubleshooted in exactly the same way as any other Kubernetes workload.
Don't worry about the performance implications of processing all your media through a gateway: STUNner is fast, it is co-located with your media servers so you don't pay the round-trip time to a far-away relay, and it scales like any other Kubernetes service.
STUNner is open source: the dataplane, the gateway operator, the
authentication service, the Helm chart and the tools are all public on GitHub. The official STUNner
images and the stunner/stunner Helm chart are built by l7mp.io from the same
code, plus a few premium additions. Without a customer key you get the free tier: unlimited
TURN Gateways and connections, or an SIP/RTP Gateway with at most 5 parallel calls. The member
tier, aimed at small and medium-scale operations, unlocks a number of premium features and higher
call limits, while the fully featured enterprise tier, optimized for large-scale deployments,
add unlimited calls and unlocks STUNner's industry-leading Linux/eBPF TURN acceleration
engine. See here for
up-to-date info on how to purchase a license.
Kubernetes has been designed and optimized for the typical HTTP/TCP Web workload, which makes streaming workloads, and especially UDP/RTP media, feel like a foreign citizen. STUNner aims to change this, by a single public gateway port for ingesting all media traffic into a Kubernetes cluster in a controlled and standards-compliant way. An additional external port let's STUNner ingest SIP signaling traffic as well in a similar way, opening the door to deploy SIP/RTP services into Kubernetes.
-
Seamless integration with Kubernetes. STUNner can be deployed into any Kubernetes cluster, even into restricted ones like GKE Autopilot, using a single command. Manage your HTTP/HTTPS application servers with your favorite service mesh, and STUNner takes care of all UDP/RTP media, WebRTC or SIP. STUNner implements the Kubernetes Gateway API so you configure it in exactly the same way as the rest of your workload through easy-to-use YAML manifests.
-
Secure perimeter defense. No need to open thousands of UDP/TCP ports on your media servers; with STUNner all media is received through a single gateway port. Get rid of the Kubernetes security monstrosities like privileged pods and
hostNetwork/hostPortservices typically recommended as a prerequisite to containerizing a WebRTC media plane or a SIP gateway: with STUNner your media servers run in ordinary unprivileged Kubernetes pods behind a single gateway Service. -
No reliance on external services for NAT traversal. Can't afford a hosted TURN service for client-side NAT traversal? STUNner runs in the same cluster as the rest of your WebRTC infrastructure, and any WebRTC client can connect to it directly without the use of any external STUN/TURN service whatsoever.
-
SIP trunks into the cluster (experimental). Connect a carrier's SIP trunk to SIP servers running in ordinary pods and STUNner does the rest: it proxies SIP signaling traffic and relays RTP media into the cluster via a single external address. See the SIP gateway guide for details.
-
Scale your media infrastructure. Tired of manually provisioning your media servers? STUNner lets you deploy the entire media infrastructure into ordinary Kubernetes pods, thus scaling the media plane is as easy as issuing a
kubectl scalecommand. Better yet, you can use the built in Kubernetes autoscalers to automatically resize your workload based on demand. -
Minimal client-side configuration. STUNner comes with a built-in authentication service that can be used to generate time-windowed per-user TURN credentials through a standards compliant HTTP REST API. Just set the generated ICE configuration in the
PeerConnectionJavaScript API and your clients will readily start using your Kubernetes-based WebRTC service via STUNner. -
Carrier-grade performance. Written in pure Go using the battle-tested pion/webrtc framework, even STUNner's open-source tier is already extremely fast and scalable. But with STUNner's industry-leading Linux/eBPF TURN acceleration engine enabled (available in the enterprise tier), you can get up to 10 Gbps TURN/UDP performance per CPU core(!) at microsecond-scale latency.
With a minimal understanding of WebRTC or SIP and Kubernetes, deploying STUNner should take less than 5 minutes.
- Customize STUNner and deploy it into your Kubernetes cluster.
- Deploy a WebRTC media server or a SIP server in ordinary Kubernetes pod.
- Set STUNner as the ICE server in your WebRTC clients, or connect your SIP trunk through a STUNner Gateway.
- ...
- Profit!!
Note that the default installation does not contain an application server, a media server or a SIP server: STUNner is not a media service in itself, it is merely an enabler for you to deploy your own media infrastructure into Kubernetes.
The simplest way to deploy STUNner is through Helm. STUNner configuration parameters are available for customization as Helm Values.
helm repo add stunner https://l7mp.io/stunner
helm repo update
helm install stunner stunner/stunner --create-namespace --namespace=stunner-systemFind out more about the charts in the STUNner-helm repository.
STUNner comes with a wide selection of tutorials and demos that teach you how to deploy all kinds
of WebRTC and SIP services into Kubernetes. The first couple of tutorials present the basic concepts,
especially the use of the Kubernetes Gateway API to configure
STUNner and the tunnel mode of stunnerd to test it. Each subsequent demo
showcases a specific WebRTC application, from desktop streaming and video-conferencing to
cloud-gaming, and goes from a clean Kubernetes cluster to a working and usable publicly available
WebRTC service in 5-10 minutes using a purely declarative configuration.
- Deploying a UDP echo service behind STUNner: This introductory tutorial shows how to deploy a simple UDP echo service into Kubernetes and expose it via STUNner. If you read just one STUNner tutorial, this should be it.
- Calling a SIP echo service in Kubernetes: This tutorial connects a softphone through a STUNner SIP Gateway to a SIP echo service in the cluster, the smallest end-to-end test of the experimental SIP gateway.
- Opening a UDP tunnel via STUNner: This tutorial shows how to tunnel an external UDP client via STUNner to a standard iperf server deployed into Kubernetes. The demo can be used to benchmark your STUNner installation.
- Direct one to one video call via STUNner: This tutorial showcases STUNner acting as a TURN server for two WebRTC clients to establish connections between themselves, without the mediation of a media server.
- Video-conferencing with LiveKit: This tutorial helps you deploy the LiveKit WebRTC media server behind STUNner. The docs also show how to obtain a valid TLS certificate to secure your signaling connections, courtesy of the cert-manager project, nip.io and Let's Encrypt.
- Video-conferencing with Janus: This tutorial helps you deploy a fully fledged Janus video-conferencing service into Kubernetes behind STUNner. The docs also show how to obtain a valid TLS certificate to secure your signaling connections, using cert-manager, nip.io and Let's Encrypt.
- Video-conferencing with Elixir WebRTC: This tutorial helps you deploy a fully fledged Elixir WebRTC video-conferencing room called Nexus into Kubernetes behind STUNner. The docs also show how to obtain a valid TLS certificate to secure your signaling connections, using cert-manager, nip.io and Let's Encrypt.
- Video-conferencing with Jitsi: This tutorial helps you deploy a fully fledged Jitsi video-conferencing service into Kubernetes behind STUNner. The docs also show how to obtain a valid TLS certificate to secure your signaling connections, using cert-manager, nip.io and Let's Encrypt.
- Video-conferencing with mediasoup: This tutorial helps you deploy the mediasoup WebRTC media server behind STUNner. The docs also show how to obtain a valid TLS certificate to secure your signaling connections, courtesy of the cert-manager project, nip.io and Let's Encrypt.
- Cloud-gaming with Cloudretro: This tutorial lets you play Super Mario or Street Fighter in your browser, courtesy of the amazing CloudRetro project and, of course, STUNner. The demo also presents a simple multi-cluster setup, where clients can reach the game-servers in their geographical locality to minimize latency.
- Remote desktop access with Neko: This demo showcases STUNner providing an ingress gateway service to a remote desktop application. We use neko.io to run a browser in a secure container inside the Kubernetes cluster, and stream the desktop to clients via STUNner.
- One to one video call with Kurento: This tutorial shows how to use STUNner to connect WebRTC clients to a media server deployed into Kubernetes behind STUNner in the media-plane deployment model. All this happens without modifying the media server code in any way, just by adding 5-10 lines of straightforward JavaScript to configure clients to use STUNner as the TURN server.
- Magic mirror with Kurento: This tutorial has been adopted from the Kurento magic mirror demo, deploying a basic WebRTC loopback server behind STUNner with some media processing added. In particular, the application uses computer vision and augmented reality techniques to add a funny hat on top of faces.
The documentation of the stable release can be found here. The documentation for the latest development release can be found here.
STUNner development is coordinated in Discord, feel free to join.
Copyright 2021-2026 by its authors. Some rights reserved. See AUTHORS.
MIT License - see LICENSE for full text.