Gefyra on Docker Desktop Kubernetes
Try out our Docker Desktop Extension!
Note: Gefyra works the same for different Kubernetes distributions. Docker Desktop doesn't come with an ingress installed which must be added to the cluster to get things working.
You can easily try Gefyra yourself following this small example.
Prerequisites
- Follow the installation for MacOS.
- Start the Kubernetes cluster that comes with Docker Desktop. This may take moment.

- Tell kubectl to use your docker-desktop cluster:
kubectl config use-context docker-desktop
- Install an ingress to enable routing for the cluster. For this guide we use the nginx ingress controller like this:
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.2.1/deploy/static/provider/cloud/deploy.yaml
- Now patch the nginx ingress controller service to make port
8080available:
kubectl patch svc -n ingress-nginx ingress-nginx-controller -p '{"spec": {"ports": [{"appProtocol": "http", "name": "http", "port": 8080, "protocol": "TCP", "targetPort": "http"}]}}' --type merge
- 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_dd.yaml
Check out this workload running under: http://hello.127.0.0.1.nip.io:8080/
- Set up Gefyra with the following command:
For Docker Desktop <4.16.x:
gefyra up
For Docker Desktop >=4.16.x:
gefyra up --host=kubernetes.docker.internal
Running Gefyra
1. Run a local container with Gefyra (Zero Image Build)
No image build or repository clone is required. Run an official 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 Docker Desktop!</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
- 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.
2. Mount the workload and create a bridge to intercept traffic with your local container
Mount the 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 comes up under: http://hello.127.0.0.1.nip.io:8080/
3. List active bridges and mounts:
gefyra bridge list
gefyra mount list
4. Remove the bridge and restore the cluster:
# Delete the bridge
gefyra bridge delete <bridge-id>
# Unmount the workload and restore original container image
gefyra mount delete mymount
Check out the initial response from: http://hello.127.0.0.1.nip.io:8080/
Cleaning up
Remove Gefyra's components from the cluster with
gefyra down