Local Clusters
Gefyra on kind
Run Gefyra against a kind cluster — CNCF-conformant local Kubernetes with NodePort mappings for WireGuard connectivity.
Prerequisites
- Follow the installation for your preferred platform.
- Create a local Kubernetes cluster with
kindlike this: Create a filekind-config.yaml:
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
extraPortMappings:
- containerPort: 31820
hostPort: 31820
protocol: udp
Run:
kind create cluster --config kind-config.yaml
Running Gefyra
1. Set up Gefyra with
gefyra up
2. 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 kind!</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
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.
3. Mount the workload and create a bridge to intercept traffic with your local container:
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 comes up under: http://hello.127.0.0.1.nip.io:8080/
4. List active bridges and mounts:
gefyra bridge list
gefyra mount list
5. 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
- Remove the locally running Kubernetes cluster with
kind delete cluster