STUNner Kubernetes Gateway Operator

The STUNner Kubernetes Gateway Operator is an open-source implementation of the Kubernetes Gateway API using STUNner as the data plane. The goal is to implement the part of the core Gateway API, namely Gateway, GatewayClass and UDPRoute resources, that are necessary to fully configure the STUNner WebRTC ingress gateway via the Kubernetes control plane. The STUNner Kubernetes Gateway Operator is currently supports only a subset of the Gateway API.

Documentation

Full documentation for the stable version can be found here. The documentation of the development version is maintained here.

Configuration: Flags and Environment Variables

The operator supports both command-line flags and environment variables.

• --controller-name can be set directly or the environment var STUNNER_GATEWAY_OPERATOR_CONTROLLER_NAME.
• --dataplane-mode can be set directly or the environment var STUNNER_GATEWAY_OPERATOR_DATAPLANE_MODE.
• --config-discovery-address can be set directly or the environment var STUNNER_GATEWAY_OPERATOR_ADDRESS.
• --pprof-bind-address can be set directly or the environment var STUNNER_GATEWAY_OPERATOR_PPROF_BIND_ADDRESS.
• CUSTOMER_KEY is read from the environment for licensing.

Command-line flags take precedence over environment variables.

Debug profiling (pprof)

Pprof is disabled by default (--pprof-bind-address=0). For debugging, prefer binding to 127.0.0.1:6060 and use kubectl port-forward to access /debug/pprof/ endpoints.

Example:

1. Enable pprof in the operator args by adding --pprof-bind-address=127.0.0.1:6060 to the operator's startup command.
2. Create a port-forward to the operator pod:

   kubectl -n stunner-system port-forward $(kubectl get pod -A -l control-plane=stunner-gateway-operator-controller-manager -o jsonpath='{.items[0].metadata.name}') 6060:6060

3. Inspect goroutine stacks:

   curl -s "http://127.0.0.1:6060/debug/pprof/goroutine?debug=2"

4. Or open interactive pprof UI:

   go tool pprof -http=:8081 "http://127.0.0.1:6060/debug/pprof/profile?seconds=30"

Do not expose pprof publicly, profiles may contain sensitive runtime details.

Gateway label propagation filter

The operator propagates labels from a Gateway resource onto the Deployment it provisions for that Gateway. Certain labels are filtered though, in order to avoid collisions with ecosystem tools that use labels as ownership claims. Most notably, kubectl apply --prune --applyset will sweep the operator's Deployments (see #70), unless the corresponding labels (applyset.kubernetes.io/part-of, applyset.k8s.io/part-of) are filtered from propagating into the Deployment. The default is to filter the below well-known keys:

• applyset.kubernetes.io/part-of, applyset.k8s.io/part-of
• app.kubernetes.io/managed-by
• argocd.argoproj.io/instance
• kustomize.toolkit.fluxcd.io/name, kustomize.toolkit.fluxcd.io/namespace

Override the list via STUNNER_GATEWAY_OPERATOR_LABEL_FILTER (comma-separated). The env-var, when set, replaces the default. Set it to the empty string to disable filtering.

Metrics

Prometheus metrics are served at --metrics-bind-address (default :8080/metrics).

Controller-runtime built-ins (most useful for day-to-day monitoring):

Metric	Type	Description
controller_runtime_reconcile_total{controller,result}	Counter	Reconciliations per controller, split by result (success, error, requeue, requeue_after).
controller_runtime_reconcile_time_seconds{controller}	Histogram	Per-reconciliation latency.
controller_runtime_reconcile_errors_total{controller}	Counter	Reconciliation errors per controller.
controller_runtime_active_workers{controller}	Gauge	Workers currently processing a reconcile request.

Operator-specific metrics (prefix stunner_gateway_operator_):

Metric	Type	Description
render_total	Counter	Render cycles completed by the renderer thread.
render_time_seconds	Histogram	Duration of a full render cycle.
update_total{result}	Counter	Update cycles completed by the updater thread (success / error).
update_errors_total	Counter	Update cycles that returned an error.
update_time_seconds	Histogram	Duration of a full update cycle.
resource_operations_total{scope,kind,operation}	Counter	Individual Kubernetes API calls made by the updater, labelled by scope (spec/status), resource kind, and operation (created, updated, error, suppressed, ...).
reconcile_events_total{result}	Counter	Reconcile events received by the operator event loop (passed when a render is scheduled, throttled when rate-limited).
generation	Gauge	Current config generation number.
generation_last_acked	Gauge	Generation number of the last update acknowledged by the updater.

Caveats

• STUNner implements its own UDPRoute resource instead of using the official UDPRoute provided by the Gateway API. The reason is that STUNner's UDPRoutes omit the port defined in backend references, in contrast to standard UDPRoutes that make the port mandatory. The rationale is that WebRTC media servers typically spawn zillions of UDP/SRTP listeners on essentially any UDP port, so enforcing a single backend port would block all client access. Instead, STUNner's UDPRoutes do not limit port access on backend services at all by default, and provide an optional pair or port/end-port fields per backend reference to define a target port range in which peer connections to the backend are to be accepted.
• The operator actively reconciles the changes in the GatewayClass resource; e.g., if the parametersRef changes then we take this into account (this is not recommended in the spec to limit the blast radius of a mistaken config update).
• ReferenceGrants are not implemented: routes can refer to Services and StaticServices in any namespace.
• The operator does not invalidate the GatewayClass status on exit and does not handle the case when the parent GatewayClass is removed from Gateway.

Help

STUNner development is coordinated in Discord, feel free to join.

License

Copyright 2021-2026 by its authors. Some rights reserved. See AUTHORS.

APACHE License - see LICENSE for full text.

Acknowledgments

Inspired from the NGINX Kubernetes Gateway and the Kong Gateway Operator.