docs: more on install

Signed-off-by: Michael Schilonka <[email protected]>

gefyra/versioned_docs/version-2.0.0/cli.md

@@ -22,8 +22,9 @@ The CLI allows to run the following available actions.
 
 ### install
 
-Gefyra installs its _Operator_, validation webhook and _Stowaway_ to the connected cluster.
-**Import** In some scenarios firewalls may be blocking port `31280`. Make sure it is reachable from your machine.
+Gefyra installs its _Operator_, validation webhook and _Stowaway_ (the Wireguard endpoint) to the connected cluster.  
+
+**Important:** Please check out the [documentation on remote cluster installation](/docs/shared-environments/installation).
 
 **Example:**
 ```sh
@@ -172,8 +173,8 @@ gefyra connections rm my-connection
 ### up
 Brings up a local development infrastructure. Gefyra pulls the active `kubectl` connection and installs 
 _Operator_ to the connected cluster. Gefyra waits for _Operator_ to become ready. In the last step, Gefyra rolls out
-the local Docker network and traffic tunnel endpoint.
-**Import** In some scenarios firewalls may be blocking port `31280`. Make sure it is reachable from your machine.
+the local Docker network and traffic tunnel endpoint.  
+**Import:** In some scenarios firewalls may be blocking port `31280`. Make sure it is reachable from your machine.
 
 **Example:**
 ```sh

gefyra/versioned_docs/version-2.0.0/run_vs_bridge.md

@@ -1,5 +1,5 @@
 ---
-title: Run vs Bridge
+title: Run vs. Bridge
 sidebar_position: 7
 ---
 import RunAnimation from '@site/src/components/RunAnimation';

gefyra/versioned_docs/version-2.0.0/shared-environments/_category_.json

@@ -1,4 +1,4 @@
 {
-  "label": "Setting Shared Kubernetes Clusters",
+  "label": "Setting up Shared Kubernetes Clusters",
   "position": 6
 }

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

@@ -1,13 +1,13 @@
 ---
-title: Gefyra Clients
+title: What are Gefyra Clients?
 sidebar_position: 1
 ---
 
 # Gefyra Clients
 
 :::note **TLDR;**
 
-Gefyra Clients provide a way to grant multiple clients limited access to a Kubernetes cluster in order to use Gefyra's capabilities.
+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.
 
 ::: 
 

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

@@ -0,0 +1,186 @@
+---
+title: Installing Gefyra in a Cluster
+sidebar_position: 2
+---
+
+# Gefyra (Remote) Cluster Installation
+
+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
+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
+for that specific version.
+
+To introspect what is going to be installed into your cluster, just run `gefyra install`. This command generates a list of
+Kubernetes objects that can either be stored for manual modification, or directly applied to the cluster.
+```yaml
+> gefyra install
+
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: gefyra
+
+---
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: gefyra-operator
+  namespace: gefyra
+
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+[...]
+```
+Please check out the [CLI reference for that command](/docs/cli#install).  
+
+
+If the default configuration is suitable for your environment, directly apply it with:
+```bash
+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`
+
+## 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.
+
+You can check out the Kubernetes service object in the output of `gefyra install`.
+```yaml
+> gefyra install | grep "type:" -B21
+
+apiVersion: v1
+kind: Service
+metadata:
+  annotations: {}
+  labels:
+    gefyra.dev/app: stowaway
+    gefyra.dev/provider: stowaway
+    gefyra.dev/role: connection
+  name: gefyra-stowaway-wireguard
+  namespace: gefyra
+spec:
+  ports:
+  - name: gefyra-wireguard
+    nodePort: 31820
+    port: 51820
+    protocol: UDP
+    targetPort: 51820
+  selector:
+    gefyra.dev/app: stowaway
+    gefyra.dev/provider: stowaway
+    gefyra.dev/role: connection
+  type: NodePort
+```
+This service will open up the port **31820** on all of your Kubernetes nodes and route VPN traffic to Gefyra.
+
+If you don't want to expose Gefyra via a *NodePort* service, or you don't have routable IPs on your Kubernetes nodes, you need
+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.
+
+To switch the load balancer service for the installation, just set the appropriate option flag for the `gefyra install` command:
+```bash
+> gefyra install --service-type=Loadbalancer
+```
+
+In many cases, the external infrastructure for a Kubernetes cluster is managed via service annotations. With Gefyra you can
+set custom annotations easily using the `--service-annotations` as often as you need. 
+
+For example:  
+`gefyra install --service-type=Loadbalancer --service-annotations service.beta.kubernetes.io/aws-load-balancer-nlb-target-type=ip --service-annotations ervice.beta.kubernetes.io/aws-load-balancer-scheme=internet-facing`
+will create the following service in your cluster:
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  annotations:
+    # see these annotations
+    service.beta.kubernetes.io/aws-load-balancer-nlb-target-type: ip
+    service.beta.kubernetes.io/aws-load-balancer-scheme: internet-facing
+  labels:
+    gefyra.dev/app: stowaway
+    gefyra.dev/provider: stowaway
+    gefyra.dev/role: connection
+  name: gefyra-stowaway-wireguard
+  namespace: gefyra
+spec:
+  ports:
+  - name: gefyra-wireguard
+    port: 31820
+    protocol: UDP
+    targetPort: 51820
+  selector:
+    gefyra.dev/app: stowaway
+    gefyra.dev/provider: stowaway
+    gefyra.dev/role: connection
+  type: LoadBalancer
+``` 
+
+Please be aware that Gefyra comes with a few manually crafted presets for popular Kubernetes offering. Check out the next section to learn how you install Gefyra using an available installation preset.
+
+
+
+## Presets
+To make it as convenient as possible, Gefyra offers presets for widely used Kubernetes offerings, such as Google's GKE or
+Amazon EKS.
+
+Please check available presets with: 
+```bash
+> gefyra install --help | grep preset
+
+  --preset TEXT               Set configs from a preset (available: aws,gke)
+```
+
+Currently, it's only *aws* and *gke*. If you want to add another preset for another popular Kubernetes provider, please consider [opening a ticket on GitHub](https://github.com/gefyrahq/gefyra/issues/new?assignees=&labels=enhancement&projects=&template=feature-request.yaml) for it.
+
+**Example:** If you install Gefyra to an EKS cluster, you only have to set the preset 
+`gefyra install --preset aws | kubectl apply -f -`, and it will automatically create the *Network Load Balancer* via the required annotations on the Kubernetes service:
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  annotations:
+    # see these annotations
+    service.beta.kubernetes.io/aws-load-balancer-nlb-target-type: ip
+    service.beta.kubernetes.io/aws-load-balancer-scheme: internet-facing
+    service.beta.kubernetes.io/aws-load-balancer-type: nlb
+  labels:
+    gefyra.dev/app: stowaway
+    gefyra.dev/provider: stowaway
+    gefyra.dev/role: connection
+  name: gefyra-stowaway-wireguard
+  namespace: gefyra
+spec:
+  ports:
+  - name: gefyra-wireguard
+    port: 31820
+    protocol: UDP
+    targetPort: 51820
+  selector:
+    gefyra.dev/app: stowaway
+    gefyra.dev/provider: stowaway
+    gefyra.dev/role: connection
+  type: LoadBalancer
+```
+
+
+
+
+
+
+
+
+
+
+

gefyra/versioned_docs/version-2.0.0/shared-environments/remote-k8s/_category_.json

@@ -1,4 +1,4 @@
 {
   "label": "Remote Kubernetes Clusters",
-  "position": 1
+  "position": 10
 }

gefyra/versioned_docs/version-2.0.0/technical-details/_category_.json

@@ -1,4 +1,4 @@
 {
-  "label": "How does Gefyra work?",
+  "label": "How Does Gefyra Work?",
   "position": 6
 }

gefyra/versioned_docs/version-2.0.0/v1_vs_v2.md

@@ -1,5 +1,5 @@
 ---
-title: What changed in v2?
+title: What Changed in Gefyra 2?
 sidebar_position: 9
 ---