Developer Workflows

Database Access & In-Cluster DNS Resolution

Query remote cluster databases, Redis caches, and private microservices directly from your local development containers without port-forwarding or fragile mocks.

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:

mermaid
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;
  1. DNS Interception: Any container launched with gefyra run uses the local Cargo container as its primary DNS resolver.
  2. Kubernetes DNS Forwarding: When your code requests postgres.staging.svc.cluster.local, Cargo forwards the query to the remote cluster's CoreDNS service.
  3. 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!