Global and regional service endpoints

This page describes Spanner global and regional service endpoints and how to use them.

A service endpoint is a base URL that specifies the network address of an API service. Spanner has both global and regional endpoints. You can use a global or regional service endpoint to make requests to Spanner.

Use the global endpoint if you don't have strict regional restriction requirements. Although the data is stored within the selected region, the data might be processed outside the region. The global endpoint for Spanner is spanner.googleapis.com. The default API endpoint accesses the global endpoint.

A regional endpoint enforces regional restrictions. Data is stored and processed within the same region. Regional endpoints for Spanner ensure and guarantee that the data stored and processed is restricted to the Spanner regional instance configuration where the database resides. Use regional endpoints if your data location must be restricted and controlled to comply with regulatory requirements. You can't use a regional endpoint to access resources belonging to a different instance configuration. You must first create an instance in the regional instance configuration before you can use the regional endpoint for that instance configuration.

A Spanner regional endpoint is available only in the Dammam me-central2 regional instance configuration. The underlying Spanner storage policies don't change regardless of which endpoint you use.

Security and compliance for regional endpoints

The benefit of using a Spanner regional endpoint over a global endpoint is that the regional endpoint provides regional isolation and protection to meet security, compliance, and regulatory requirements.

You can only use regional endpoints that belong to that regional instance configuration. For example, you can't use spanner.me-central2.rep.googleapis.com to serve requests if the instance you are accessing belongs to the us-central1 regional instance configuration. The request will be rejected with an InvalidRegionalRequest error.

Limitations of regional endpoints

You can't access a dual-region or multi-region instance configuration with a regional endpoint. You must use the global endpoint to access your dual-region or multi-region instance configurations. For example, if you have an instance in the multi-region instance configuration nam7, you can't use the regional endpoint spanner.us-central1.rep.googleapis.com to send requests to your instance in nam7.

If you have active requests that use regional endpoints on any of the instance resources, moving the instance impacts all requests using the regional endpoint because regional enforcement blocks access to cross region instances. Requests using a global endpoint are unaffected.

Regional endpoint naming convention

Spanner regional endpoint names follow the same naming convention as the regional instance configuration names. The regional endpoint follows the format spanner.<REGION>.rep.googleapis.com. For example, both the regional instance configuration name and regional endpoint name for Dammam are me-central2. Therefore, the regional endpoint is spanner.me-central2.rep.googleapis.com.

Only me-central2 is available as a possible regional endpoint.

Specify a regional endpoint

You can specify a Spanner regional endpoint using the Google Cloud CLI, REST, or RPC API requests.

gcloud

To specify a regional endpoint and override the global endpoint, run the following command:

gcloud config set api_endpoint_overrides/spanner https://spanner.REGION.rep.googleapis.com/

Provide the following value:

REGION
The region for which to set a regional endpoint. For example, me-central2.

For example, to configure the regional endpoint as me-central2, run the following command:

gcloud config set api_endpoint_overrides/spanner https://spanner.me-central2.rep.googleapis.com/

To reconfigure a regional endpoint to the global endpoint, run:

gcloud config unset api_endpoint_overrides/spanner

REST API

The default API endpoint accesses the global endpoint. To use a regional endpoint, configure the endpoint to the address of the regional endpoint using the following pattern:

https://spanner.REGION.rep.googleapis.com

For example, if you want to enforce data guarantees in the regional instance configuration Dammam (me-central2), use:

  https://spanner.me-central2.rep.googleapis.com

Refer to REST API for more information.

RPC API

The default API endpoint accesses the global endpoint. To use a regional endpoint, configure the endpoint to the address of the regional endpoint using the following pattern:

spanner.REGION.rep.googleapis.com

For example, if you want to enforce data guarantees in the regional instance configuration Dammam (me-central2), use:

spanner.me-central2.rep.googleapis.com

Refer to RPC API for more information.

What's next