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.

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

  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.

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:

Known constraints

There is no support for mTLS endpoints.