Developer Workflows

Run vs. Bridge: Two Modes of Kubernetes Interception

Understand the difference between Gefyra's run and bridge commands. Learn when to use outbound-only cluster access vs. full inbound traffic 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

Dimensiongefyra run (Outbound Only)gefyra bridge (Inbound Interception)
Primary GoalTalk to in-cluster services from local codeReplace a remote pod with local code to handle incoming traffic
Traffic DirectionOutbound: Local ➔ Remote ClusterBidirectional: Remote Ingress ➔ Local Container ➔ Remote Services
Cluster Manifest ModificationZero. No cluster pods or deployments are patchedTemporary Patch. Injects Carrier2 proxy sidecar into target pod
Multi-Developer SupportUnlimited developers can run containers simultaneouslyMultiple developers cannot bridge the same container simultaneously
Typical Use CasesDatabase migrations, background workers, integration test runners, one-off scriptsWeb APIs, REST/GraphQL endpoints, microservices receiving ingress requests

Architectural Comparison

mermaid
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 migrate or 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. pytest or jest) 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