Gefyra Logo
Shared Environments

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 (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.

> 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.

If the default configuration is suitable for your environment, directly apply it with:

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.

Check your active cluster context with kubectl config current-context.

Default networking

Gefyra depends on a working Wireguard VPN 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.

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.

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

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:

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 service.beta.kubernetes.io/aws-load-balancer-scheme=internet-facing

will create the following service in your cluster:

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:

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 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:

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

Getting Started

This chapter contains guides on how to set up shared remote Kubernetes for Gefyra. These guides are usually for multiple client use cases.

Managing Gefyra Clients

Gefyra introduces the concept of Gefyra Clients. These are objects to manage and distribute access to the cluster.

Copyright © 2026