Regional and global endpoints

This page describes Bigtable endpoints, explains what you should consider before using them, and shows how to set an endpoint using the cbt CLI.

To send requests to Bigtable, you can use either a global or regional service endpoint. Regional endpoints for Bigtable ensure that an instance's data is stored and processed in the Bigtable region where the data resides. You might need to use regional endpoints for Bigtable in a specific geographic region in support of your project's security and compliance needs.

Before you read this document, familiarize yourself with Instances, clusters, and nodes and App profiles.

Key concepts include the following:

  • Service endpoint: a base URL that specifies the network address of an API service. Bigtable has both global and regional endpoints.

  • Global endpoint: lets Bigtable store and route the data in a Bigtable instance to any region that contains one of the instance's clusters. The global endpoint for the Cloud Bigtable API (Data API) is bigtable.googleapis.com. The default Data API endpoint accesses the global endpoint.

  • Regional endpoint: enforces regional restrictions, ensuring that Bigtable stores and processes data in a specified region. You can use regional endpoints only with the Cloud Bigtable API (Data API). Bigtable doesn't support regional endpoints for the Cloud Bigtable Admin API.

When to use regional endpoints

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

Regional endpoints, however, don't support Data Boost or the Cloud Bigtable Admin API. In addition, you can't configure Bigtable to achieve a monthly uptime percentage of >=99.999% when you use regional endpoints. For more information, see the Considerations to use a regional endpoint section of this document.

When to use global endpoints

Use a global endpoint in the following cases:

  • You don't have regional restriction requirements that require you to use a regional endpoint.
  • You need to use Data Boost.
  • You need to use the Cloud Bigtable Admin API.
  • You require a monthly uptime percentage of at least 99.999%.

Considerations to use a regional endpoint

If you use a regional endpoint, then consider the following factors:

Cluster locations

Before you can use a regional endpoint, you must create an instance with at least one cluster in the region where you want to isolate your data. Bigtable regional endpoints are available in select Bigtable regions. For a list of available regions, see Regional service endpoints.

You can only use a regional endpoint that belongs to the region where you want to isolate your data. For example, if a cluster is in the us-central1 region, then you can't use bigtable.us-west1.rep.googleapis.com to serve requests.

If you attempt to use a regional endpoint to access a cluster that's in a different region, Bigtable rejects the request with a FAILED_PRECONDITION error message stating that no clusters are accessible using the specified cluster and endpoint. For more information about this error message, see Bigtable status codes.

App profiles

After you set a regional endpoint, you must use an app profile that's configured to route requests to a cluster in the endpoint's region.

If you attempt to use an app profile configured to send writes only to a cluster (using single-cluster routing) or clusters in a different region from the endpoint (using multi-cluster routing), then you receive the FAILED_PRECONDITION error message. For more information about cluster routing, see Routing policy.

If you use an app profile that's configured to route to any cluster in an instance for high availability (HA), and you also use a regional endpoint, then the regional endpoint ensures that all requests are routed only to clusters in its region, even if the instance has clusters in other regions. Automatic failover is constrained, so requests are only served from clusters in the region of the endpoint.

Consider an example where you are sending requests using an app profile configured for multi-cluster routing to instance that has clusters in us-west1-a (Oregon), us-west1-b (Oregon), and us-central1-a (Iowa). If you send these requests to the bigtable.us-central1.rep.googleapis.com regional endpoint, then all requests are served by us-central1-a even if you don't reconfigure the app profile. Requests that can't be served by us-central1-a fail.

Replication

Regional endpoints don't affect or prevent replication. If you configure a regional endpoint in Region A, and then you add a cluster to your instance in Region B, your data is replicated to Region B just as if you used the global endpoint.

To avoid replicating data to another region, create clusters only in the intended region.

To prevent users in your organization from adding clusters outside of the endpoint region, you can set an organization policy that uses location constraints.

Availability

When you use regional endpoints, you can't configure Bigtable to achieve a monthly uptime percentage of >=99.999%. A monthly uptime of >=99.999% requires automatic failover of requests over regional boundaries. A regional endpoint prevents automatic failover because it confines all requests to a single region. For more information about monthly uptime percentages, see the Bigtable service level agreement (SLA).

Regional endpoint semantics

A regional endpoint follows the format bigtable.REGION.rep.googleapis.com, where REGION is a Google Cloud region name, such as northamerica-northeast2.

For example, if you want to isolate your data in the Iowa region, because the region name for Iowa is us-central1, the regional endpoint URL for the Iowa region is bigtable.us-central1.rep.googleapis.com.

Specify a regional endpoint

You can specify a Bigtable regional endpoint using the cbt CLI, or the Cloud Bigtable client libraries.

cbt

To specify a regional endpoint and override the global endpoint using the cbt CLI, you can use the --data-endpoint option in your request, or you can add the following to your ~/.cbtrc file. For additional information on creating a ~/.cbtrc file, see the cbt CLI reference.

data-endpoint = https://bigtable.REGION.rep.googleapis.com/

Replace REGION with the region where you want to set a regional endpoint, such as us-central1 or europe-west1.

For example, to configure the regional endpoint as us-central1 add this to the ~/.cbtrc file:

data-endpoint = https://bigtable.us-central1.rep.googleapis.com/

Specify the global endpoint

cbt

To specify the global sendpoint, send your request without using the --data-endpoint option. If you previously added a data-endpoint line to your ~/.cbtrc file, delete it.

Restrict global API endpoint usage

To help enforce the use of regional endpoints, use the constraints/gcp.restrictEndpointUsage organization policy constraint to block requests to the global API endpoint. For more information, see Restricting endpoint usage.

What's next