Local Clusters

Gefyra on Docker Desktop Kubernetes

Use Gefyra with Docker Desktop's built-in Kubernetes on macOS — including the Docker Desktop Extension and CLI workflow.

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

  1. Follow the installation for MacOS.
  2. Start the Kubernetes cluster that comes with Docker Desktop. This may take moment.

  1. Tell kubectl to use your docker-desktop cluster:
kubectl config use-context docker-desktop
  1. 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
  1. Now patch the nginx ingress controller service to make port 8080 available:
kubectl patch svc -n ingress-nginx ingress-nginx-controller -p '{"spec": {"ports": [{"appProtocol": "http", "name": "http", "port": 8080, "protocol": "TCP", "targetPort": "http"}]}}' --type merge
  1. 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/

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