Locational endpoints for ITAR compliance

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.

Note: Cloud Load Balancing uses global request endpoints when routing requests to Cloud Storage buckets. You cannot configure Cloud Load Balancing to use locational endpoints. Requests sent to Cloud Load Balancing are not guaranteed to meet ITAR compliance.

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 the us-central1-storage.googleapis.com endpoint, the virtual machine must also reside in US-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	Yes^1
objects delete	No	Yes^1
objects get	Yes	Yes^1
objects insert	Yes	Yes^1
objects list	No	Yes^1
objects patch	No	Yes^1
objects copy	Yes	Yes^4
objects rewrite	Yes	Yes^4
buckets insert	No	Yes^2
buckets delete	No	Yes^3
buckets get	No	Yes^2
buckets patch	No	Yes^2
buckets update	No	Yes^2
buckets getIamPolicy	No	Yes^2
buckets setIamPolicy	No	Yes^2
buckets testIamPermissions	No	Yes^2
buckets lockRetentionPolicy	No	Yes^2
buckets BucketAccessControls	No	Yes^2
buckets DefaultObjectAccessControls	No	Yes^2
buckets ObjectAccessControls	No	Yes^2
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

¹ 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.

² 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.

³ 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.

⁴ 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:

1. 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.

Note: Virtual hosted-style endpoints cannot be used to access domain-named buckets. Use either path-style endpoints or a redirect instead.

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.