This page describes how to use locational endpoints to access Cloud Storage. Locational endpoints allow you to run your workloads in a manner that's compliant with International Traffic in Arms Regulations (ITAR).
For information about restrictions when using Cloud Storage in a manner that's compliant with ITAR, see Restrictions and limitations for ITAR.
Overview
Locational endpoints are request endpoints that only allow requests to
proceed if the affected resource exists in the location specified by
the endpoint. For example, when you use the endpoint
https://us-central1-storage.googleapis.com
in a delete bucket request, the
request only proceeds if the bucket is located in US-CENTRAL1
.
Unlike global endpoints, where requests can be processed in a different location from where the resource resides, locational endpoints guarantee that your requests are processed only within the location specified by the endpoint, where the resource resides. When using locational endpoints, you can ensure that your at-rest and in-transit data stays within jurisdiction to meet data residency requirements.
Using locational endpoints guarantees that:
Your data stored in Cloud Storage does not leave the specified location.
Your data is TLS terminated in the region specified by the endpoint when transiting from on-premises to Google Cloud.
Your data remains in jurisdiction when transiting between Google Cloud services.
When using locational endpoints, you assume the following responsibilities:
In order to get data residency guarantees, requests made to a locational endpoint must originate from the same location that's specified by the endpoint. For example, if you're using a Compute Engine virtual machine to perform a request to a bucket residing in
US-CENTRAL1
via theus-central1-storage.googleapis.com
endpoint, the virtual machine must also reside inUS-CENTRAL1
.Locational endpoints must only be used when performing supported operations. Performing unsupported operations result in an error.
Locational endpoints support in-transit traffic between on-premises to Google Cloud via Interconnect or VPN, and in-transit traffic between Google Cloud services (for example, from BigQuery to Cloud Storage). Internet traffic is not supported.
Supported operations
The following table summarizes the operations that can and cannot be performed with locational endpoints. In general, intra-location operations can be performed with locational endpoints, while cross-location operations cannot.
If you attempt to perform an unsupported operation using a locational endpoint, Cloud Storage returns a 400 HTTP error code with the message: "This endpoint does not implement this operation. Please use the global endpoint."
Operation | Mutates object data | Supported for usage with locational endpoints |
---|---|---|
objects compose | Yes | Yes1 |
objects delete | No | Yes1 |
objects get | Yes | Yes1 |
objects insert | Yes | Yes1 |
objects list | No | Yes1 |
objects patch | No | Yes1 |
objects copy | Yes | Yes4 |
objects rewrite | Yes | Yes4 |
buckets insert | No | Yes2 |
buckets delete | No | Yes3 |
buckets get | No | Yes2 |
buckets patch | No | Yes2 |
buckets update | No | Yes2 |
buckets getIamPolicy | No | Yes2 |
buckets setIamPolicy | No | Yes2 |
buckets testIamPermissions | No | Yes2 |
buckets lockRetentionPolicy | No | Yes2 |
buckets BucketAccessControls | No | Yes2 |
buckets DefaultObjectAccessControls | No | Yes2 |
buckets ObjectAccessControls | No | Yes2 |
HMAC key operations | No | No |
Service account operations | No | No |
Pub/Sub notification operations | Varies by operation | No |
Object change notification operations | Varies by operation | No |
Batched operations | Varies by operation | No |
1 To perform this operation using locational endpoints, the bucket
containing the affected object must exist in the location specified by the
endpoint. For example: an object delete request to
us-central1-storage.googleapis.com
can only be used to delete objects in
buckets that reside in the US-CENTRAL1
region. If you try to delete an object
in a location that's not US-CENTRAL1
, the operation returns a NOT_FOUND
error.
2 To perform this operation using locational endpoints, the bucket
must exist in the location specified by the endpoint. For example: a bucket
create request to us-central1-storage.googleapis.com
can only be used to
create a bucket in the US-CENTRAL1
region. If you try to create the bucket in
a location that's not US-CENTRAL1
, the operation returns an INVALID_ARGUMENT
error.
3 To perform this operation using locational endpoints, the bucket
must exist in the location specified by the endpoint. For example: a bucket
delete request to us-central1-storage.googleapis.com
can only be used to delete a
bucket in the US-CENTRAL1
region. If you try to delete a bucket in a location
that's not US-CENTRAL1
, the operation returns a NOT_FOUND
error.
4 To perform this operation using locational endpoints, the source
and destination buckets must both exist in the location specified by the
endpoint. For example: you can use locational endpoints to copy an object from
one bucket to another if both buckets exist in the same location. However, you
cannot use locational endpoints to copy an object from one bucket to another if
the buckets exist in different locations. If the source or destination bucket
exists in a different location than the location specified by the endpoint, the
operation returns a NOT_FOUND
error.
Supported regions
Locational endpoints are supported for all US regions, the US
multi-region,
and the NAM4
predefined dual-region. For more information about what regions
can be specified, see Bucket locations.
Making requests
Console
See Restrictions and limitations for ITAR for information about how to perform operations using the Google Cloud console in a manner that's ITAR compliant.
Command line
To configure the Google Cloud CLI for use with locational endpoints:
Set the
api_endpoint_overrides/storage
property to the locational endpoint you want to use:gcloud config set api_endpoint_overrides/storage https://LOCATION-storage.googleapis.com/
Once this property is set, you can use gcloud CLI commands as you normally would.
Alternatively, you can use locational endpoints for individual commands by
setting the CLOUDSDK_API_ENDPOINT_OVERRIDES_STORAGE
environment variable
in each command. For example:
CLOUDSDK_API_ENDPOINT_OVERRIDES_STORAGE=https://LOCATION-storage.googleapis.com/ gcloud ls gs://my-bucket
Client libraries
Cloud Storage client libraries manage request endpoints automatically, but you can manually set locational endpoints. To learn how to set locational endpoints, see the client library code samples using request endpoints.
REST APIs
JSON API
When making requests to locational endpoints, use the following URIs:
For general JSON API requests, excluding object uploads, use the following endpoint:
https://LOCATION-storage.googleapis.com
Replace LOCATION with a supported bucket location. For example,
us-central1
.For JSON API object uploads, use the following endpoint:
https://LOCATION-storage.googleapis.com/upload/storage/v1/b/BUCKET_NAME/o
Replace:
LOCATION with a supported bucket location. For example,
us-central1
.BUCKET_NAME with the name of the bucket to which you want to upload an object. For example,
my-example-bucket
.
For JSON API object downloads, use the following endpoint:
https://LOCATION-storage.googleapis.com/download/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?alt=media
Replace:
LOCATION with a supported bucket location. For example,
us-central1
.BUCKET_NAME with the name of the bucket that contains the object you want to download. For example,
my-example-bucket
.OBJECT_NAME with the name of the object you want to download. For example,
waterfall.png
.
Note that the JSON API endpoints only support HTTPS requests.
XML API
When using the XML API to make requests to locational endpoints, you can use a virtual hosted style endpoint or a path-style endpoint:
Virtual hosted style endpoint:
https://BUCKET_NAME.LOCATION-storage.googleapis.com
Path-style endpoint:
https://LOCATION-storage.googleapis.com/BUCKET_NAME
For both endpoint types, replace:
LOCATION with a supported bucket location. For example,
us-central1
.BUCKET_NAME with a valid bucket name. For example,
my-example-bucket
.
The XML API endpoints support secure sockets layer (SSL) encryption, which means you can use either HTTP or HTTPS. Using HTTPS is recommended, especially if you authenticate to Cloud Storage using OAuth 2.0.
Properly format requests
To ensure that your requests are compatible across Cloud Storage tools:
Ensure that you properly encode special characters that appear in the object name or query string of a request URI.
Familiarize yourself with bucket naming and object naming considerations.
Known constraints
There is no support for mTLS endpoints.