Locational endpoints

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

You can use either a global or locational service endpoint to send requests to Bigtable. Locational 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 locational endpoints for Bigtable in a specific geographic region in support of your project's security and compliance needs.

Before you read this document, you should be familiar with Instances, clusters, and nodes and App profiles.

Key concepts include the following:

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

  • Global endpoint: A 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.

  • Locational endpoint A locational endpoint enforces locational restrictions, ensuring that data is stored and processed in a specified region.

You can use locational endpoints only with the Cloud Bigtable API (Data API). Locational endpoints are not supported for the Cloud Bigtable Admin API.

When to use locational endpoints

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

Use a locational endpoint if your data location must be restricted and controlled to comply with regulatory requirements.

Use the global endpoint if you don't have strict locational restriction requirements.

Considerations when using a locational endpoint

Consider the following factors when you use a locational endpoint.

Cluster locations

Before you can use a locational endpoint, you must create an instance with at least one cluster in the region where you want to isolate your data. Bigtable locational endpoints are available in all Bigtable locations.

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

If you attempt to use a locational endpoint to access a cluster in a different region, the request is rejected with a FAILED_PRECONDITION error with a message noting that no clusters are accessible using the specified cluster and endpoint. For example, a request sent to us-west1-bigtable.googleapis.com for clusters in us-central1 fails with FAILED_PRECONDITION. For more information on FAILED_PRECONDITION, see Bigtable status codes.

App profiles

After you set a locational endpoint, you must use an app profile that is 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), you receive the failed precondition error message There are no clusters accessible through this app profile and the REGION_NAME endpoint. For more information on cluster routing, see Routing policy.

If you use an app profile that is configured to route to any cluster in an instance for high availability (HA), and you also use a locational endpoint, the locational 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 us-central1-bigtable.googleapis.com locational 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

Locational endpoints don't affect or prevent replication. If you configure a locational endpoint in Region A, and then you add a cluster to your instance in Region B, your data is replicated to Region B just like it is if you use 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 the endpoint region, you can set an organization policy that uses location constraints. To learn more, see Restricting resource locations.

Availability

When you use locational 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 locational boundaries, which a locational endpoint prevents because it confines all requests to a single region. For more information on monthly uptime percentages, see the Bigtable service level agreement (SLA).

Locational endpoint semantics

The first segment of a Bigtable locational endpoint name is the Google Cloud region name. A locational endpoint follows the format REGION-bigtable.googleapis.com, where REGION is a 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 locational endpoint URL for the Iowa region is us-central1-bigtable.googleapis.com. For a list of available regions, see Bigtable locations.

Specify a locational endpoint

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

gcloud

To specify a locational endpoint and override the global endpoint using the gcloud CLI, run the following command:

gcloud config set api_endpoint_overrides/bigtable https://REGION-bigtable.googleapis.com/

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

For example, to configure the locational endpoint as us-central1, run the following command:

gcloud config set api_endpoint_overrides/bigtable https://us-central1-bigtable.googleapis.com/

cbt

To specify a locational 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://REGION-bigtable.googleapis.com/

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

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

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

Specify the global endpoint

gcloud

To reconfigure a locational endpoint to the global endpoint, run this command:

gcloud config unset api_endpoint_overrides/bigtable

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.

What's next