STUNner Documentation

STUNner is a Kubernetes-native media gateway designed to handle WebRTC UDP/RTP traffic. It solves the challenge of ingesting streaming workloads into Kubernetes by exposing a single public STUN/TURN server port. This allows you to manage media traffic in a controlled, standards-compliant way without needing to open thousands of UDP ports or use privileged pods with hostNetwork/hostPort configurations.

Key capabilities include:

• Kubernetes Gateway API Integration: Configure STUNner using standard YAML manifests, similar to how you manage HTTP workloads with service meshes like Istio.
• Secure Perimeter: All media is received through a single ingress port, reducing the attack surface.
• Self-contained NAT Traversal: Deploy STUNner within your cluster to act as your own STUN/TURN service, removing reliance on external providers.
• Scalability: Scale your media plane using standard Kubernetes mechanisms like kubectl scale or the Horizontal Pod Autoscaler (HPA).
• High Performance: Built with Go and pion/webrtc. The enterprise tier includes a Linux/eBPF TURN acceleration engine capable of up to 10 Gbps per CPU core.

STUNner is a Kubernetes-native media gateway designed to solve the complexities of deploying WebRTC infrastructure in the cloud. It provides a standards-compliant STUN/TURN gateway that allows WebRTC clients to access virtualized media infrastructure running in Kubernetes pods.

STUNner integrates with the Kubernetes Gateway API, allowing configuration via standard Kubernetes YAML manifests. It solves common WebRTC-on-Kubernetes issues such as UDP/RTP networking complexities, port range management, and the dependency on external, expensive, or high-latency third-party STUN/TURN services.

STUNner can be deployed in two primary operational models:

1. Headless Model: Acts as a standalone STUN/TURN server used by WebRTC clients and media servers for scalable NAT traversal.
2. Media-plane Model: Acts as a gateway for ingesting WebRTC media traffic into the Kubernetes cluster by exposing a public-facing STUN/TURN server that clients connect to.

STUNner is available in three tiers:

• STUNner free tier: For simple WebRTC applications.
• STUNner member tier: Includes premium features for small to medium scale operations.
• STUNner enterprise tier: Optimized for large-scale deployments.

STUNner supports graceful shutdown to prevent client disconnects when pods are terminated during a scale-down event. When a pod is marked for termination, stunnerd will:

1. Refuse to terminate as long as there are active TURN allocations.
2. Automatically remove itself only once all allocations are deleted or timed out.
3. Stop receiving new TURN allocation requests from the Kubernetes load balancer.

Configuration and Limitations:

• Grace Period: By default, a stunnerd pod will remain alive for at most 1 hour after being marked for deletion, even if allocations are still active. You can adjust this by setting terminationGracePeriod in the Dataplane template.
• Resource Defaults: By default, pods are provisioned with at most 2 CPU cores and 16 listener threads. These can be customized in the Dataplane template.
• Stale Allocations: If a client closes a connection without notifying the server (e.g., spontaneous UDP closure), the allocation may persist until the TURN refresh lifetime expires (default is 10 minutes).
• Forced Removal: If a pod refuses to stop after a kubectl delete due to lingering allocations, you can force it using: kubectl delete pod --grace-period=0 --force stunner-XXX

TCPRoute is the TCP counterpart to UDPRoute. It uses the same spec and backend semantics, but the relay leg towards the backend is a TCP connection.

Important Constraints:

• No Protocol Conversion: The protocol of the relay leg is fixed by the client's TURN allocation. A TCP backend is only reachable via an RFC 6062 TCP allocation.
• Browser Compatibility: Browsers do not implement RFC 6062, so TCP backends cannot be reached from a browser's relay candidates.
• Licensing: Rendering a TCPRoute into a dataplane cluster is a premium feature. Without a license, the operator accepts the resource and maintains status, but no cluster is rendered.

STUNner-native TCPRoute resources mask official Gateway API TCPRoute resources of the same name.

apiVersion: stunner.l7mp.io/v1
kind: TCPRoute
metadata:
  name: media-plane-route
  namespace: stunner
spec:
  parentRefs:
    - name: tcp-gateway
  rules:
    - backendRefs:
        - name: media-server-pool
          namespace: media-plane

The stunnerd daemon is the core component of the data plane. It is managed automatically by the Gateway operator:

• Automatic Provisioning: When you create a new Gateway, the operator automatically spawns a stunnerd Deployment with the same name and namespace.
• Scaling: You can scale the stunnerd Deployment to any number of pods. Kubernetes will distribute new client connections evenly across the scaled-out fleet.
• Configuration Reconciliation: When a Gateway or UDPRoute is modified, the operator renders a new configuration and downloads it to the stunnerd pods. The pods then reconcile their internal state (listeners and clusters) to match the new spec.
• Internal Components: Each stunnerd instance implements:
  • TURN listeners: One per Gateway listener to terminate client sessions.
  • Clusters: One per UDPRoute to forward packets to backend services.

When using STUNner as an ingress gateway (Media-plane model), you must choose an ICE mode to determine how peers create candidates:

Asymmetric ICE mode

Recommended for the Media-plane deployment model. In this mode, only one peer (typically the client) uses STUNner. The other peer (the server) uses no STUN/TURN servers at all.

• How it works: The client creates a TURN relay candidate via STUNner (using a private pod IP). The server generates host candidates (using its own private pod IP). Since Kubernetes pods can communicate directly on the private network, the connection succeeds.
• Configuration Rules:
  • Client: Set STUNner as the only TURN server; configure no STUN servers. It is highly recommended to set iceTransportPolicy to relay to prevent clients from circumventing STUNner via public STUN servers.
  • Server: Do not configure any STUN or TURN servers.

Symmetric ICE mode

Both the client and the server obtain ICE relay candidates from STUNner. This mode is the simplest for the Headless model but adds more overhead in the Media-plane model because STUNner must perform encapsulation/decapsulation for both sides.

• How it works: The connection occurs directly via STUNner acting as a relay for both peers.
• Configuration Rules:
  • Both Client & Server: Set STUNner as the only TURN server; configure no STUN servers.
  • Both Client & Server: You must set iceTransportPolicy to relay. If not set, the connection may fall back to asymmetric mode due to ICE priority rules.
  • Optimization: On the server side, use the internal IP address and port of the STUNner Kubernetes service (ClusterIP) to avoid unnecessary roundtrips (hairpinning) through the external LoadBalancer IP.