Topics

Language breakdown

Go 98.2%

Shell 1.5%

Makefile 0.2%

Dockerfile 0.1%

▸ Files click to expand

README

STUNner

Note: This page documents the latest development version of STUNner. See the documentation for the stable version here.

STUNner: A Kubernetes media gateway for WebRTC

Ever wondered how to deploy your WebRTC 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? Read through the endless stream of Stack Overflow questions asking how to scale WebRTC services with Kubernetes, just to get (mostly) insufficient answers? Want to safely connect users behind a NAT without relying on expensive third-party TURN services?

Worry no more! STUNner allows you to deploy any WebRTC service into Kubernetes, smoothly integrating it into the cloud-native ecosystem. STUNner exposes a standards-compliant STUN/TURN gateway for clients to access your virtualized WebRTC infrastructure running in Kubernetes, maintaining full browser compatibility and requiring minimal or no modification to your existing WebRTC codebase. STUNner supports the Kubernetes Gateway API so you can configure it in the familiar YAML-engineering style via Kubernetes manifests.

Description

WebRTC lacks a virtualization story: there is no easy way to deploy a WebRTC media service into Kubernetes to benefit from the resiliency, scalability, and high availability features we have come to expect from modern network services. Worse yet, the entire industry relies on a handful of public STUN servers and hosted TURN services to connect clients behind a NAT/firewall, which may create a useless dependency on externally operated services, introduce a performance bottleneck, raise security concerns, and come with a non-trivial price tag.

The main goal of STUNner is to allow anyone to deploy their own WebRTC 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 can use as a scalable NAT traversal facility (headless model), or it can act as a gateway for ingesting WebRTC media traffic into the Kubernetes cluster by exposing a public-facing STUN/TURN server that WebRTC clients can connect to (media-plane model). This makes it possible to deploy WebRTC application servers and media servers into ordinary Kubernetes pods, taking advantage of the full cloud native feature set to manage, scale, monitor and troubleshoot the WebRTC infrastructure like any other Kubernetes workload.

STUNner media-plane deployment architecture

Don't worry about the performance implications of processing all your media through a TURN server: STUNner is extremely fast, it is co-located with your media server pool so you don't pay the round-trip time to a far-away public STUN/TURN server, and it can be easily scaled up if needed just like any other "normal" Kubernetes service.

STUNner comes in multiple flavors. The open-source **STUNner free tier** will suit simple WebRTC applications. Certain advanced features are however available only in STUNner's paid premium editions. The STUNner member tier includes the premium features targeted for small and medium scale operations, while the fully featured **STUNner enterprise tier** is optimized for large-scale deployments. See here for up-to-date info on how to purchase a license.

Features

Kubernetes has been designed and optimized for the typical HTTP/TCP Web workload, which makes streaming workloads, and especially UDP/RTP based WebRTC media, feel like a foreign citizen. STUNner aims to change this state-of-the-art, by exposing a single public STUN/TURN server port for ingesting all media traffic into a Kubernetes cluster in a controlled and standards-compliant way.

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. 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 server for

potentially malicious access; with STUNner *all media is received through a single ingress port*. Get rid of the Kubernetes security monstrosities like privileged pods and hostNetwork/hostPort services typically recommended as a prerequisite to containerizing your WebRTC media plane: with STUNner your media servers will run in ordinary unprivileged Kubernetes pods exposed on single gateway service.

No reliance on external services for NAT traversal. Can't afford a hosted TURN

service for client-side NAT traversal? Can't get decent audio/video quality because the third-party TURN service poses a bottleneck? STUNner can be deployed into 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, apart from STUNner itself.

Scale your WebRTC infrastructure. Tired of manually provisioning your WebRTC media servers?

STUNner lets you deploy the entire WebRTC infrastructure into ordinary Kubernetes pods, thus scaling the media plane is as easy as issuing a kubectl scale command. Better yet, you can use the built in Kubernetes horizontal autoscaler 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 PeerConnection JavaScript 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.

The main use of STUNner is as a Kubernetes-native gateway service for ingesting and load-balancing clients' media connections across a pool of WebRTC media servers hosted in ordinary Kubernetes pods. STUNner however is also usable to deploy a scalable STUN server pool or as a public Kubernetes-based TURN service.

Getting Started

With a minimal understanding of WebRTC and Kubernetes, deploying STUNner should take less than 5 minutes, in five simple steps.

Customize STUNner and deploy it into your Kubernetes cluster.
Optionally deploy a WebRTC media server.
Set STUNner as the ICE server in your WebRTC clients.
...
Profit!!

Note that the default installation does not contain an application server and a media server: STUNner is not a WebRTC service in itself, it is merely an enabler for you to deploy your own WebRTC 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-system

Find out more about the charts in the STUNner-helm repository.

Usage

STUNner comes with a wide selection of tutorials and demos that teach you how to deploy all kinds of WebRTC 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 turncat utility 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.

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.