From 781573a8de330f104179a4e87bbbcde312e3b6c6 Mon Sep 17 00:00:00 2001
From: "Han Verstraete (OpenFaaS Ltd)" <han@openfaas.com>
Date: Mon, 9 Dec 2024 13:21:20 +0100
Subject: [PATCH] Docs for uplink REST API

Signed-off-by: Han Verstraete (OpenFaaS Ltd) <han@openfaas.com>
---
 docs/uplink/rest-api.md | 150 ++++++++++++++++++++++++++++++++++++++++
 mkdocs.yml              |   1 +
 2 files changed, 151 insertions(+)
 create mode 100644 docs/uplink/rest-api.md

diff --git a/docs/uplink/rest-api.md b/docs/uplink/rest-api.md
new file mode 100644
index 0000000..4f4065d
--- /dev/null
+++ b/docs/uplink/rest-api.md
@@ -0,0 +1,150 @@
+# Inlets Uplink REST API
+
+Inlets uplink tunnels and namespaces can be managed through a REST API.
+
+A quick note on TLS: when you expose the uplink API over the Internet, you should enable HTTPS to prevent snooping and tampering.
+
+## Installation
+
+The Uplink Client API can be enabled through the helm chart. Update the `values.yaml`:
+
+```yaml
+clientApi:
+    enable: true
+
+    # Domain used for client API ingress
+    domain: clientapi.example.com
+```
+
+## Authentication
+
+The Inlets Uplink client API supports authentication through API tokens.
+
+The authentication token can be retrieved from the cluster at any time by an administrator.
+
+```sh
+export TOKEN=$(kubectl get secret -n inlets client-api-token \
+  -o jsonpath="{.data.client-api-token}" \
+  | base64 --decode)
+```
+
+## Tunnels
+
+### Get a tunnel
+
+```sh
+curl -i \
+    -H "Authorization: Bearer ${TOKEN}" \
+    "$CLIENT_API/v1/tunnels/$NAME?namespace=$NAMESPACE"
+```
+
+Adding the query parameter `metrics=1` includes additional tunnel metrics in the response like RX and TX and TCP connection rate.
+
+Path parameters:
+
+* `name` - Name of the tunnel.
+
+Query parameters:
+
+* `namespace` - Namespace where the tunnel should be looked up.
+* `metrics` - Include tunnel metrics in the response.
+
+### List tunnels
+
+```sh
+curl -i \
+    -H "Authorization: Bearer ${TOKEN}" \
+    "$CLIENT_API/v1/tunnels?namespace=$NAMESPACE"
+```
+
+Query parameters:
+
+* `namespace` - Namespace where the tunnel should be looked up.
+
+### Create a tunnel
+
+```sh
+curl -i \
+    -X POST \
+    -H "Authorization: Bearer ${TOKEN}" \
+    "$CLIENT_API/v1/tunnels"
+    -d '{ "name": "acmeco", "namespace": "acmeco", "tcpPorts": [ 80, 443 ]  }'
+```
+
+### Update a tunnel
+
+```sh
+curl -i \
+    -X PUT \
+    -H "Authorization: Bearer ${TOKEN}" \
+    "$CLIENT_API/v1/tunnels"
+    -d '{ "name": "acmeco", "namespace": "acmeco", "tcpPorts": [ 80, 443, 4222 ] }'
+```
+
+### Delete a tunnel
+
+```sh
+curl -i \
+    -X DELETE \
+    -H "Authorization: Bearer ${TOKEN}" \
+    "$CLIENT_API/v1/tunnels/$NAME?namespace=$NAMESPACE"
+```
+
+Path parameters:
+
+* `name` - Name of the tunnel.
+
+Query parameters:
+
+* `namespace` - Namespace where the tunnel should be looked up.
+
+
+## Namespace management
+
+The inlets uplink client API includes REST endpoints for listing, creating and deleting namespaces. Namespaces created through the API are automatically labeled for use with inlets uplink.
+The `kube-system` and `inlets` namespace can not be used as tunnel namespaces.
+
+### List uplink namespace
+
+List all inlets uplink namespaces. This endpoint will list all namespaces with a label `inlets.dev/uplink=1`.
+
+```sh
+curl -i \
+    -H "Authorization: Bearer ${TOKEN}" \
+    "$CLIENT_API/v1/namespace
+```
+
+### Create a namespace
+
+```sh
+curl -i \
+    -X POST \
+    -H "Authorization: Bearer ${TOKEN}" \
+    "$CLIENT_API/v1/tunnels/$NAME?namespace=$NAMESPACE"
+    -d '{ "name": "acmeco" }'
+```
+
+Every namespace created through the API will have the `inlets.dev/uplink=1` label set.
+
+The API supports adding additional namespace labels and annotations:
+
+```json
+{
+    "name": "acmeco",
+    "annotations": {
+        "customer": "acmeco"
+    },
+    "labels": {
+        "customer": "acmeco"
+    }
+}
+```
+
+### Delete a namespace
+
+```sh
+curl -i \
+    -X DELETE \
+    -H "Authorization: Bearer ${TOKEN}" \
+    "$CLIENT_API/v1/namespace/$NAME"
+```
\ No newline at end of file
diff --git a/mkdocs.yml b/mkdocs.yml
index 28c55f3..41f6759 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -120,6 +120,7 @@ nav:
     - Connect to tunnels: uplink/connect-to-tunnels.md
     - Monitor tunnels: uplink/monitoring-tunnels.md
     - Ingress for tunnels: uplink/ingress-for-tunnels.md
+    - REST API: uplink/rest-api.md
   - Reference:
     - Overview: reference/index.md
     - Inlets Operator: reference/inlets-operator.md