Skip to content

Commit

Permalink
doc: Document premium features
Browse files Browse the repository at this point in the history
  • Loading branch information
@rg0now
rg0now committed Feb 20, 2025
1 parent baaca16 commit ef56901
Show file tree
Hide file tree
Showing 5 changed files with 253 additions and 18 deletions.
26 changes: 24 additions & 2 deletions cmd/stunnerctl/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -136,6 +136,20 @@ The `status` sub-command reports the status of the dataplane pods for a gateway,
TERMINATING
```

### License status

STUNner requires a valid license to unlock premium features. The below will report STUNner's license status:

```console
stunnerctl license
License status:
Subscription type: member
Enabled features: DaemonSet, STUNServer, ...
Last updated: ...
```

This command will connect to your STUNner gateway operator and validate your license. It will also report any errors STUNner may have encountered while validating your license.

### Authentication

The `auth` sub-command can be used to obtain a TURN credential or a full ICE server config for connecting to a specific gateway. The authentication service API is usually served by a separate [STUNner authentication server](https://github.com/l7mp/stunner-auth-service) deployed alongside the gateway operator. The main use of this command is to feed an ICE agent manually with the ICE server config to connect to a specific STUNner gateway.
Expand All @@ -144,14 +158,22 @@ The `auth` sub-command can be used to obtain a TURN credential or a full ICE ser

``` console
stunnerctl -n stunner auth udp-gateway
{"iceServers":[{"credential":"pass-1","urls":["turn:10.104.19.179:3478?transport=udp"],"username":"user-1"}],"iceTransportPolicy":"all"}
{"iceServers":[{"credential":"pass-1","urls":["turn:1A.B.C.D:3478?transport=udp"],"username":"user-1"}],"iceTransportPolicy":"all"}
```

- Request a plain [TURN credential](https://datatracker.ietf.org/doc/html/draft-uberti-behave-turn-rest-00) using the authentication service deployed into the `stunner-system-prod` namespace:

``` console
stunnerctl -n stunner auth udp-gateway --auth-turn-credential --auth-service-namespace=stunner-system-prod
{"password":"pass-1","ttl":86400,"uris":["turn:10.104.19.179:3478?transport=udp"],"username":"user-1"}
{"password":"pass-1","ttl":86400,"uris":["turn:A.B.C.D:3478?transport=udp"],"username":"user-1"}
```

- Obtain an ICE config for the Gateway `stunner/udp-gateway` and setting the user-id to `my-user`
(useful for ephemeral authentication):

``` console
stunnerctl -n stunner auth udp-gateway --username my-user
{"iceServers":[{"credential":"...=","urls":["turn:A.B.C.D:3478?transport=udp"],"username":"1740150333:my-user"}],"iceTransportPolicy":"all"}
```

### ICE test
Expand Down
2 changes: 2 additions & 0 deletions docs/AUTH.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

STUNner uses the IETF STUN/TURN protocol suite to ingest media traffic into a Kubernetes cluster, which, [by design](https://datatracker.ietf.org/doc/html/rfc5766#section-17), provides comprehensive security. In particular, STUNner provides message integrity and, if configured with the TURN-TLS or TURN-DTLS listeners, confidentiality. To complete the CIA triad, this guide shows how to configure user authentication with STUNner.

Note that STUNner can also be deployed as a STUN server without enabling the TURN protocol features (only available in premium tiers), in which case it runs with no authentication (`authType:none`). Refer to the [user guide](PREMIUM.md) for the details.

## The long-term credential mechanism

STUNner relies on the STUN [long-term credential
Expand Down
29 changes: 16 additions & 13 deletions docs/GATEWAY.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -60,18 +60,20 @@ spec:

Below is a reference of the most important fields of the GatewayConfig [`spec`](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects)

| 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](AUTH.md). Valid only if `authRef` is not set. | No |
| `password` | `string` | The password for [`static` authentication](AUTH.md). Valid only if `authRef` is not set. | No |
| `sharedSecret` | `string` | The shared secret for [`ephemeral` authentication](AUTH.md). Valid only if `authRef` is not set. | No |
| `authLifetime` | `int` | The lifetime of [`ephemeral` authentication](AUTH.md) 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](https://github.com/l7mp/stunner/issues/32). | No |
| 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](AUTH.md). Valid only if `authRef` is not set. | No |
| `password` | `string` | The password for [`static` authentication](AUTH.md). Valid only if `authRef` is not set. | No |
| `sharedSecret` | `string` | The shared secret for [`ephemeral` authentication](AUTH.md). Valid only if `authRef` is not set. | No |
| `authLifetime` | `int` | The lifetime of [`ephemeral` authentication](AUTH.md) 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](https://github.com/l7mp/stunner/issues/32). | 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 (**not supported in the free tier**). 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.

Expand Down Expand Up @@ -251,7 +253,7 @@ The below table summarizes the Gateway annotations supported by STUNner.
|:----------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------:|
| `stunner.l7mp.io/service-type: <svc-type>` | [Type of the Service](https://kubernetes.io/docs/concepts/services-networking/service) per Gateway, either `ClusterIP`, `NodePort`, or `LoadBalancer`. | `LoadBalancer` |
| `stunner.l7mp.io/enable-mixed-protocol-lb: <bool>` | [Mixed protocol load balancer service](https://kubernetes.io/docs/concepts/services-networking/service/#load-balancers-with-mixed-protocol-types) support. | False |
| `stunner.l7mp.io/external-traffic-policy: <string>` | Se the value to `Local` to preserve clients' source IP at the load balancer. | `Cluster` |
| `stunner.l7mp.io/external-traffic-policy: <string>` | Set the value to `Local` to preserve clients' source IP at the load balancer. | `Cluster` |
| `stunner.l7mp.io/disable-managed-dataplane: <bool>` | Switch managed-dataplane support off for a Gateway. | False |
| `stunner.l7mp.io/nodeport: <map>` | Request a specific NodePort for particular listeners. Value is a JSON map of listener-nodeport key-value pairs. | None |
| `stunner.l7mp.io/targetport: <map>` | Request a specific target port for particular listeners. Value is a JSON map of listener-targetport key-value pairs. | None |
Expand Down Expand Up @@ -411,6 +413,7 @@ The following fields can be set in the Dataplane `spec` to customize the provisi
| `hostNetwork` | `bool` | Deploy the [dataplane](/cmd/stunnerd/README.md) 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 true, enable HTTP health-checks on port 8086: liveness probe responder will be exposed on path `/live` and readiness probe on path `/ready`. Default: true. | 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 |

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.

Expand Down
Loading

0 comments on commit ef56901

Please sign in to comment.