Local Clusters

Gefyra on kind

Run Gefyra against a kind cluster — CNCF-conformant local Kubernetes with NodePort mappings for WireGuard connectivity.

Prerequisites

  1. Follow the installation for your preferred platform.
  2. Create a local Kubernetes cluster with kind like this: Create a file kind-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

  1. Remove Gefyra's components from the cluster with
gefyra down
  1. Remove the locally running Kubernetes cluster with
kind delete cluster