Run vs. Bridge: Two Modes of Kubernetes Interception
Gefyra provides two fundamental operational modes for connecting local containers to your Kubernetes cluster: gefyra run and gefyra bridge.
Understanding when to use each command ensures clean workflows, avoids unnecessary pod modifications, and accelerates your development loop.
Comparison Matrix
| Dimension | gefyra run (Outbound Only) | gefyra bridge (Inbound Interception) |
|---|---|---|
| Primary Goal | Talk to in-cluster services from local code | Replace a remote pod with local code to handle incoming traffic |
| Traffic Direction | Outbound: Local ➔ Remote Cluster | Bidirectional: Remote Ingress ➔ Local Container ➔ Remote Services |
| Cluster Manifest Modification | Zero. No cluster pods or deployments are patched | Temporary Patch. Injects Carrier2 proxy sidecar into target pod |
| Multi-Developer Support | Unlimited developers can run containers simultaneously | Multiple developers cannot bridge the same container simultaneously |
| Typical Use Cases | Database migrations, background workers, integration test runners, one-off scripts | Web APIs, REST/GraphQL endpoints, microservices receiving ingress requests |
Architectural Comparison
flowchart TD
subgraph RunMode
direction LR
RunTitle[["gefyra run (Outbound)"]] ~~~ LocalContainer1["Local Container<br/>(Migration / Script)"]
LocalContainer1 -->|Queries Cluster DB| ClusterDB[("Cluster Postgres / CoreDNS")]
end
subgraph BridgeMode
direction LR
BridgeTitle[["gefyra bridge (Inbound)"]] ~~~ ClusterIngress["K8s Ingress / Gateway"]
ClusterIngress -->|Intercepts Traffic| LocalContainer2["Local Container<br/>(Your Code)"]
LocalContainer2 -->|Queries DB / Microservices| ClusterDB2[("Cluster Postgres / CoreDNS")]
end
classDef groupTitle fill:transparent,stroke:none;
classDef runBox stroke-width:2px;
classDef bridgeBox stroke-width:2px;
class RunTitle,BridgeTitle groupTitle;
class RunMode runBox;
class BridgeMode bridgeBox;Mode 1: gefyra run
The run command executes an arbitrary Docker or Podman container on your local machine and joins it directly to the cluster's network fabric.
When to use gefyra run:
- You need to run a database migration script (
python manage.py migrateor Flyway) against a private in-cluster database. - You are writing a background worker or Kafka/RabbitMQ consumer that only initiates outbound connections and does not receive incoming HTTP traffic.
- You want to run an integration test suite (e.g.
pytestorjest) from your local machine against live staging APIs.
Example: Running a Migration Against Staging
# Connect to the cluster
gefyra up
# Run a container that connects to the in-cluster PostgreSQL service
gefyra run \
-i my-django-app:latest \
-N migration-runner \
-e DATABASE_URL="postgresql://user:pass@postgres.staging.svc.cluster.local:5432/app_db" \
-v $(pwd):/app \
-w /app \
-c "python manage.py migrate"
No pods in your Kubernetes cluster are modified. The container simply runs locally with in-cluster DNS resolution and WireGuard routing.
Mode 2: gefyra bridge
The bridge command builds on top of run. It temporarily patches a target deployment or pod in your cluster, routes all incoming traffic to your local container, and returns the response back to the cluster.
When to use gefyra bridge:
- You are developing a web API or microservice that receives HTTP, gRPC, or WebSocket traffic from an Ingress controller or other pods.
- You want to set breakpoints in your IDE and inspect live incoming requests sent by frontend clients or upstream services.
- You want to test hot-reloaded changes live inside the staging environment before creating a pull request.
Example: Mounting and Bridging an In-Cluster Deployment
# 1. Start your local container with volume hot-reloading
gefyra run \
-i my-api:dev \
-N local-api \
-v $(pwd)/src:/app/src \
-c "uvicorn src.main:app --host 0.0.0.0 --port 8000 --reload" \
-d
# 2. Mount the staging deployment with Carrier2
gefyra mount create --target deployment/order-service/api --name order-mount
# 3. Bridge incoming cluster traffic to your local container
gefyra bridge create \
--mount order-mount \
-p 8000:8000 \
-t local-api \
--match-path-prefix /
Traffic arriving at the order-service deployment in Kubernetes is immediately forwarded to your local container on port 8000. When you stop development, delete the bridge and unmount the workload to cleanly restore the original pod:
# 1. Delete the active bridge
gefyra bridge delete <bridge-id>
# 2. Remove the mount and restore the original pod image
gefyra mount delete order-mount
IDE Debugging
Set live breakpoints in VS Code, PyCharm, and IntelliJ while stepping through requests intercepted directly from your Kubernetes staging cluster.
Database and DNS
Query remote cluster databases, Redis caches, and private microservices directly from your local development containers without port-forwarding or fragile mocks.