> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-Region Deployment

> Deploy KnoxCall across multiple geographic regions for low-latency access, high availability, and compliance requirements.

# Multi-Region Deployment

<Warning>
  **Planned Feature**: Multi-region deployment is an upcoming feature that is not yet available. The information below describes the planned functionality and is subject to change. If you are interested in multi-region support, please contact our sales team to be notified when it becomes available.
</Warning>

Deploy KnoxCall across multiple geographic regions to provide low-latency API access worldwide, meet data residency requirements, and ensure high availability.

## Why Multi-Region?

### Performance

Reduce latency by routing requests to the nearest region:

```text theme={"dark"}
User in Tokyo → Asia-Pacific Region (50ms)
vs.
User in Tokyo → US East Region (200ms)
```

**Result:** 75% faster response times

### Compliance

Meet data residency and sovereignty requirements:

* **GDPR**: EU data must stay in EU
* **CCPA**: California data preferences
* **HIPAA**: Healthcare data location requirements

### High Availability

If one region goes down, traffic automatically routes to another:

```text theme={"dark"}
US East: ❌ Down
    ↓
Automatic failover
    ↓
US West: ✅ Serving traffic
```

**Uptime:** 99.99% SLA with multi-region

## Planned Regions

The planned region model defines four regions:

<CardGroup cols={2}>
  <Card title="🇦🇺 New Zealand / Australia" icon="location-dot">
    **Sydney, Australia (`nz`)**

    * NZ + Australia data residency
    * Serves NZ, AU
  </Card>

  <Card title="🇺🇸 United States" icon="location-dot">
    **Oregon, United States (`us`)**

    * Americas + Asia coverage
    * Primary region
  </Card>

  <Card title="🇩🇪 Europe" icon="location-dot">
    **Frankfurt, Germany (`eu`)**

    * GDPR-aligned EU data residency
    * Serves UK + EU
  </Card>

  <Card title="🌐 Global" icon="globe">
    **`global`**

    * For tenants that opt out of regional pinning
    * Served from any region
  </Card>
</CardGroup>

## How It Works

### Automatic Routing

Requests are automatically routed to the optimal region:

```text theme={"dark"}
Client Location: London, UK
    ↓
DNS Resolution
    ↓
Nearest Region: EU West (Ireland)
    ↓
Request routed to EU West
    ↓
Low latency: ~20ms
```

### Data Synchronization

Your configuration is synchronized across all regions:

* **Routes**: Instantly synchronized
* **Secrets**: Replicated encrypted
* **Clients**: Available in all regions
* **Logs**: Aggregated centrally

### Region Selection

Three modes for region selection:

#### 1. Automatic (Recommended)

KnoxCall automatically routes to the nearest region:

```text theme={"dark"}
User → Closest Region
```

**Best for:** Most use cases

#### 2. Pinned Region

Pin a tenant to a specific region so its data is only served from that region. Region pinning is planned to be driven by the tenant's residency configuration (the `SERVER_REGION` of each regional deployment plus the tenant's assigned region), not a per-request header.

**Best for:** Data residency requirements

#### 3. Per-Route Region

Configure default region per route:

```text theme={"dark"}
Route: customer-data-api
Default Region: eu (GDPR compliance)

Route: global-api
Default Region: auto (nearest)
```

## Setting Up Multi-Region

### Step 1: Enable Multi-Region (Enterprise)

Multi-region is available on Enterprise plans:

1. Contact sales or support
2. Enable multi-region for your tenant
3. Select regions to deploy to

### Step 2: Configure Routes

For each route, choose regional strategy:

1. Navigate to **Routes** → Select route
2. Go to **Regional Configuration** tab
3. Select mode:

**Automatic Routing:**

```text theme={"dark"}
Region Selection: Automatic
Fallback Region: us
```

**Pinned Region:**

```text theme={"dark"}
Region Selection: Pinned
Primary Region: eu
```

**Multi-Region Active-Active:**

```text theme={"dark"}
Region Selection: Active-Active
Regions: us, eu, nz
Load Balancing: Geo-proximity
```

4. Save configuration

### Step 3: Test Regional Routing

Test from different locations by confirming requests resolve to the expected regional endpoint:

```bash theme={"dark"}
curl https://a1b2c3d4.acme.knoxcall.com/api/test \
  -H "x-knoxcall-route: my-route" \
  -v
```

A request from a US-based client is planned to resolve to the `us` (Oregon) deployment, while a request from an EU-based client resolves to the `eu` (Frankfurt) deployment, based on the tenant's residency configuration.

## Data Residency Configuration

For compliance, ensure data stays in specific regions:

### GDPR Compliance (EU)

```yaml theme={"dark"}
Route: eu-customer-data
Regions: eu
Data Residency: Enforce EU only
Failover: Within EU only
```

### US Data Residency

```yaml theme={"dark"}
Route: us-customer-data
Regions: us
Data Residency: Enforce US only
Failover: Within US only
```

### Multi-Regional with Restrictions

```yaml theme={"dark"}
Route: global-api
Regions: All regions
EU Traffic: Must use the eu region
US Traffic: Must use the us region
NZ/AU Traffic: Must use the nz region
```

## Failover & High Availability

### Automatic Failover

If a region becomes unhealthy:

```text theme={"dark"}
Primary: US East → ❌ Health check fails
    ↓
Traffic switches to: US West ✅
    ↓
User requests continue uninterrupted
    ↓
When US East recovers → Traffic returns
```

**Detection time:** \< 30 seconds
**Switchover time:** \< 5 seconds

### Health Checks

KnoxCall performs continuous health checks:

* **Frequency**: Every 10 seconds
* **Threshold**: 3 consecutive failures triggers failover
* **Checks**:
  * API endpoint responsiveness
  * Database connectivity
  * Latency \< 1000ms
  * Success rate > 95%

### Regional Status Page

Monitor regional health:

🟢 **US East**: Operational (99.99% uptime)
🟢 **US West**: Operational (99.98% uptime)
🟢 **EU West**: Operational (100% uptime)
🟢 **EU Central**: Operational (99.97% uptime)
🟢 **APAC**: Operational (99.99% uptime)

Visit: `https://status.knoxcall.com`

## Performance Benefits

### Latency Reduction

Average API latency by region:

| User Location | Single Region (US East) | Multi-Region | Improvement |
| ------------- | ----------------------- | ------------ | ----------- |
| New York      | 20ms                    | 20ms         | -           |
| Los Angeles   | 80ms                    | 25ms         | 69% faster  |
| London        | 120ms                   | 15ms         | 88% faster  |
| Singapore     | 250ms                   | 30ms         | 88% faster  |
| Sydney        | 200ms                   | 50ms         | 75% faster  |

### Global Coverage Map

```text theme={"dark"}
      🇺🇸 US West     🇺🇸 US East
         25ms            20ms
              ╲        ╱
                ╲    ╱
                 User
                ╱    ╲
              ╱        ╲
         15ms            30ms
      🇪🇺 EU West    🇸🇬 APAC
```

## Monitoring Multi-Region

### Regional Metrics Dashboard

Monitor performance per region:

* **Request volume per region**
* **Average latency per region**
* **Error rate per region**
* **Failover events**

### Alerts

Set up regional alerts:

```text theme={"dark"}
Alert: Region Degraded
Condition: Latency > 500ms for 5 minutes
Notification: Email, Slack, PagerDuty

Alert: Regional Failover
Condition: Traffic switched to backup region
Notification: Immediate SMS, Email
```

## Cost Considerations

### Data Transfer

Data transfer between regions incurs costs:

* **Within region**: Free
* **Cross-region**: \$0.02/GB

**Optimization:**

* Pin routes to single region when possible
* Use multi-region only for global applications

### Regional Pricing

Some regions have different pricing:

* **US Regions**: Standard pricing
* **EU Regions**: +10% due to GDPR compliance costs
* **APAC Regions**: +15% due to infrastructure costs

## Best Practices

### 1. Use Automatic Routing by Default

Unless you have specific compliance needs:

```yaml theme={"dark"}
Region Selection: Automatic
```

### 2. Pin Compliance-Sensitive Routes

For GDPR, HIPAA, or other compliance:

```yaml theme={"dark"}
Route: patient-data
Regions: us (HIPAA)
Data Residency: Enforce US only
```

### 3. Test Failover

Regularly test failover:

1. Simulate region failure
2. Verify traffic switches to backup
3. Ensure data consistency

### 4. Monitor Regional Performance

Set up dashboards per region:

* Latency trends
* Error rates
* Traffic distribution

### 5. Configure Appropriate Failover

**Critical routes:**

```yaml theme={"dark"}
Failover: Automatic, within 30 seconds
Backup regions: 2
```

**Non-critical routes:**

```yaml theme={"dark"}
Failover: Manual approval required
```

## Troubleshooting

### High latency despite multi-region

**Check:**

* DNS propagation (24-48 hours)
* Regional assignment correct
* Client using correct endpoint

### Requests going to wrong region

**Causes:**

* DNS caching
* VPN routing
* Pinned region configuration

**Fix:**

* Clear DNS cache
* Verify the tenant's assigned residency region
* Verify route configuration

### Failover not working

**Check:**

* Health checks enabled
* Backup region configured
* Failover policy active

## Next Steps

<CardGroup cols={2}>
  <Card title="Rate Limiting" icon="gauge" href="/advanced/rate-limiting">
    Protect your APIs
  </Card>

  <Card title="Alerts" icon="bell" href="/monitoring/alerts">
    Monitor regional health
  </Card>

  <Card title="Security" icon="shield" href="/security/securing-your-routes">
    Secure your routes
  </Card>

  <Card title="Analytics" icon="chart-line" href="/monitoring/analytics">
    Monitor regional performance
  </Card>
</CardGroup>

***

<CardGroup cols={2}>
  <Card title="📊 Statistics" icon="chart-line">
    * **Level**: advanced
    * **Time**: 15 minutes
  </Card>

  <Card title="🏷️ Tags" icon="tags">
    `multi-region`, `global`, `performance`, `compliance`, `high-availability`
  </Card>
</CardGroup>