From 3ea3943d10a2cb4e504e2b7cd857938f023b929f Mon Sep 17 00:00:00 2001
From: Claudio Lorina <claudio.lorina@gmail.com>
Date: Thu, 30 Jan 2025 10:40:41 +0100
Subject: [PATCH] docs: liqoctl generate/delete peering-user

---
 docs/usage/peer.md | 41 +++++++++++++++++++++++++++++++++++++++--
 1 file changed, 39 insertions(+), 2 deletions(-)

diff --git a/docs/usage/peer.md b/docs/usage/peer.md
index acc42c63fd..62f4154267 100644
--- a/docs/usage/peer.md
+++ b/docs/usage/peer.md
@@ -56,12 +56,49 @@ You can configure and fine-tune each module separately using the individual comm
 For the majority and the cases the `liqoctl peer` is enough.
 However, **to know the best strategy for each case and the requirements of each approach, check the [peering strategies guide](/advanced/peering-strategies.md)**.
 
-### Peering establishment
+### Getting the required permissions to establish a peering
+
+To create a peering with a *provider* cluster, you will require a kubeconfig with a set of permissions to establish a connection with it.
+
+The [liqoctl](../installation/liqoctl.md) CLI tool provides utility functions to manage the permissions of users able to create a peering connection with the current cluster.
+
+**From the *provider* cluster**, you can run the following command to generate a *kubeconfig*:
+
+```bash
+liqoctl generate peering-user \
+  --kubeconfig $PROVIDER_KUBECONFIG_PATH \
+  --consumer-cluster-id $CONSUMER_CLUSTER_ID > $CONSUMER_KUBECONFIG_PATH
+```
+
+```{warning}
+Once you generate the *kubeconfig*, take note of it as it will not be stored by Liqo.
+If you lose it, you will need to delete and recreate it.
+```
+
+This command will store a *kubeconfig* with **the minimum permissions to create and destroy a peering with the current cluster** from a cluster with ID `$CONSUMER_CLUSTER_ID`.
+
+You are allowed to have a single peering user for each consumer cluster, so you will not be able to create a new kubeconfig for the same consumer cluster until you delete the previous one.
+
+````{admonition} Note
+To delete a peering user for the consumer cluster with ID `$CONSUMER_CLUSTER_ID`, run:
+
+```bash
+liqoctl delete peering-user \
+  --consumer-cluster-id $CONSUMER_CLUSTER_ID
+```
+
+**Once you delete a peering user, its kubeconfig will not be valid anymore, even if a new peering user for the same cluster is created.**
+````
+
+
+### Establish a peering connection
 
 To proceed, ensure that you are operating in the *consumer* cluster, and then issue the *liqoctl peer* command:
 
 ```bash
-liqoctl --kubeconfig=$CONSUMER_KUBECONFIG_PATH peer --remote-kubeconfig $PROVIDER_KUBECONFIG_PATH
+liqoctl peer \
+  --kubeconfig=$CONSUMER_KUBECONFIG_PATH \
+  --remote-kubeconfig $PROVIDER_KUBECONFIG_PATH
 ```
 
 ```{warning}