Database Access & In-Cluster DNS Resolution
One of the largest productivity drains for cloud engineers is the Mocking Trap: spending hours creating and maintaining Docker Compose replicas of production databases, queues, and caches. Over time, local schema definitions, seed data, and network topologies inevitably drift from production.
Gefyra eliminates local mocks by extending the Kubernetes cluster network directly into your local container runtime.
How Gefyra Resolves Cluster DNS & Routes Traffic
When you execute gefyra up, Gefyra configures a dedicated WireGuard tunnel and launches the Cargo container on your local machine:
flowchart TD
subgraph LocalWorkstation
LocalTitle[["Local Workstation"]] ~~~ App["Local Container<br/>(Django / Express / Go)"]
App -->|DNS Query| Cargo["Gefyra Cargo (Local DNS & Gateway)"]
end
Cargo <==>|"Encrypted WireGuard (UDP 31820)"| Stowaway["Gefyra Stowaway Gateway (Cluster)"]
subgraph Cluster
ClusterTitle[["Remote K8s Staging"]] ~~~ Stowaway
Stowaway --> CoreDNS["CoreDNS (10.96.0.10)"]
Stowaway --> RealDB[("Staging Database<br/>(Postgres / MySQL)")]
Stowaway --> Kafka["Kafka / RabbitMQ"]
Stowaway --> Upstream["Upstream Microservices"]
end
classDef groupTitle fill:transparent,stroke:none;
classDef gefyra stroke-width:2px;
classDef remote stroke-width:2px;
class LocalTitle,ClusterTitle groupTitle;
class LocalWorkstation gefyra;
class Cluster remote;- DNS Interception: Any container launched with
gefyra runuses the local Cargo container as its primary DNS resolver. - Kubernetes DNS Forwarding: When your code requests
postgres.staging.svc.cluster.local, Cargo forwards the query to the remote cluster's CoreDNS service. - Direct Routing: Returned in-cluster IP addresses (e.g.,
10.244.2.14) are routed directly through the encrypted WireGuard tunnel to the destination pod or service.
Connecting to In-Cluster Databases
Accessing a Staging PostgreSQL Database
Suppose your staging cluster contains a Postgres database accessible within Kubernetes as postgres.staging.svc.cluster.local:5432.
You can run your local application container and connect directly to it:
# 1. Connect Gefyra to the cluster
gefyra up
# 2. Run local container with database connection string pointing to in-cluster DNS
gefyra run \
-i python:3.12-slim \
-N local-api \
-e DATABASE_URL="postgresql://dbuser:secretpass@postgres.staging.svc.cluster.local:5432/orders_db" \
-v $(pwd):/app \
-w /app \
-c "python manage.py runserver 0.0.0.0:8000"
Your local application container connects directly to the real staging database—no kubectl port-forward, no SSH tunnels, and no mock containers required.
Using Redis, Kafka, and Cloud Managed Databases
In-Cluster Redis Cache
import redis
# Fully resolved via Gefyra's DNS forwarder
r = redis.Redis(host="redis-master.staging.svc.cluster.local", port=6379, db=0)
r.set("session:user_123", "active")
In-Cluster Kafka Topics
from kafka import KafkaConsumer
consumer = KafkaConsumer(
"order-events",
bootstrap_servers=["kafka-cluster-kafka-bootstrap.kafka.svc.cluster.local:9092"],
)
for msg in consumer:
print(f"Consumed event: {msg.value}")
AWS RDS / GCP Cloud SQL in Private VPCs
If your Kubernetes cluster resides inside an AWS VPC with private peering to an Amazon RDS Postgres instance (mydb.c7xyz.us-east-1.rds.amazonaws.com), Gefyra routes requests from your local container through the cluster's network overlay directly into the private AWS RDS instance without exposing it to the public internet.
Verifying DNS & Network Routing
To verify that your local environment can resolve cluster services, use Gefyra's run command with a diagnostic container:
# Test DNS lookup
gefyra run -i curlimages/curl -c "nslookup kubernetes.default.svc.cluster.local"
# Test TCP connectivity to an internal service
gefyra run -i curlimages/curl -c "curl -v http://auth-service.staging.svc.cluster.local:8080/health"
If the curl command outputs HTTP 200, your local workstation is successfully bridged into the Kubernetes network fabric!
Run vs. Bridge
Understand the difference between Gefyra's run and bridge commands. Learn when to use outbound-only cluster access vs. full inbound traffic interception.
Getting Started
Run a single shared Kubernetes staging cluster for your whole team — isolated Gefyra bridges per developer, lower cloud cost, zero traffic collisions.