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.
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:
| Provider | Region setting | Requests go to |
|---|---|---|
| Vertex AI | Location, such as europe-west4 | https://<location>-aiplatform.googleapis.com |
| Bedrock Runtime | AWS Region, such as eu-central-1 | https://bedrock-runtime.<region>.amazonaws.com |
| Bedrock Mantle | AWS Region, such as eu-central-1 | https://bedrock-mantle.<region>.api.aws |
| Azure AI | 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, notglobal. - On Bedrock Runtime, enable models by their single-region model ID or by a
geography-scoped inference profile such as
eu., not aglobal.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
modules/data-residency.ts
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:
config/policies.json (one entry in the policies array)
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:
Code
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:
Code
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 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
- Cookbook: Dynamic model routing: pick the model per request from the live catalog
- Custom Policies: the full custom-policy quickstart
- Managing Providers: add and edit provider configurations