Local Clusters

Developing with Gefyra on Minikube

Step-by-step guide to running Gefyra on Minikube. Connect your local Docker containers and IDE directly into your local Minikube cluster.

minikube is the official Kubernetes project for running single-node Kubernetes clusters locally. Gefyra connects smoothly to Minikube using Docker or virtualized drivers.


Prerequisites


1. Start Your Minikube Cluster

Start Minikube using the Docker driver (recommended):

minikube start --driver=docker --cpus=2 --memory=4096

Verify your cluster is healthy:

kubectl get nodes

2. Initialize Gefyra with Minikube

Because Minikube runs inside its own Docker container or virtual machine, Gefyra's WireGuard client needs the correct IP address of the Minikube node.

Get your Minikube IP:

MINIKUBE_IP=$(minikube ip)
echo "Minikube IP: $MINIKUBE_IP"

Initialize Gefyra and point the WireGuard client to Minikube's NodePort endpoint:

gefyra up --endpoint $MINIKUBE_IP:31820

Gefyra will:

  1. Deploy the Gefyra Operator and Stowaway gateway into the gefyra namespace.
  2. Configure the local Cargo WireGuard sidecar.
  3. Establish the encrypted link to your Minikube cluster.

3. Deploy an Example Workload

Deploy an example Nginx deployment and service to Minikube:

kubectl create deployment hello-nginx --image=nginx:alpine --port=80
kubectl expose deployment hello-nginx --port=80 --target-port=80

Verify the pod is running:

kubectl get pods -l app=hello-nginx

4. Run a Local Container with Gefyra

Run a local container that will intercept traffic from the Minikube pod. For this demo, run a local Python HTTP server:

# Create a local response file
mkdir -p /tmp/local-nginx && echo "Hello from Local Minikube Bridge!" > /tmp/local-nginx/index.html

# Run the local container via Gefyra
gefyra run \
  -i python:3.12-alpine \
  -N local-hello \
  -v /tmp/local-nginx:/www \
  -c "python3 -m http.server 80 -d /www" \
  -d

5. Mount and Bridge the Minikube Pod to Local

Mount the deployment with Carrier2:

gefyra mount create --target deployment/hello-nginx/nginx --name hello-mount

Next, bridge incoming traffic destined for hello-nginx to your local container:

gefyra bridge create \
  --mount hello-mount \
  -p 80:80 \
  -t local-hello \
  --match-path-prefix /

Test the bridge from inside Minikube:

kubectl run test-curl --rm -it --restart=Never --image=curlimages/curl -- curl -s http://hello-nginx

Output:

Hello from Local Minikube Bridge!

Traffic hitting the in-cluster Nginx service is now served directly by your local Python container running on your machine!


6. Cleanup

To remove the bridge and unmount the workload:

gefyra bridge delete <bridge-id>
gefyra mount delete hello-mount

To disconnect Gefyra completely and unpatch all Minikube components:

gefyra down