Gefyra on k3d
Prerequisites
Hint there is a bug in Docker Desktop v4.17-v4.18 which causes gefyra up to fail with k3d clusters that run on that DD version.
Creating a local Kubernetes cluster

1. Create a local Kubernetes cluster with k3d by running:
k3d cluster create mycluster --agents 1 -p 8080:80@agent:0 -p 31820:31820/UDP@agent:0
This creates a Kubernetes cluster that binds port 8080 and 31820 to localhost. The kubectl context is immediately set to this cluster.
2. Apply some workload, for example from the testing directory of this repo:
kubectl apply -f https://raw.githubusercontent.com/gefyrahq/gefyra/main/testing/workloads/hello.yaml
Check out this workload running under: http://hello.127.0.0.1.nip.io:8080/
Running Gefyra
1. Set up Gefyra with your k3d cluster:
gefyra up
2. Run a local container with Gefyra (Zero Image Build)
No custom Dockerfile or image build is required. Run an official lightweight Python container from Docker Hub:
# 1. Create a local response file
mkdir -p /tmp/local-server
echo "<h1>Hello from Gefyra. Live local code served directly into k3d!</h1>" > /tmp/local-server/index.html
# 2. Run the local container in Gefyra
gefyra run \
-i python:3.12-alpine \
-N mypyserver \
-v /tmp/local-server:/app \
-c "python3 -m http.server 8000 -d /app" \
-d
Important: gefyra run joins your local container directly to the Kubernetes network fabric with CoreDNS and internal service access. Check out the docs for gefyra run.
3. Exec into the running container and verify cluster access:
docker exec -it mypyserver sh
wget -O- hello-nginx
exit
will print out the website of the cluster service hello-nginx from within the cluster. 🚀
4. Mount the workload and create a bridge to redirect cluster traffic to your local container:
First, mount the cluster deployment with Carrier2:
gefyra mount create --target deployment/hello-nginxdemo/hello-nginx --name mymount
Next, create the bridge connecting your local container to the mount:
gefyra bridge create --mount mymount -p 80:8000 -t mypyserver --match-path-prefix /
Check out the locally running server serving the cluster by refreshing the address from the service in Kubernetes.
It shows you a different message: Hello from Gefyra. It is .... Yes, that is really coming from your local container! 😎
5. List all active mounts and bridges:
You can inspect all active mounts and bridges with:
gefyra bridge list
gefyra mount list
6. Remove the bridge and restore the cluster to its original state:
# Delete the bridge
gefyra bridge delete <bridge-id>
# Unmount the workload and restore original container image
gefyra mount delete mymount
Check out the original response from the service. The cluster is now reset to its initial state again.
Cleaning up
Remove Gefyra's components from the cluster and your local Docker host with:
gefyra down
Deleting the locally running k3d Kubernetes cluster with
k3d cluster delete mycluster