GatewayClass🔗

These resources set up a STUNner installation: the GatewayClass is the root of the configuration hierarchy, the GatewayConfig holds the settings shared by every Gateway of the class (most importantly the TURN authentication credentials), and the Dataplane is the template of the stunnerd pods.

  1. GatewayClass
  2. GatewayConfig
  3. Dataplane

GatewayClass🔗

The GatewayClass resource provides the root of a STUNner gateway configuration. GatewayClass resources are cluster-scoped, so they can be attached to from any namespace.

Below is a sample GatewayClass resource. Each GatewayClass specifies a controller that will manage the Gateway objects created under the class; this must be set to stunner.l7mp.io/gateway-operator for the STUNner gateway operator to pick up the GatewayClass. In addition, a GatewayClass can refer to further implementation-specific configuration via a parametersRef; in the case of STUNner this will always be a GatewayConfig object (see below).

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: stunner-gatewayclass
spec:
  controllerName: "stunner.l7mp.io/gateway-operator"
  parametersRef:
    group: "stunner.l7mp.io"
    kind: GatewayConfig
    name: stunner-gatewayconfig
    namespace: stunner
  description: "STUNner is a WebRTC ingress gateway for Kubernetes"

Below is a quick reference of the most important fields of the GatewayClass spec.

Field Type Description Required
controllerName string Reference to the controller that is managing the Gateways of this class. The value of this field MUST be specified as stunner.l7mp.io/gateway-operator. Yes
parametersRef object Reference to a GatewayConfig resource, identified by the name and namespace, for general STUNner configuration. The settings group: "stunner.l7mp.io" and kind: GatewayConfig are default and can be omitted, any other group or kind is an error. Yes
description string Description helps describe a GatewayClass with more details. No

GatewayConfig🔗

The GatewayConfig resource provides general configuration for STUNner, most importantly the STUN/TURN authentication credentials clients can use to connect to STUNner. GatewayClass resources attach a STUNner configuration to the hierarchy by specifying a particular GatewayConfig in the GatewayClass parametersRef. GatewayConfig resources are namespaced, and every hierarchy can contain at most one GatewayConfig. Failing to specify a GatewayConfig is an error because the authentication credentials cannot be learned otherwise.

The following example takes the STUNner authentication settings from the Secret called stunner-auth-secret in the stunner namespace, sets the authentication realm to stunner.l7mp.io, and sets the dataplane loglevel to all:DEBUG,turn:INFO (this will set all loggers to DEBUG level except the TURN protocol machinery's logger which is set to INFO).

apiVersion: stunner.l7mp.io/v1
kind: GatewayConfig
metadata:
  name: stunner-gatewayconfig
  namespace: stunner
spec:
  logLevel: "all:DEBUG,turn:INFO"
  realm: stunner.l7mp.io
  authRef:
    name: stunner-auth-secret
    namespace: stunner

Below is a reference of the most important fields of the GatewayConfig spec

Field Type Description Required
dataplane string The name of the Dataplane template to use for provisioning stunnerd pods. Default: default. No
logLevel string Logging level for the dataplane pods. Default: all:INFO. No
realm string The STUN/TURN authentication realm to be used for clients to authenticate with STUNner. The realm must consist of lower case alphanumeric characters or - and must start and end with an alphanumeric character. Default: stunner.l7mp.io. No
authRef reference Reference to a Secret (namespace and name) that defines the STUN/TURN authentication mechanism and the credentials. No
authType string Type of the STUN/TURN authentication mechanism. Valid only if authRef is not set. Default: static. No
userName string The username for static authentication. Valid only if authRef is not set. No
password string The password for static authentication. Valid only if authRef is not set. No
sharedSecret string The shared secret for ephemeral authentication. Valid only if authRef is not set. No
authLifetime int The lifetime of ephemeral authentication credentials in seconds. Not used by STUNner. No
loadBalancerServiceAnnotations map[string]string A list of annotations that will go into the LoadBalancer services created automatically by STUNner to obtain a public IP address. See more detail here. No
loadBalancerServiceLabels map[string]string A list of labels that will go into the LoadBalancer services created automatically by STUNner. See more detail here. No
userQuota int Limit the number of allocations per username (not supported in the free tier). Default is 0, which means no quota. No
stunMode bool Toggle STUN-only mode. In this mode STUNner responds only to STUN requests; any TURN allocation request is rejected. Default is false. No

At least a valid username/password pair must be supplied for static authentication, or a sharedSecret for the ephemeral mode, either via an external Secret or inline in the GatewayConfig. External authentication settings override inline settings. Missing both is an error.

Except the TURN authentication realm, all GatewayConfig resources are safe for modification. That is, the stunnerd daemon knows how to reconcile a change in the GatewayConfig without restarting listeners/TURN servers. Changing the realm, however, restarts the TURN servers that use the auth config, terminating all active client sessions.

Dataplane🔗

The Dataplane resource is used as a template for provisioning stunnerd dataplane pods that implement TURN media ingestion. This is useful to choose the stunnerd image origin and version, set custom command line arguments and environment variables, configure resource requests/limits, etc.

Below is the default Dataplane installed by STUNner.

apiVersion: stunner.l7mp.io/v1
kind: Dataplane
metadata:
  name: default
spec:
  command:
  - stunnerd
  args:
  - -w
  image: l7mp/stunnerd:latest
  resources:
    limits:
      cpu: 1000m
      memory: 512Mi
    requests:
      cpu: 250m
      memory: 128Mi
  terminationGracePeriodSeconds: 3600

The following fields can be set in the Dataplane spec to customize the provisioning of stunnerd pods.

Field Type Description Required
image string The container image. Yes
imagePullPolicy string Policy for if/when to pull the stunnerd image, either Always, Never, or IfNotPresent. Default: Always if the latest tag is specified on the image, IfNotPresent otherwise. No
imagePullSecrets list List of Secret references to use for pulling the stunnerd image. Each ref is a secret name, namespace is the same as that of the Gateway on behalf of which the dataplane is deployed. No
labels map Custom labels added to stunnerd pods. Mandatory labels override whatever is set here. Changing pod labels triggers full dataplane restart for the affected Gateways. No
annotations map Custom annotations added to stunnerd pods. Mandatory annotations override whatever is set here, which in turn override manually added annotations. Changes trigger full dataplane restart for the affected Gateways. No
command list Entrypoints for the dataplane container. No
args list Command line arguments for the dataplane container. No
envFrom list List of sources to populate environment variables for the dataplane container. Default: empty. No
env list List of environment variables for the dataplane container. Default: empty. No
replicas int Number of dataplane pods per Gateway to provision. Not enforced if the dataplane Deployment replica count is overwritten manually or by an autoscaler. Default: 1. No
resources object Compute resources per dataplane pod. Default: none. No
affinity object Scheduling constraints for the dataplane pods. Default: none. No
tolerations object Tolerations for the dataplane pods. Default: none. No
priorityClassName string The PriorityClass of the dataplane pods to avoid them being evicted under capacity pressure. The PriorityClass must exist. Default: none. No
securityContext object Pod-level security attributes for the dataplane pods. Default: none. No
containerSecurityContext object Container-level security attributes for the dataplane pods. Default: none. No
topologySpreadConstraints object Description of how the dataplane pods for a Gateway ought to spread across topology domains. Default: none. No
terminationGracePeriodSeconds duration Optional duration in seconds for stunnerd to terminate gracefully. Default: 3600 seconds. No
hostNetwork bool Deploy the dataplane into the host network namespace of Kubernetes nodes. Useful for implementing headless TURN services. May require elevated privileges. Default: false. No
disableHealthCheck bool Disable health-checking. If false, HTTP health-checks are enabled on port 8086: liveness probe responder will be exposed on path /live and readiness probe on path /ready. Default: false. No
enableMetricsEndpoint bool Enable Prometheus metrics scraping. If true, a metrics endpoint will be available at http://0.0.0.0:8080. Default: false. No
dataplaneResource string Kubernetes resource type to be used for deploying the dataplane, either a Deployment (default) or DaemonSet (not supported in the free tier). No

A change to a Dataplane (a new image, resources, arguments) takes effect through a rolling update of the stunnerd pods of every Gateway that uses it: Kubernetes starts a new pod and retires the old one only once the new one is ready. If the new pod never gets ready (it cannot be scheduled, its image cannot be pulled, it crashes), the old pod keeps serving with the previous settings and the change never takes effect. A Deployment gives up on such a rollout at a point; the Gateway then turns Programmed to False with reason Pending. An in-progress rollout sets Programmed=true. Note that a DaemonSet dataplane does not report a stuck rollout.

There can be multiple Dataplane resources defined in a cluster, say, one for the production workload and one for development. Use the spec.dataplane field in the GatewayConfig to choose the Dataplane per each STUNner install.

Warning

A Dataplane resource called default must always be available in the cluster, otherwise the operator will not know how to provision dataplane pods. Removing the default template will break your STUNner installation.