Regional endpoints
This page describes Bigtable regional 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 regional service endpoint to send requests to Bigtable. Regional endpoints for Bigtable ensure and guarantee 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, 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 regional 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 Bigtable Data API is
bigtable.googleapis.com. The default Data API endpoint accesses the global endpoint.Regional endpoint A regional endpoint enforces regional restrictions, ensuring that data is stored and processed in a specified region.
You can use regional endpoints only with the Bigtable Data API. Regional endpoints are not supported for the 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.
Use a regional 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 regional restriction requirements.
Considerations when using a regional endpoint
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 all Bigtable locations.
You can only use a regional 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 regional
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 regional 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 regional endpoint, 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 us-central1-bigtable.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 do not 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 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 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, which a regional 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).
Regional endpoint semantics
The first segment of a Bigtable regional endpoint name is the
Google Cloud region name. A regional 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 regional endpoint URL for the Iowa
region is us-central1-bigtable.googleapis.com. For a list of available
regions, see Bigtable locations.
Specify a regional endpoint
You can specify a Bigtable regional endpoint using the
Google Cloud CLI, the cbt CLI, or the Bigtable client
libraries.
gcloud
To specify a regional 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
regional endpoint, such as us-central1 or europe-west1.
For example, to configure the regional 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 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://REGION-bigtable.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://us-central1-bigtable.googleapis.com/
Specify the global endpoint
gcloud
To reconfigure a regional 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.