l7mp/stunner-gateway-operator

STUNner Kubernetes Gateway Operator 镜像文档

概述和主要用途

STUNner Kubernetes Gateway Operator（简称STUNner）是基于Kubernetes Gateway API的STUN/TURN协议网关操作器，专为容器化实时媒体通信应用设计。它实现了NAT（网络地址转换）穿透功能，通过标准化协议（RFC 5389、RFC 5766、RFC 8656）解决跨网络环境下的连接建立问题，支持WebRTC、视频会议、实时游戏等低延迟媒体应用在Kubernetes集群中稳定部署。

核心功能和特性

• Kubernetes原生集成：遵循Kubernetes Gateway API规范，通过自定义资源（CR）实现声明式配置，支持与现有Kubernetes网络组件无缝协作。

• 动态协议支持：完整实现STUN（NAT类型检测）和TURN（中继服务）协议，支持UDP、TCP传输层协议，适应不同网络环境需求。

• 高可用性设计：支持多副本部署、自动扩缩容和故障自愈，通过Kubernetes控制器模式确保网关服务持续可用。

• 安全增强：内置TLS/DTLS加密、长期凭证认证机制，支持访问控制策略，保护媒体流传输安全。

• 可观测性集成：暴露Prometheus指标接口和结构化日志，支持与Grafana、ELK等监控工具集成，便于性能分析和问题排查。

• 灵活路由能力：通过UDPRoute/TCPRoute资源定义媒体流转发规则，支持基于命名空间、端口、主机名的精细化流量控制。

使用场景和适用范围

典型应用场景

• WebRTC应用部署：为浏览器/移动端WebRTC应用提供NAT穿透，解决客户端间直接连接失败问题。
• 视频会议系统：支持多节点媒体流中继，确保跨网络参会者的音视频数据稳定传输。
• 实时游戏服务：降低玩家间数据传输延迟，提升P2P连接成功率，优化游戏体验。
• 物联网设备通信：实现边缘IoT设备与云端服务的实时双向通信，克服网络地址转换障碍。
• 混合云媒体中继：在多集群或跨云环境中作为媒体流枢纽，优化跨区域数据传输路径。

适用环境

• Kubernetes集群（v1.21+），需预先安装Gateway API CRD（v1beta1+）。
• 需处理NAT穿透需求的实时媒体应用，尤其适合动态IP环境、多层防火墙隔离场景。

详细使用方法和配置说明

安装步骤

前置条件

• Kubernetes集群（v1.21+）
• Helm 3.5+
• Gateway API CRD（可通过kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/standard-install.yaml安装）

Helm安装

bash
# 添加STUNner Helm仓库
helm repo add stunner https://l7mp.io/stunner
helm repo update

# 安装STUNner Operator（默认命名空间：stunner-system）
helm install stunner stunner/stunner --namespace stunner-system --create-namespace

核心配置示例

1. 定义GatewayClass

yaml
apiVersion: gateway.networking.k8s.io/v1beta1
kind: GatewayClass
metadata:
  name: stunner-gatewayclass
spec:
  controllerName: stunner.l7mp.io/gateway-controller  # STUNner控制器标识
  parametersRef:
    group: stunner.l7mp.io
    kind: GatewayConfig
    name: stunner-default-config  # 可选：引用自定义配置

2. 创建Gateway资源

yaml
apiVersion: gateway.networking.k8s.io/v1beta1
kind: Gateway
metadata:
  name: stunner-media-gateway
  namespace: media-app
spec:
  gatewayClassName: stunner-gatewayclass
  listeners:
  - name: stun-udp
    protocol: UDP
    port: 3478  # STUN默认端口
    hostname: "stunner.example.com"
    allowedRoutes:
      namespaces:
        from: Selector
        selector:
          matchLabels:
            app: media-service
  - name: turn-tcp
    protocol: TCP
    port: 3479  # TURN TCP端口
    hostname: "stunner.example.com"

3. 配置媒体流路由（UDPRoute）

yaml
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: UDPRoute
metadata:
  name: media-service-route
  namespace: media-app
spec:
  parentRefs:
  - name: stunner-media-gateway
    namespace: media-app
  rules:
  - backendRefs:
    - name: media-server-svc  # 目标媒体服务Service
      port: 8080  # 媒体服务监听端口

环境变量配置

STUNner Operator支持通过环境变量调整运行参数，常用配置如下：

部署示例（本地测试）

如需本地Docker环境测试（需连接Kubernetes集群）：

bash
docker run -d \
  --name stunner-operator \
  -e POD_NAMESPACE=stunner-system \
  -e KUBERNETES_SERVICE_HOST=<kube-apiserver-ip> \
  -e KUBERNETES_SERVICE_PORT=6443 \
  -v /path/to/kubeconfig:/root/.kube/config \
  l7mp/stunner-operator:latest

注意：本地测试需确保容器可访问Kubernetes API，建议通过挂载kubeconfig文件或配置KUBERNETES_SERVICE_HOST/KUBERNETES_SERVICE_PORT环境变量实现。

注意事项

• Gateway API依赖：需提前在集群中安装Gateway API CRD（v1beta1+版本），否则STUNner自定义资源将无法创建。
• 资源规划：根据媒体流带宽需求调整CPU/内存资源限制，建议单副本配置至少1核CPU、1Gi内存。
• 安全加固：生产环境需启用TURN认证（配置authType: long-term）和TLS加密，避免未授权访问和数据泄露。