From 5163cd580194995780b39741a1a6671799c527e8 Mon Sep 17 00:00:00 2001
From: Rafael Bodill <justrafi@gmail.com>
Date: Mon, 28 Aug 2023 21:25:40 +0300
Subject: [PATCH] Document konnectivity-client integration

---
 docs/commandline/open-local_csi.md         |  9 +++
 docs/user-guide/apiserver-network-proxy.md | 68 ++++++++++++++++++++++
 2 files changed, 77 insertions(+)
 create mode 100644 docs/user-guide/apiserver-network-proxy.md

diff --git a/docs/commandline/open-local_csi.md b/docs/commandline/open-local_csi.md
index a3326475..b52ccef8 100644
--- a/docs/commandline/open-local_csi.md
+++ b/docs/commandline/open-local_csi.md
@@ -22,6 +22,15 @@ open-local csi [flags]
       --master string                       URL/IP for master.
       --nodeID string                       the id of node
       --path.sysfs string                   Path of sysfs mountpoint (default "/host_sys")
+      --use-node-hostname                   use node hostname dns for grpc connection
+      --konnectivity-uds                    apiserver-network-proxy unix socket path
+      --konnectivity-proxy-host             apiserver-network-proxy server host
+      --konnectivity-proxy-port             apiserver-network-proxy server port
+      --konnectivity-proxy-mode             apiserver-network-proxy proxy mode
+      --konnectivity-client-cert            apiserver-network-proxy client cert
+      --konnectivity-client-key             apiserver-network-proxy client key
+      --konnectivity-ca-cert                apiserver-network-proxy CA cert
+
 ```
 
 ### Options inherited from parent commands
diff --git a/docs/user-guide/apiserver-network-proxy.md b/docs/user-guide/apiserver-network-proxy.md
new file mode 100644
index 00000000..068393af
--- /dev/null
+++ b/docs/user-guide/apiserver-network-proxy.md
@@ -0,0 +1,68 @@
+# apiserver-network-proxy (ANP)
+
+The [apiserver-network-proxy](https://github.com/kubernetes-sigs/apiserver-network-proxy)
+service, also named [Konnectivity setup](https://kubernetes.io/docs/tasks/extend-kubernetes/setup-konnectivity/),
+provides a TCP level proxy for the control plane _to_ cluster communication.
+
+Open-Local's CSI plugin runs an LVM daemon, by default on port `1736`, allowing
+the controller and node plugins to communicate with worker nodes. However, in
+some cases workers might be running at the edge, behind a NAT or other network
+constraints. There are platforms like OpenYurt and SuperEdge that offer proxy
+tunnels and various other edge solutions. With these, you might be interested in
+the [`--use-node-hostname`](/docs/commandline/open-local_csi.md) argument, which
+will use the node host-name DNS, instead of its IP, for the gRPC connection.
+
+Konnectivity relies on an [`EgressSelectorConfiguration`](https://kubernetes.io/docs/reference/config-api/apiserver-config.v1alpha1/#apiserver-k8s-io-v1alpha1-EgressSelectorConfiguration)
+to proxy traffic from the kube-apiserver (KAS) into the worker nodes. KAS can be
+configured to send traffic (or not) to one or more of the proxies.
+
+Open-Local supports the Konnectivity proxy using Unix socket or http-connect.
+With this, Open-Local will communicate with the nodes through the Konnectivity
+proxy and reach edge worker nodes.
+
+Following are usage examples, with relevant changes to csi-plugin args:
+
+## Using http-connect
+
+```yaml
+spec:
+  containers:
+  - name: csi-plugin
+    args:
+    - csi
+    - --konnectivity-proxy-host=rafi-konnectivity-server.rafi
+    - --konnectivity-proxy-port=8090
+    - --konnectivity-proxy-mode=http-connect
+    - --konnectivity-client-cert=/pki/konnectivity/tls.crt
+    - --konnectivity-client-key=/pki/konnectivity/tls.key
+    - --konnectivity-ca-cert=/pki/konnectivity/ca.crt
+    volumeMounts:
+    - mountPath: /pki/konnectivity/
+      name: konnectivity-client
+      readOnly: true
+  volumes:
+  - name: konnectivity-client
+    secret:
+      defaultMode: 420
+      secretName: rafi-pki-konnectivity-client
+```
+
+## GRPC socket
+
+```yaml
+spec:
+  containers:
+  - name: csi-plugin
+    args:
+    - csi
+    - --konnectivity-uds=/etc/kubernetes/konnectivity-server/konnectivity-server.socket
+    - --konnectivity-proxy-mode=grpc
+    volumeMounts:
+    - name: konnectivity-uds
+      mountPath: /etc/kubernetes/konnectivity-server
+  volumes:
+  - name: konnectivity-uds
+    hostPath:
+      path: /etc/kubernetes/konnectivity-server
+      type: DirectoryOrCreate
+```