Cookbooks

Cookbook: Data residency routing

Applies to
Gatewayruntime for API, AI, and MCP gateways
Hosting
Managed EdgeManaged DedicatedSelf-Hosted

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 does this with the same public routing primitive as Dynamic model routing: 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.

EU region
US region
vertex-eu (europe-west4)
vertex-us (us-central1)
Your app
AI Gateway (data-residency policy)

Create a provider for each region

Add one provider configuration per region on Settings → AI Providers, 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:

ProviderRegion settingRequests go to
Vertex AILocation, such as europe-west4https://<location>-aiplatform.googleapis.com
Bedrock RuntimeAWS Region, such as eu-central-1https://bedrock-runtime.<region>.amazonaws.com
Bedrock MantleAWS Region, such as eu-central-1https://bedrock-mantle.<region>.api.aws
Azure AIAzure Resource Name and host familyhttps://<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.
  • On Azure AI, create the resource and its deployments in the region you need.

The policy

TypeScriptmodules/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:

JSONconfig/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:

JSONCode
{ "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.

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:

TerminalCode
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:

RequestResponse
No header and no defaultRegion400
No model in the body400
A region with no provider in the options403
A model that the region's provider doesn't list as active403

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 hosting, which runs your gateway in the cloud provider and regions you choose, or Self-Hosted, which runs it in your own infrastructure. See Hosting options to compare deployment models.

Next steps

Last modified on