Developing with Gefyra on Minikube
minikube is the official Kubernetes project for running single-node Kubernetes clusters locally. Gefyra connects smoothly to Minikube using Docker or virtualized drivers.
Prerequisites
- Minikube installed (
minikube version >= 1.28.0). - Docker or Podman installed and active.
- Gefyra CLI installed.
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:
- Deploy the Gefyra Operator and Stowaway gateway into the
gefyranamespace. - Configure the local Cargo WireGuard sidecar.
- 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