# Cookbook: Data residency routing

> **Scope of this page**
>
> This page documents the Zuplo **gateway** runtime (API, AI, and MCP gateways), not the Developer Portal.
>
> It applies to every Zuplo hosting option: Managed Edge, Managed Dedicated, and Self-Hosted. See [Hosting options](https://zuplo.com/docs/articles/hosting-options).

When prompts and responses must stay in a geographic region, route each request
to a provider configuration that runs in that region, and refuse the request
when no such configuration serves the model it asks for. A custom
[chain policy](../custom-policies.mdx) does this with the same public routing
primitive as [Dynamic model routing](./dynamic-model-routing.mdx):
`AIGatewayModelRouting.set(context, routing)`.

This recipe gives each data region its own provider configuration, such as
`vertex-eu` pinned to `europe-west4` and `vertex-us` pinned to `us-central1`.
The policy reads the region for the request, picks that region's provider, and
answers `403` when the region has no provider or the provider doesn't offer the
requested model.

<Diagram height="h-72">
  <DiagramNode id="app">Your app</DiagramNode>
  <DiagramNode id="gateway" variant="zuplo">
    AI Gateway (data-residency policy)
  </DiagramNode>
  <DiagramGroup id="eu" label="EU region">
    <DiagramNode id="vertex-eu" variant="blue">
      vertex-eu (europe-west4)
    </DiagramNode>
  </DiagramGroup>
  <DiagramGroup id="us" label="US region">
    <DiagramNode id="vertex-us" variant="green">
      vertex-us (us-central1)
    </DiagramNode>
  </DiagramGroup>
  <DiagramEdge from="app" to="gateway" label="x-data-region: eu" />
  <DiagramEdge from="gateway" to="vertex-eu" label="eu" />
  <DiagramEdge from="gateway" to="vertex-us" label="us" />
</Diagram>

## Create a provider for each region

Add one provider configuration per region on
[**Settings → AI Providers**](https://portal.zuplo.com/+/account/project/ai/settings/data-models),
and enable the same models on each. The provider name you choose is the value
the policy maps each region to. Each regional provider type has a setting that
fixes where its requests go:

| Provider                                  | Region setting                          | Requests go to                                                           |
| ----------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------ |
| [Vertex AI](../vertex-ai.mdx)             | **Location**, such as `europe-west4`    | `https://<location>-aiplatform.googleapis.com`                           |
| [Bedrock Runtime](../bedrock-runtime.mdx) | **AWS Region**, such as `eu-central-1`  | `https://bedrock-runtime.<region>.amazonaws.com`                         |
| [Bedrock Mantle](../bedrock-mantle.mdx)   | **AWS Region**, such as `eu-central-1`  | `https://bedrock-mantle.<region>.api.aws`                                |
| [Azure AI](../azure-ai.mdx)               | **Azure Resource Name** and host family | `https://<resource>.<host family>`, in the Azure region of that resource |

For a provider that must stay in one region, choose a regional value rather than
a global one:

- On Vertex AI, enter a regional location such as `europe-west4`, not `global`.
- On Bedrock Runtime, enable models by their single-region model ID or by a
  geography-scoped inference profile such as `eu.`, not a `global.` profile. AWS
  lists which Regions each profile uses under
  [Supported Regions and models for inference profiles](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-support.html).
- On Azure AI, create the resource and its deployments in the region you need.

## The policy

```ts title="modules/data-residency.ts"
import {
  AIGatewayModelRouting,
  AIGatewayRouting,
  ConfigurationError,
  HttpProblems,
  ZuploContext,
  ZuploRequest,
} from "@zuplo/runtime";

interface DataResidencyOptions {
  // Each data region and the provider configuration that serves it.
  providers: Record<string, string>;
  // The region for requests that don't name one.
  defaultRegion?: string;
  // The header a caller sets to choose a region. Defaults to x-data-region.
  regionHeader?: string;
}

export default async function dataResidency(
  request: ZuploRequest,
  context: ZuploContext,
  options: DataResidencyOptions,
): Promise<ZuploRequest | Response> {
  // Only POST requests name a model to route.
  if (request.method !== "POST") {
    return request;
  }

  const header = options.regionHeader ?? "x-data-region";
  const region =
    request.headers.get(header)?.trim().toLowerCase() || options.defaultRegion;
  if (!region) {
    return HttpProblems.badRequest(request, context, {
      detail: `Set the ${header} header to choose a data region.`,
    });
  }

  const providerName = new Map(Object.entries(options.providers)).get(region);
  if (!providerName) {
    return HttpProblems.forbidden(request, context, {
      detail: `No provider serves the '${region}' data region.`,
    });
  }

  const body: unknown = await request
    .clone()
    .json()
    .catch(() => undefined);
  const model =
    typeof body === "object" && body !== null && "model" in body
      ? body.model
      : undefined;
  if (typeof model !== "string" || model === "") {
    return HttpProblems.badRequest(request, context, {
      detail: "Name a model in the request body.",
    });
  }

  // The region picks the provider, so the request names only the model.
  const target = `${providerName}/${model}`;
  const routing: AIGatewayRouting = new URL(request.url).pathname.endsWith(
    "/v1/embeddings",
  )
    ? { embeddings: target }
    : { completions: target };

  try {
    // Rejects a provider name that doesn't exist and a model that the
    // provider doesn't offer, so the request never leaves the region.
    await AIGatewayModelRouting.set(context, routing);
  } catch (error) {
    if (error instanceof ConfigurationError) {
      context.log.warn(error.message);
      return HttpProblems.forbidden(request, context, {
        detail: `Model '${model}' isn't available in the '${region}' data region.`,
      });
    }
    throw error;
  }
  return request;
}
```

`AIGatewayModelRouting.set()` validates the selection before it stores it. It
throws a `ConfigurationError` when the provider name doesn't exist or when a
built-in provider doesn't offer the model as an active model of that kind, and
the policy turns that into a `403`. For an Azure AI provider, the gateway checks
the deployment name when the request runs instead, and answers `400` for a
deployment the provider doesn't map, before it calls Azure. The gateway replaces
the `model` in the request body with the selected model before it calls the
provider.

## Declare and use it

Declare the module in `config/policies.json` and push. The declared options list
every region the gateway serves:

```json title="config/policies.json (one entry in the policies array)"
{
  "name": "data-residency",
  "policyType": "custom-code-inbound",
  "handler": {
    "export": "default",
    "module": "$import(./modules/data-residency)",
    "options": {
      "providers": {
        "eu": "vertex-eu",
        "us": "vertex-us"
      }
    }
  }
}
```

Then add `data-residency` to an app's chain on its **Policies** tab, in place of
Model Filtering. Make it the only policy in the chain that selects models: leave
out Model Override, Model Load Balancing, Smart Router, and Fallback Model, so
no later policy replaces the regional selection or adds a backup in another
region.

Policies that send prompts to another vendor's service, such as Akamai AI
Firewall, Comet Opik Tracing, and Galileo Tracing, send them wherever that
service runs. Add them to a residency-bound app only when the vendor's service
runs in the same region.

## Pin an app to one region

The header lets a caller choose among the regions in the options, which suits a
multi-region app that knows each end user's region. To hold an app to one region
regardless of what the caller sends, override the options on that app's chain
entry so they list only that region:

```json
{
  "providers": { "eu": "vertex-eu" },
  "defaultRegion": "eu"
}
```

An entry that overrides options replaces the declared options completely, so
this app has no `us` provider: a request that sends `x-data-region: us` gets a
`403`, and a request without the header goes to `vertex-eu`. See
[Per-app settings](../custom-policies.mdx#per-app-settings).

## Send a request

Name the model without a provider prefix, and choose the region with the header.
The URL is a stand-in for the app's API URL:

```bash
curl https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e/v1/chat/completions \
  -H "Authorization: Bearer YOUR_APP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-data-region: eu" \
  -d '{
    "model": "gemini-3.7-flash",
    "messages": [{"role": "user", "content": "Hello"}]
  }'
```

The gateway sends the request to `vertex-eu/gemini-3.7-flash`. The policy
answers these requests itself, before any provider call:

| Request                                                   | Response |
| --------------------------------------------------------- | -------- |
| No header and no `defaultRegion`                          | `400`    |
| No `model` in the body                                    | `400`    |
| A region with no provider in the options                  | `403`    |
| A model that the region's provider doesn't list as active | `403`    |

## Run the gateway in a region

The policy keeps provider traffic in a region. To also choose where the gateway
itself runs, use [Managed Dedicated](../../dedicated/overview.mdx) hosting,
which runs your gateway in the cloud provider and regions you choose, or
[Self-Hosted](../../self-hosted/overview.md), which runs it in your own
infrastructure. See [Hosting options](../../articles/hosting-options.mdx) to
compare deployment models.

## Next steps

- [Cookbook: Dynamic model routing](./dynamic-model-routing.mdx): pick the model
  per request from the live catalog
- [Custom Policies](../custom-policies.mdx): the full custom-policy quickstart
- [Managing Providers](../managing-providers.mdx): add and edit provider
  configurations
