docs: more on clients and stuff

Signed-off-by: Michael Schilonka <michael@blueshoe.io>

gefyra/versioned_docs/version-2.0.0/shared-environments/clients.md

@@ -6,9 +6,7 @@ sidebar_position: 2
 # Working With Gefyra Clients
 
 :::note **TLDR;**
-
 Gefyra Clients provide a way to grant multiple clients (i.e. users, robots, pipelines, etc.) limited access to a Kubernetes cluster in order to use Gefyra's capabilities. They are managed with [`gefyra clients [COMMAND]`](/docs/cli#clients).
-
 ::: 
 
 Gefyra introduces the concept of **Gefyra Clients**. These are objects to manage and distribute access to the cluster.  
@@ -18,7 +16,7 @@ Gefyra introduces the concept of **Gefyra Clients**. These are objects to manage
 Each created client object get a dedicated *Kubernetes Service Account* attached that is being used by any Gefyra client during its interaction with the cluster. The corresponding *client file*, which contains the connection parameters for the *Service Account* can be retrieved from the cluster by the administrator with Gefyra's CLI.  
 
 This client file can be then distributed to anyone which needs to `connect`, `run` or `bridge` workloads in the given cluster.
-The permissions of the Kubernetes service account are limited, following the principle of the least privilege. Hence, Gefyra clients can only operate in the cluster with the well-defined set Gefyra's actions.
+The permissions of the Kubernetes service account are limited, following the principle of the least privilege. Hence, Gefyra clients can only operate in the cluster with the well-defined set of Gefyra's actions.
 
 This flow gives a brief overview of Gefyra's workflow for teams:
 ```mermaid
@@ -36,20 +34,24 @@ flowchart TD;
     connect-->run
 ```
 
-
-**Important:** Although clients may be shared by multiple machines, it is neither recommended not will it work simultaneously.
+:::important Don't share client connections
+Although clients may be used by multiple machines, it is neither recommended not will it work simultaneously.
 Once a client connects to a cluster, it agrees with Gefyra's Operator on a dedicated IP-range that no other client can use at the same time. Clients may *connect* and *disconnect* at any time. When disconnecting from the cluster, clients release their VPN peer (and thus their IP-range) association.
+:::
 
-## Prerequisites
+:::note Prerequisites
 1. Gefyra is [available](https://gefyra.dev/installation) (at least in version 2.0.0)  
 2. Gefyra is [installed](./installation) to a shared Kubernetes cluster
 3. Admin access to the shared cluster
+:::
 
 ## Creating a Gefyra Client
 You can create as many clients as you need in a cluster. Every client will have it's very own VPN connection to the cluster.  
 An admin manages clients via Gefyra's `gefyra client` command group in the CLI. Gefyra operates with the currently active cluster context on the machine it is running on.
 
-**Remark:** Check your active cluster context with `kubectl config current-context`.
+:::note Kubernetes context
+Check your active cluster context with `kubectl config current-context`.
+:::
 
 ```bash
 > gefyra client
@@ -113,8 +115,10 @@ As you can see, the *client file* is JSON-structured and contains a lot of secre
 *access token* of the Kubernetes service account that is associated with this Gefyra client, but also the other connection
 parameters are **highly sensible**.
 
-**Important:** Please handle the *client files* with care as they contain confidential information. Leaking these files may
+:::important Keep client files safe
+Please handle the *client files* with care as they contain confidential information. Leaking these files may
 allow unidentified individuals access to your Gefyra cluster.
+:::
 
 You can either pipe that output to a file on your local machine:
 ```
@@ -127,12 +131,14 @@ gefyra clients config 20d50da476524eaf8dd511deed55fc63 -o 20d50da476524eaf8dd511
 in your current working directory.
 
 ### Providing Custom Connection Data
-**Important:** In this process, Gefyra tries to determine as many connection parameters as possible automatically. However,
+:::important Custom networking
+In this process, Gefyra tries to determine as many connection parameters as possible automatically. However,
 if there are network-related customizations to made for your client, please provide them at this point.
+:::
 
 If you need to specify the connection endpoint for Kubernetes differently, please use the `--kubernetes-api` option, e.g.
 ```
-gefyra clients config 20d50da476524eaf8dd511deed55fc63 -o 20d50da476524eaf8dd511deed55fc63.json --kubernetes-api "https://k8s.blueshoe.io"
+gefyra clients config 20d50da476524eaf8dd511deed55fc63 --kubernetes-api "https://k8s.blueshoe.io"
 ```
 
 If you need to specify Gefyra's VPN connection endpoint, please use the `--host` and/or `--port` option, e.g.
@@ -148,7 +154,7 @@ This *client file* is all a Gefyra client needs in order to establish a connecti
 
 ## Deleting a Gefyra Client
 You can delete a Gefyra client in every stage of its lifecycle. This will disconnect the client (forcefully) and render its
-*client file* invalid to that the owner of the file will no longer be able to connect to the cluster.
+*client file* invalid, thus the owner of the file will no longer be able to connect to the cluster.
 ```
 > gefyra clients delete 20d50da476524eaf8dd511deed55fc63
 Client 20d50da476524eaf8dd511deed55fc63 marked for deletion

gefyra/versioned_docs/version-2.0.0/shared-environments/connecting.md

@@ -6,17 +6,90 @@ sidebar_position: 3
 # Connecting to Gefyra
 
 :::note **TLDR;**
-
 If you have a Gefyra *client file* and want to connect to a shared Kubernetes cluster,   
 just run `gefyra connections connect -f <file>`.
-
 ::: 
 
+Connecting to a Gefyra-enabled Kubernetes cluster is the process of any Gefyra client to establish a networking connection based on [Wireguard VPN](https://www.wireguard.com/) to a cluster. It is a multistep process that involves the dynamic creation of connection credentials and IP-range negotiation
+between cluster and client. The network connection is persistent for the session, rock-solid and blazingly fast.
+
+:::note Prerequisites
+1. Gefyra is [available](https://gefyra.dev/installation) (at least in version 2.0.0)
+2. A running Docker host on the machine that connects  
+3. A Gefyra [*client file*](/docs/shared-environments/clients#a-default-client-file)
+:::
+
 ## Managing Connections
+Client connections to a Gefyra cluster are managed with the `gefyra connections` command group.  
+The connection itself consists of a file, that is located in a local user directory, and *usually* a 
+Docker container that acts as a VPN endpoint on a local machine.
 
 ### Connect
+:::important Gefyra client file required
+You can only connect to a Gefyra cluster with a [*client file*](/docs/shared-environments/clients#distributing-the-client-file). 
+If you don't have such a client file, either [set up Gefyra in a Kubernetes cluster](/docs/shared-environments/installation) and create yourself
+[a Gefyra *client*](/docs/shared-environments/clients#creating-a-gefyra-client), or find the responsible person and ask for access.
+:::
+
+Establishing a connection (**for the first time**) to Gefyra works like this:
+```
+> gefyra connections connect -f myfancyclient.json
+
+Creating the cluster connection 'default' |   ▶▶▶▶▶▶▶          | / 0 in 28s
+
+Connection established with connection name 'default'. Run 'gefyra connections list' to see all connections.
+```
+This example assumes, there is a client that provides the client file *myfancyclient.json*. A couple of things happened during this process:
+
+1. Gefyra fetched the ad-hoc VPN credentials for this connection
+2. A container for the Gefyra connection with name *default* has been started
+3. A dedicated Docker network has been created
+3. The connection was successfully checked
+
+If you check your Docker host, you will find a container named `gefyra-cargo-default` running. That's the gateway into the cluster.
+
+:::note Default connection
+Since we didn't specify a *connection name* and there was no *default* connection available before, creating it was successful. However, there
+is only one *default* connection on a client machine. Additional connections must [be assigned a name](#connection-names).
+:::
+
+Once you have a stopped connection, you don't need the client file anymore to connect. Just run the following with the *default* connection:
+```
+> gefyra connections connect
+```
+The Gefyra connection will be back up in no time. Of course, if you do have multiple connections, you have to specify the connection name with the
+`--connection-name` option.
+
+:::note Client file superseded
+After you successfully connected a machine with a Gefyra cluster, the *client file* is typically superseded at that point. Gefyra stores the 
+credentials from the file elsewhere, so a user doesn't have to handle the file. However, if you remove your connection and want to reconnect 
+to the cluster (assuming the Gefyra client is still the same) you may connect to the cluster with that file again. Yet, you can also request a 
+new one, which is safer than having a *client file* dangling.
+:::
+
+### Listing Connections
+To see all Gefyra connections on a local machine, please run the following:
+```
+> gefyra connections list
+NAME     VERSION    CREATED                         STATUS
+default  2.0.0      2023-10-10T18:36:15.519969679Z  running
+```
+
+You will find the status of all of your connections here. It can be `running`, `stopped` or `error`.
 
 ### Disconnect
+To actively disconnect from the cluster, you run this command:
+```
+gefyra connections stop
+```
+This assumes you have a *default* connection currently running. If not, you have to provide a valid connection name with the `--connection-name` option.
+
+You will find this connection to be stopped from the client's side. However, if you want to reconnect to the cluster, you can now run `gefyra connections connect` again. The connection process will be superfast this time.
+
+:::important Deleting a connection
+If you want to delete a connection, and thus release the Gefyra client in the cluster, you can run `gefyra connections remove`. If you want to reconnect 
+later, you will need a *client file* again.
+:::
 
 ### Connection Names
 

gefyra/versioned_docs/version-2.0.0/shared-environments/installation.md

@@ -8,9 +8,9 @@ sidebar_position: 1
 Installing Gefyra to a remote cluster is usually slightly different to a local setup. This is because the networking aspect
 differs considerably between a local cluster, that might be created with overlay networks and port-forwarding, and remote clusters with cloud-specific routing components. Starting with Gefyra 2, you get good control of the cluster-side components. 
 
-## Prerequisites
+:::note Prerequisites
 Gefyra is [available](https://gefyra.dev/installation) (at least in version 2.0.0)
-
+:::
 
 ## The Installation
 There are a couple of options for the installation procedure. Gefyra's executable ships with all required Kubernetes configs
@@ -46,13 +46,18 @@ If the default configuration is suitable for your environment, directly apply it
 gefyra install | kubectl apply -f -
 ```
 That will pipe the Kubernetes configs generated by Gefyra's install command directly into the cluster context
-that is currently active.  
-**Remark:** Check you current cluster context with `kubectl config current-context`
+that is currently active.
+
+:::note Kubernetes context
+Check your active cluster context with `kubectl config current-context`.
+:::
 
 ## Default Networking
 Gefyra depends on a working [Wireguard VPN](https://www.wireguard.com/) connection between the cluster and Gefyra's clients. Setting up that connection is completely managed by Gefyra and only requires little configuration from a cluster admin: that is configuring the VPN route.
 
-**Important:** Gefyra's default to expose its Wireguard endpoint is via a Kubernetes service of type **NodePort**. However, that is only feasible if the Kubernetes nodes have a public (internet-routable) IP address, or at least this IP is reachable for all clients.
+:::important NodePort default
+Gefyra's default to expose its Wireguard endpoint is via a Kubernetes service of type **NodePort**. However, this can only work if the Kubernetes nodes have a public (internet-routable) IP address, or at least this IP is reachable for all clients.
+:::
 
 You can check out the Kubernetes service object in the output of `gefyra install`.
 ```yaml
@@ -87,7 +92,9 @@ If you don't want to expose Gefyra via a *NodePort* service, or you don't have r
 to set up a **UDP load balancing** for Gefyra. Luckily, Gefyra's got you covered.
 
 ## Setting up a UDP `Loadbalancer`
-**Important:** Gefyra's VPN connection is established using UDP traffic. Not all cloud providers offer a UDP load balancing solution. If you can not use a *Loadbalancer*, you have to stick with the *NodePort* service.
+:::important UDP load balancing
+Gefyra's VPN connection is established using UDP traffic. Not all cloud providers offer a UDP load balancing solution. If you can not use a *Loadbalancer*, you have to stick with the *NodePort* service.
+:::
 
 To switch the load balancer service for the installation, just set the appropriate option flag for the `gefyra install` command:
 ```bash