From 4d519f8f836bcdb362697994f147d2af0332ff96 Mon Sep 17 00:00:00 2001
From: "Han Verstraete (OpenFaaS Ltd)" <han@openfaas.com>
Date: Tue, 21 Mar 2023 14:18:44 +0100
Subject: [PATCH] Document versioning/upgrading inlets for uplink

Signed-off-by: Han Verstraete (OpenFaaS Ltd) <han@openfaas.com>
---
 docs/uplink/create-tunnels.md | 27 +++++++++++++++++++++++++++
 docs/uplink/manage-tunnels.md | 28 ++++++++++++++++++++++++++++
 2 files changed, 55 insertions(+)

diff --git a/docs/uplink/create-tunnels.md b/docs/uplink/create-tunnels.md
index 9b1bf0e..6900a92 100644
--- a/docs/uplink/create-tunnels.md
+++ b/docs/uplink/create-tunnels.md
@@ -135,6 +135,33 @@ spec:
     region: east
 ```
 
+## Set the inlets version used by tunnels
+
+The inlets version for a tunnel can be set by using the `inletsVersion` field in the tunnel spec. If the field is omitted, the tunnel wil use the inlets version configured in the `values.yaml` file.
+
+```yaml
+apiVersion: uplink.inlets.dev/v1alpha1
+kind: Tunnel
+metadata:
+  name: acmeco
+  namespace: tunnels
+spec:
+  inletsVersion: 0.9.18
+  licenseRef:
+    name: inlets-uplink-license
+    namespace: tunnels
+```
+
+The version can also be set when creating a tunnel with the CLI:
+
+```bash
+inlets-pro tunnel create acmeco \
+  -n tunnels
+  --version "0.9.18"
+```
+
+To prevent mismatches with the inlets uplink client existing tunnels are not automatically updated when the `inletsVersion` parameter in the Chart changes. See [upgrading tunnels](/uplink/manage-tunnels/#upgrade-the-inlets-version-of-a-tunnel).
+
 ## Connect to tunnels
 
 The `uplink client` command is part of the inlets-pro binary. It is used to connect to tunnels and expose services over the tunnel.
diff --git a/docs/uplink/manage-tunnels.md b/docs/uplink/manage-tunnels.md
index 0a2f217..b5f2091 100644
--- a/docs/uplink/manage-tunnels.md
+++ b/docs/uplink/manage-tunnels.md
@@ -99,6 +99,34 @@ spec:
 
 Alternatively, if you have the tunnel saved as a YAML file, you can edit it and apply it again with `kubectl apply`.
 
+## Upgrade the inlets version of a tunnel
+
+The inlets version for a tunnel is set upon tunnel creation either by setting the `inletsVersion` in Tunnel Custom Resource or the default version configured in the `values.yaml` file is used.
+
+To prevent mismatches with the inlets uplink client the inlets version is never upgraded unless it is explicitly updated in the Tunnel Custom Resource.
+
+You can change the inlets version used by the tunnel deployment by editing the Tunnel CRD. Add or edit the `inletsVersion` field in the tunnel spec and set it to the desired version:
+
+```bash
+kubectl edit -n tunnels \
+  tunnel/acmeco  
+```
+
+```diff
+apiVersion: uplink.inlets.dev/v1alpha1
+kind: Tunnel
+metadata:
+  name: acmeco
+  namespace: tunnels
+spec:
++ inletsVersion: 0.9.18 
+  licenseRef:
+    name: inlets-uplink-license
+    namespace: tunnels
+  tcpPorts:
+  - 8080
+```
+
 ## Check the logs of a tunnel
 
 The logs for tunnels can be useful for troubleshooting or to see if clients are connecting successfully.