diff --git a/gefyra/versioned_docs/version-2.0.0/cli.md b/gefyra/versioned_docs/version-2.0.0/cli.md index aebf69d..424f40f 100644 --- a/gefyra/versioned_docs/version-2.0.0/cli.md +++ b/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 diff --git a/gefyra/versioned_docs/version-2.0.0/run_vs_bridge.md b/gefyra/versioned_docs/version-2.0.0/run_vs_bridge.md index a8172d2..cf029a8 100644 --- a/gefyra/versioned_docs/version-2.0.0/run_vs_bridge.md +++ b/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'; diff --git a/gefyra/versioned_docs/version-2.0.0/shared-environments/_category_.json b/gefyra/versioned_docs/version-2.0.0/shared-environments/_category_.json index d2e4961..d823cc3 100644 --- a/gefyra/versioned_docs/version-2.0.0/shared-environments/_category_.json +++ b/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 } \ No newline at end of file diff --git a/gefyra/versioned_docs/version-2.0.0/shared-environments/clients.md b/gefyra/versioned_docs/version-2.0.0/shared-environments/clients.md index 7f6a0e4..1b93f3e 100644 --- a/gefyra/versioned_docs/version-2.0.0/shared-environments/clients.md +++ b/gefyra/versioned_docs/version-2.0.0/shared-environments/clients.md @@ -1,5 +1,5 @@ --- -title: Gefyra Clients +title: What are Gefyra Clients? sidebar_position: 1 --- @@ -7,7 +7,7 @@ sidebar_position: 1 :::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. ::: diff --git a/gefyra/versioned_docs/version-2.0.0/shared-environments/installation.md b/gefyra/versioned_docs/version-2.0.0/shared-environments/installation.md new file mode 100644 index 0000000..73570fc --- /dev/null +++ b/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 +``` + + + + + + + + + + + diff --git a/gefyra/versioned_docs/version-2.0.0/shared-environments/remote-k8s/_category_.json b/gefyra/versioned_docs/version-2.0.0/shared-environments/remote-k8s/_category_.json index 9b7a8c4..4e2c99f 100644 --- a/gefyra/versioned_docs/version-2.0.0/shared-environments/remote-k8s/_category_.json +++ b/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 } \ No newline at end of file diff --git a/gefyra/versioned_docs/version-2.0.0/technical-details/_category_.json b/gefyra/versioned_docs/version-2.0.0/technical-details/_category_.json index ef6916e..1c36f77 100644 --- a/gefyra/versioned_docs/version-2.0.0/technical-details/_category_.json +++ b/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 } diff --git a/gefyra/versioned_docs/version-2.0.0/v1_vs_v2.md b/gefyra/versioned_docs/version-2.0.0/v1_vs_v2.md index 591c55f..07bdd54 100644 --- a/gefyra/versioned_docs/version-2.0.0/v1_vs_v2.md +++ b/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 ---