Skip to main content

Geoproximity Routing

Route user traffic to the nearest cluster based on geographic location. Reduce latency, improve performance, and enable disaster recovery with multi-region deployments across AWS, Azure, and GCP.

What Is Geoproximity?​

Geoproximity routing directs users to the closest cluster geographically, minimizing network latency and improving application performance. When you deploy the same application to multiple regions, geoproximity ensures each user connects to their nearest deployment.

Business Value:

  • Lower latency: Users connect to the nearest cluster, reducing round-trip time by 50-80%
  • Global reach: Serve customers worldwide with consistent performance
  • Disaster recovery: Automatically failover to backup regions during outages
  • Compliance: Keep data in-region to meet regulatory requirements (GDPR, data residency)

How Geoproximity Works​

User in California              User in Germany
       ↓                              ↓
   DNS Query                      DNS Query
       ↓                              ↓
[Geographic Routing]           [Geographic Routing]
       ↓                              ↓
US-West Cluster               EU-Central Cluster
 (Low Latency)                 (Low Latency)

Routing Logic:

  1. User makes DNS request for app.mycompany.com
  2. DNS service determines user's geographic location (IP geolocation)
  3. Returns IP address of closest cluster
  4. User connects directly to nearest region

Example:

  • User in New York → Routes to us-east cluster
  • User in London → Routes to eu-west cluster
  • User in Tokyo → Routes to asia-pacific cluster

Use Cases​

1. Global SaaS Applications​

Deploy your application to multiple regions for worldwide customers.

Example: E-commerce platform with users in US, Europe, and Asia

  • US-East cluster serves North American customers
  • EU-West cluster serves European customers
  • AP-Southeast cluster serves Asian customers

Result: 60-80% lower latency for all users compared to single-region deployment.

2. Disaster Recovery & High Availability​

Automatically failover to backup regions during outages.

Example: Financial services application

  • Primary: US-East cluster
  • Backup: US-West cluster
  • Failover: Automatic routing to US-West if US-East is unhealthy

Result: Zero downtime during regional outages.

3. Data Residency & Compliance​

Keep data within geographic boundaries to meet regulatory requirements.

Example: Healthcare application (HIPAA, GDPR)

  • EU customers: Data stays in EU clusters (GDPR compliance)
  • US customers: Data stays in US clusters (HIPAA compliance)

Result: Automatic compliance with regional data laws.

4. Content Delivery​

Serve static assets and dynamic content from edge locations.

Example: Media streaming platform

  • US regions: Serve US content from CDN + US clusters
  • EU regions: Serve EU content from CDN + EU clusters

Result: Faster load times, better user experience.

Multi-Region Architecture​

Deployment Pattern​

                    [DNS Geoproximity Service]
                             ↓
        ┌────────────────────┼────────────────────┐
        ↓                    ↓                    ↓
  [US-West Cluster]    [EU-West Cluster]   [AP-Southeast Cluster]
        ↓                    ↓                    ↓
   Cabinet: prod        Cabinet: prod        Cabinet: prod
        ↓                    ↓                    ↓
   my-api:1.2.3        my-api:1.2.3         my-api:1.2.3

Key Principles:

  • Same cabinet name across all regions (prod, staging, etc.)
  • Same asset versions for consistency
  • Separate databases per region (or replicated databases)
  • Centralized configuration with region-specific overrides

Configuring Geoproximity with CLI​

Step 1: Create Clusters in Multiple Regions​

Create clusters in different geographic regions:

# US-West cluster
cod cluster create us-west \
  --provider aws \
  --region us-west-2 \
  --environment prod

# EU-West cluster
cod cluster create eu-west \
  --provider aws \
  --region eu-west-1 \
  --environment prod

# AP-Southeast cluster
cod cluster create ap-southeast \
  --provider aws \
  --region ap-southeast-1 \
  --environment prod

Expected Outcome:

  • Three clusters created in different regions
  • All attached to the same prod environment
  • Ready for multi-region deployment

Step 2: Deploy Application to All Regions​

Deploy the same cabinet configuration to each cluster:

# Deploy to US-West
cod asset deploy --cabinet prod --cluster us-west

# Deploy to EU-West
cod asset deploy --cabinet prod --cluster eu-west

# Deploy to AP-Southeast
cod asset deploy --cabinet prod --cluster ap-southeast

Key: Use same cabinet name (prod) and asset versions across all clusters.

Step 3: Configure Domain with Geoproximity Routing​

Configure geoproximity routing in the web UI at app.codiac.io:

  1. Navigate to your domain configuration
  2. Enable geoproximity routing
  3. Select target clusters (us-west, eu-west, ap-southeast)

Expected Outcome:

  • DNS configured with geoproximity routing
  • Users automatically routed to nearest cluster
  • Traffic distribution based on location

Viewing Geoproximity Configuration​

View cluster routing configuration in the web UI at app.codiac.io, or use kubectl:

cod domain view api.mycompany.com

Expected Output:

Domain: api.mycompany.com
Routing Policy: Geoproximity
Target Clusters:
  - us-west (Region: us-west-2, Health: ✓ Healthy)
  - eu-west (Region: eu-west-1, Health: ✓ Healthy)
  - ap-southeast (Region: ap-southeast-1, Health: ✓ Healthy)

Traffic Distribution (Last 24h):
  us-west: 45%
  eu-west: 35%
  ap-southeast: 20%

Health Checks & Failover​

Geoproximity routing includes automatic health checks:

# Configure health check endpoint
cod domain healthcheck api.mycompany.com \
  --path /health \
  --interval 30s \
  --timeout 10s \
  --failure-threshold 3

Failover Behavior:

  • If us-west cluster becomes unhealthy, US traffic routes to next-nearest cluster
  • Automatic failback when cluster recovers
  • No manual intervention required

Region-Specific Configuration​

Override configuration for specific regions using the web UI at app.codiac.io or CLI:

# Set EU-specific config (GDPR settings)
codiac config set
# Select cabinet scope → prod-eu → DATABASE_REGION → eu-central-1

# Set US-specific config
codiac config set
# Select cabinet scope → prod-us → DATABASE_REGION → us-west-2

Result:

  • Same application code
  • Region-specific database connections
  • Automatic data residency compliance

Routing Policies​

Codiac supports multiple routing policies for multi-region deployments:

PolicyDescriptionBest ForExample
GeoproximityRoute to nearest region based on user locationGlobal applications with worldwide usersSaaS platforms, content delivery
Latency-BasedRoute to cluster with lowest latency (measured dynamically)Performance-critical applicationsTrading platforms, gaming
WeightedDistribute traffic by percentage (e.g., 80% US, 20% EU)Gradual rollouts, A/B testingCanary deployments, phased migrations
FailoverPrimary/backup regions (active-passive)Disaster recoveryMission-critical systems

Choosing a Policy:

  • Most use cases → Geoproximity (automatic, works globally)
  • Performance-critical → Latency-Based (real-time optimization)
  • Controlled rollouts → Weighted (manual traffic split)
  • DR-focused → Failover (primary + backup)

Best Practices​

1. Use Same Cabinet Names Across Regions​

Good:

US-West: cabinet = "prod"
EU-West: cabinet = "prod"
AP-Southeast: cabinet = "prod"

Why: Simplifies deployment and configuration management.

2. Deploy Same Asset Versions​

Ensure consistency across regions:

# Deploy version 1.2.3 to all clusters
cod asset deploy --cabinet prod --version 1.2.3 --all-clusters

Why: Prevents version drift and inconsistent behavior.

3. Test Failover Regularly​

Simulate regional outages:

# Disable health checks for us-west to trigger failover
cod cluster stop us-west

# Verify traffic routes to eu-west or ap-southeast
cod domain view api.mycompany.com

# Re-enable us-west
cod cluster start us-west

Why: Ensure failover works before a real incident.

4. Monitor Regional Performance​

Track metrics per region:

  • Average response time
  • Error rate
  • Traffic volume
  • Health check success rate

Set alerts for:

  • Latency above 500ms
  • Error rate above 1%
  • Health check failures

5. Plan for Data Synchronization​

Multi-region deployments need data strategy:

Option A: Regional Databases

  • Each region has own database
  • User data stays in-region (compliance)
  • No cross-region latency

Option B: Global Database with Replication

  • Single source of truth
  • Replicated to all regions
  • Eventual consistency

Option C: Hybrid

  • User data regional
  • Shared data (products, content) replicated globally

Common Patterns​

Pattern 1: Active-Active Multi-Region​

All regions serve traffic simultaneously.

Users → DNS Geoproximity → Nearest Cluster → Regional Database

Use Case: Global SaaS, content delivery Pros: Best performance, high availability Cons: Complex data synchronization

Pattern 2: Active-Passive (Disaster Recovery)​

One primary region, backup regions on standby.

Users → Primary Cluster (US-East)
  ↓ (on failure)
Failover → Backup Cluster (US-West)

Use Case: Disaster recovery, HA for single-region apps Pros: Simpler data management Cons: Higher latency for failover traffic

Pattern 3: Regional Isolation​

Each region completely independent (no cross-region traffic).

US Users → US Cluster → US Database
EU Users → EU Cluster → EU Database

Use Case: Compliance (GDPR), data residency Pros: Full compliance, no data leakage Cons: Higher operational complexity

Troubleshooting​

Problem: Users routed to wrong region​

Possible Causes:

  1. IP geolocation inaccurate
  2. DNS cache not updated
  3. Routing policy misconfigured

Solutions:

# Check DNS propagation
dig api.mycompany.com

# Verify routing policy
cod domain view api.mycompany.com

# Force DNS cache clear
# (User-side: flush DNS cache on their machine)

Problem: High latency despite geoproximity​

Possible Causes:

  1. Nearest cluster unhealthy (failover to distant cluster)
  2. Database in different region than cluster
  3. Network routing issue

Solutions:

  • Check health status of all clusters
  • Ensure databases are co-located with clusters
  • Monitor cross-region network latency

Problem: Failover not working​

Possible Causes:

  1. Health checks not configured
  2. All clusters unhealthy
  3. DNS TTL too long

Solutions:

# Verify health checks configured
cod domain view api.mycompany.com

# Check cluster health
cod cluster list --environment prod

# Reduce DNS TTL to 60 seconds for faster failover
cod domain update api.mycompany.com --ttl 60

FAQ​

Q: How quickly does failover happen?

A: Depends on DNS TTL (time-to-live). With 60-second TTL, failover takes 1-2 minutes. Lower TTL = faster failover but more DNS queries.

Q: Can I use geoproximity with multiple cloud providers?

A: Yes, deploy clusters to AWS, Azure, and GCP. Geoproximity routes users to nearest cluster regardless of provider.

Q: How does geoproximity determine user location?

A: IP-based geolocation using MaxMind GeoIP or similar services. Accuracy: ~95% at country level, ~80% at city level.

Q: What happens if all clusters in a region fail?

A: Traffic automatically routes to next-nearest healthy region. Example: If all US clusters fail, US traffic routes to EU clusters.

Q: Does geoproximity increase costs?

A: Multi-region deployments cost more (multiple clusters, cross-region data transfer). Trade-off: better performance and availability vs. higher infrastructure costs.

Q: How do I test geoproximity routing?

A: Use VPN to simulate users in different regions, or use tools like curl --resolve with region-specific IPs.

Need help with multi-region deployment? Contact Support or visit codiac.io to schedule a consultation.