doc: Document the new stunnerctl commands (status and auth)

rg0now · rg0now · commit 466b67b7cfea · 2024-02-21T22:55:06.000+01:00
diff --git a/cmd/stunnerctl/README.md b/cmd/stunnerctl/README.md
@@ -26,7 +26,11 @@ go build -o stunnerctl cmd/stunnerctl/main.go
 
 ## Usage
 
-Type `stunnerctl` to get a glimpse of the features provided. Below are some common usage examples.
+Type `stunnerctl` to get a glimpse of the sub-commands and features provided. 
+
+### Config
+
+The `config` sub-command is used to load or watch running dataplane configs from the STUNner config discovery service (CDS) running in a remote Kubernetes cluster. Usually the CDS server role is fulfilled by the [STUNner gateway operator](https://github.com/l7mp/stunner-gateway-operator) but you can choose any CDS service you want (see the `--cds-server-*` CLI flags in the help). The main use of this command is to check the active dataplane configuration for troubleshooting connectivity problems.
 
 - Dump a summary of the running config of the STUNner gateway called `udp-gateway` deployed into the `stunner` namespace:
 
@@ -42,15 +46,21 @@ Type `stunnerctl` to get a glimpse of the features provided. Below are some comm
       Endpoints: [10.76.1.3, 10.80.7.104]
   ```
 
-- Dump a the running config of all gateways in the `stunner` namespace in JSON format (YAML is also available using `-o yaml`):
+- The same, but using the alternative Kubernetes config file `~/my-config.conf` to access the cluster. The rest of the usual `kubectl` flags (`--context`, `--token`, etc.) are also available to select the cluster to connect to.
+
+  ``` console
+  stunnerctl --kubeconfig ~/my-config.conf -n stunner config udp-gateway
+  ```
+
+- Dump the running config of all gateways in the `stunner` namespace in JSON format (YAML is also available using `-o yaml`):
 
   ```console
   stunnerctl -n stunner config -o json
   {"version":"v1","admin":{"name":"stunner/tcp-gateway",...}}
   {"version":"v1","admin":{"name":"stunner/udp-gateway",...}}}
   ```
 
-- Watch all STUNner configs as they are being refreshed and dump only the name of the STUNner gateway whose config changes:
+- Watch STUNner configs as they are being refreshed by the operator and dump only the name of the gateway whose config changes:
 
   ```console
   stunnerctl config --all-namespaces -o jsonpath='{.admin.name}' -w
@@ -59,8 +69,6 @@ Type `stunnerctl` to get a glimpse of the features provided. Below are some comm
   ...
   ```
 
-## Fallback
-
 For those who don't have the Go toolchain available to run `go install`, STUNner provides a minimalistic `stunnerctl` replacement called `stunnerctl.sh`.
 This script requires nothing else than `bash`, `kubectl`, `curl` and `jq` to work. 
 
@@ -80,19 +88,15 @@ Listener 1
         Public port:    3478
 ```
 
-## Last resort
-
-You can also use `kubectl port-forward` to load or watch STUNner configs manually.
-Open a port-forwarded connection to the STUNner gateway operator:
+You can also use `kubectl port-forward` to load or watch STUNner configs manually.  Open a port-forwarded connection to the STUNner gateway operator:
 
 ``` console
 export CDS_SERVER_NAME=$(kubectl get pods -l stunner.l7mp.io/config-discovery-service=enabled --all-namespaces -o jsonpath='{.items[0].metadata.name}')
 export CDS_SERVER_NAMESPACE=$(kubectl get pods -l stunner.l7mp.io/config-discovery-service=enabled --all-namespaces -o jsonpath='{.items[0].metadata.namespace}')
 kubectl -n $CDS_SERVER_NAMESPACE port-forward pod/${CDS_SERVER_NAME} 63478:13478 &
 ```
 
-If all goes well, you can now connect to the STUNner config discovery API served by the gateway operator directly, just using `curl`. 
-The below will load the config of the `udp-gateway` in the `stunner` namespace:
+If all goes well, you can now connect to the STUNner CDS API served by the gateway operator through the port-forwarded tunnel opened by `kubectl` just using `curl`.  The below will load the config of the `udp-gateway` in the `stunner` namespace:
 
 ``` console
 curl -s http://127.0.0.1:63478/api/v1/configs/stunner/udp-gateway
@@ -104,6 +108,52 @@ If you happen to have a WebSocket client like the wonderful [`websocat`](https:/
 websocat ws://127.0.0.1:63478/api/v1/configs/stunner/udp-gateway?watch=true -
 ```
 
+### Status
+
+The `status` sub-command reports the status of the dataplane pods for a gateway, especially the runtime state of the `stunnerd` daemon.
+
+- Find all dataplane pods for the `udp-gateway` in the `stunner` namespace and dump a status summary:
+
+  ``` console
+  stunnerctl -n stunner status udp-gateway
+  stunner/udp-gateway-856c9f4dc9-524hc:
+  	stunner/udp-gateway:{logLevel="all:INFO",health-check="http://:8086"}
+  	static-auth:{realm="stunner.l7mp.io",username="<SECRET>",password="<SECRET>"}
+  	listeners:1/clusters:1
+  	allocs:3/status=READY
+  stunner/udp-gateway-856c9f4dc9-c7wcq:
+  	stunner/udp-gateway:{logLevel="all:INFO",health-check="http://:8086"}
+  	static-auth:{realm="stunner.l7mp.io",username="<SECRET>",password="<SECRET>"}
+  	listeners:1/clusters:1
+  	allocs:2/status=READY
+  ```
+
+- Same but report only the runtime status of the `stunnerd` pods in the `stunner` namespace:
+
+  ``` console
+  stunnerctl -n stunner status -o jsonpath='{.status}'
+  READY
+  TERMINATING
+  ```
+
+### 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.
+
+- Obtain a full ICE server config for `udp-gateway` deployed into the `stunner` namespace:
+
+  ``` 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"}
+  ```
+
+- 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"}
+  ```
+
 ## License
 
 Copyright 2021-2023 by its authors. Some rights reserved. See [AUTHORS](../../AUTHORS).
diff --git a/docs/cmd/stunnerctl.md b/docs/cmd/stunnerctl.md
@@ -5,16 +5,7 @@ The prominent use of `stunnerctl` is to load or watch STUNner dataplane configur
 
 ## Installation
 
-On Linux and macOS, Use [this script](/cmd/getstunner/getstunner.sh) to download the latest version of the `stunnerctl` binary:
-
-```console
-curl -sL https://raw.githubusercontent.com/l7mp/stunner/main/cmd/getstunner/getstunner.sh | sh -
-export PATH=$HOME/.l7mp/bin:$PATH
-```
-> [!NOTE]
-> The script installs `turncat` too.
-
-Install the `stunnerctl` binary using the standard Go toolchain and add it to `$PATH`.
+Install the `stunnerctl` binary using the standard Go toolchain and add it to `$PATH`. 
 
 ```console
 go install github.com/l7mp/stunner/cmd/stunnerctl@latest
@@ -35,7 +26,11 @@ go build -o stunnerctl cmd/stunnerctl/main.go
 
 ## Usage
 
-Type `stunnerctl` to get a glimpse of the features provided. Below are some common usage examples.
+Type `stunnerctl` to get a glimpse of the sub-commands and features provided. 
+
+### Config
+
+The `config` sub-command is used to load or watch running dataplane configs from the STUNner config discovery service (CDS) running in a remote Kubernetes cluster. Usually the CDS server role is fulfilled by the [STUNner gateway operator](https://github.com/l7mp/stunner-gateway-operator) but you can choose any CDS service you want (see the `--cds-server-*` CLI flags in the help). The main use of this command is to check the active dataplane configuration for troubleshooting connectivity problems.
 
 - Dump a summary of the running config of the STUNner gateway called `udp-gateway` deployed into the `stunner` namespace:
 
@@ -51,15 +46,21 @@ Type `stunnerctl` to get a glimpse of the features provided. Below are some comm
       Endpoints: [10.76.1.3, 10.80.7.104]
   ```
 
-- Dump a the running config of all gateways in the `stunner` namespace in JSON format (YAML is also available using `-o yaml`):
+- The same, but using the alternative Kubernetes config file `~/my-config.conf` to access the cluster. The rest of the usual `kubectl` flags (`--context`, `--token`, etc.) are also available to select the cluster to connect to.
+
+  ``` console
+  stunnerctl --kubeconfig ~/my-config.conf -n stunner config udp-gateway
+  ```
+
+- Dump the running config of all gateways in the `stunner` namespace in JSON format (YAML is also available using `-o yaml`):
 
   ```console
   stunnerctl -n stunner config -o json
   {"version":"v1","admin":{"name":"stunner/tcp-gateway",...}}
   {"version":"v1","admin":{"name":"stunner/udp-gateway",...}}}
   ```
 
-- Watch all STUNner configs as they are being refreshed and dump only the name of the STUNner gateway whose config changes:
+- Watch STUNner configs as they are being refreshed by the operator and dump only the name of the gateway whose config changes:
 
   ```console
   stunnerctl config --all-namespaces -o jsonpath='{.admin.name}' -w
@@ -68,16 +69,14 @@ Type `stunnerctl` to get a glimpse of the features provided. Below are some comm
   ...
   ```
 
-## Fallback
-
 For those who don't have the Go toolchain available to run `go install`, STUNner provides a minimalistic `stunnerctl` replacement called `stunnerctl.sh`.
 This script requires nothing else than `bash`, `kubectl`, `curl` and `jq` to work. 
 
 The below will dump the running config of `tcp-gateway` deployed into the `stunner` namespace:
 
 ```console
 cd stunner
-cmd/stunnerctl/stunnerctl.sh running-config stunner/stunner-gateway
+cmd/stunnerctl/stunnerctl.sh running-config stunner/tcp-gateway
 STUN/TURN authentication type:  static
 STUN/TURN username:             user-1
 STUN/TURN password:             pass-1
@@ -89,19 +88,15 @@ Listener 1
         Public port:    3478
 ```
 
-## Last resort
-
-You can use `kubectl port-forward` to load or watch STUNner configs manually. 
-Open a port-forwarded connection to the STUNner gateway operator:
+You can also use `kubectl port-forward` to load or watch STUNner configs manually.  Open a port-forwarded connection to the STUNner gateway operator:
 
 ``` console
 export CDS_SERVER_NAME=$(kubectl get pods -l stunner.l7mp.io/config-discovery-service=enabled --all-namespaces -o jsonpath='{.items[0].metadata.name}')
 export CDS_SERVER_NAMESPACE=$(kubectl get pods -l stunner.l7mp.io/config-discovery-service=enabled --all-namespaces -o jsonpath='{.items[0].metadata.namespace}')
 kubectl -n $CDS_SERVER_NAMESPACE port-forward pod/${CDS_SERVER_NAME} 63478:13478 &
 ```
 
-If all goes well, you can now connect to the STUNner config discovery API served by the gateway operator directly, just using `curl`. 
-The below will load the config of the `udp-gateway` in the `stunner` namespace:
+If all goes well, you can now connect to the STUNner CDS API served by the gateway operator through the port-forwarded tunnel opened by `kubectl` just using `curl`.  The below will load the config of the `udp-gateway` in the `stunner` namespace:
 
 ``` console
 curl -s http://127.0.0.1:63478/api/v1/configs/stunner/udp-gateway
@@ -113,6 +108,52 @@ If you happen to have a WebSocket client like the wonderful [`websocat`](https:/
 websocat ws://127.0.0.1:63478/api/v1/configs/stunner/udp-gateway?watch=true -
 ```
 
+### Status
+
+The `status` sub-command reports the status of the dataplane pods for a gateway, especially the runtime state of the `stunnerd` daemon.
+
+- Find all dataplane pods for the `udp-gateway` in the `stunner` namespace and dump a status summary:
+
+  ``` console
+  stunnerctl -n stunner status udp-gateway
+  stunner/udp-gateway-856c9f4dc9-524hc:
+  	stunner/udp-gateway:{logLevel="all:INFO",health-check="http://:8086"}
+  	static-auth:{realm="stunner.l7mp.io",username="<SECRET>",password="<SECRET>"}
+  	listeners:1/clusters:1
+  	allocs:3/status=READY
+  stunner/udp-gateway-856c9f4dc9-c7wcq:
+  	stunner/udp-gateway:{logLevel="all:INFO",health-check="http://:8086"}
+  	static-auth:{realm="stunner.l7mp.io",username="<SECRET>",password="<SECRET>"}
+  	listeners:1/clusters:1
+  	allocs:2/status=READY
+  ```
+
+- Same but report only the runtime status of the `stunnerd` pods in the `stunner` namespace:
+
+  ``` console
+  stunnerctl -n stunner status -o jsonpath='{.status}'
+  READY
+  TERMINATING
+  ```
+
+### 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.
+
+- Obtain a full ICE server config for `udp-gateway` deployed into the `stunner` namespace:
+
+  ``` 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"}
+  ```
+
+- 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"}
+  ```
+
 ## License
 
 Copyright 2021-2023 by its authors. Some rights reserved. See [AUTHORS](../../AUTHORS).
