Set default storage location using snapshot settings

When you create snapshots, Google Cloud uses predefined default values for configuration options unless you explicitly provide different values. Snapshot settings are centralized configuration parameters on a project level that let you customize the default location where Google Cloud stores your snapshots. Using snapshot settings to define your own custom default removes the need for you to manually specify a location during each snapshot creation.

This document provides information about snapshot settings and how to use them to customize the default storage location for your project's snapshots.

Before you begin

If you haven't already, set up authentication. Authentication is the process by which your identity is verified for access to Google Cloud services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine as follows.

Select the tab for how you plan to use the samples on this page:
gcloud
1. Install the Google Cloud CLI, then initialize it by running the following command:
```
gcloud init
```
  Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
2. Set a default region and zone.
REST

To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.

Limitations

You can view and update the snapshot settings only by using the gcloud CLI or REST.
You can't customize the default storage location of instant snapshots. You can only do so for standard and archive snapshots.
Modifying the location policy in your project's snapshot settings only affects the snapshots that are created after that modification. Updating your project's snapshot settings does not change the location of any existing snapshots.
If you manually specify a location during snapshot creation, then Google Cloud overrides the snapshot settings and creates your snapshot in that newly specified location. However, the storage location policy in your snapshot settings remains unchanged.

How snapshot settings work

The storage location policy of a project's snapshot settings defines where Google Cloud automatically stores that project's snapshots. Google Cloud maintains a predefined value for this storage location policy until you update the snapshot settings and configure a new default. After you update the snapshot settings and set a new default storage location, Google Cloud uses this location to store every new snapshot created in that project.

You can update your snapshot settings to modify the storage location policy any number of times. However, modifying your project's snapshot settings only affects the locations of snapshots that are created after that modification. Updating your project's snapshot settings does not change the location of any existing snapshots.

To ensure that Google Cloud uses the storage location defined by your snapshot settings, don't manually specify a location during snapshot creation. If you manually specify a location during snapshot creation, then Google Cloud overrides the snapshot settings and creates your snapshot in that newly specified location. However, the storage location policy in your snapshot settings remains unchanged.

You can use snapshot settings to customize the default storage location of your standard and archive snapshots. You can't customize the default storage location of instant snapshots.

Storage location options

When you configure your project's snapshot settings and specify a new default storage location, you can either choose specific regions or use disk-based location settings. More specifically, you can choose one of the following location options for your storage location policy:

The nearest multi-region to the source disk
The same local region as the source disk
Specific regions of your choice

Google Cloud predefined storage location policy

Until you update your snapshot settings for the first time, Google Cloud maintains a predefined value for the storage location policy. This predefined policy provides the default storage location for snapshots until you configure your own default storage location by updating your project's snapshot settings. The predefined storage location policy is set to the multi-region that is geographically closest to the location of your source disk.

If your source disk is in a location that is part of a multi-region, then your snapshot settings storage location policy is set to that multi-region. For example, if your disk is in a location like us-central1, then the default storage location is the multi-region us.
For a location that is outside of a multi-region, the default storage location is the geographically closest multi-region outside of that region. For a location like australia-southeast1, the default location becomes the asia multi-region.

Pricing implications

You don't have to pay any extra amount to use snapshot settings for your projects. However, the location values that you specify using snapshot settings affect other operations, which may in turn affect those operational costs.

Set the default storage location for a project using snapshot settings

You can update your project's snapshot settings and set a new default storage location by using REST and the gcloud CLI.

If you don't set a storage location policy in your snapshot settings, then your snapshots are created using the Google Cloud predefined storage location policy.

Permissions required for this task

To perform this task, you must have the following permissions:

compute.snapshotSettings.update on the project

gcloud

To add the snapshot settings or update the existing snapshot settings for your project, use the gcloud compute snapshot-settings update command:

  gcloud compute snapshot-settings update \
      --project=PROJECT_ID \
      --storage-location-policy=STORAGE_LOCATION \
      --storage-location-names=REGION_NAME

Replace the following:

PROJECT_ID: The ID of the project.
STORAGE_LOCATION: The snapshot storage location policy for your project. The value can be one of the following:
- nearest-multi-region: Specifies the location policy as the closest Cloud Storage multi-region to the location of your disk.
- local-region: Specifies the location policy as the same Cloud Storage region where your disk is located.
- specific-locations: Specifies the location policy as a custom Cloud Storage region location of your choice. If you specify this option, you must also specify the location that you want by using the --storage-location-names flag.
REGION_NAME: Optional: If you include the --storage-location-policy flag with a value of specific-locations, then you must specify a Cloud Storage region. You can specify only one region. Set this value to the name of the region that you want to specify as your storage location policy.

Examples to set storage location policy using snapshot settings

Consider an example project my-project in us-central1 region.

To configure the storage location policy of your project's snapshot settings as the Cloud Storage multi-region closest to your disk, run the following command:

  gcloud compute snapshot-settings update \
      --project=my-project \
      --storage-location-policy=nearest-multi-region

To configure the storage location policy of your project's snapshot settings as the same Cloud Storage region as your disk, run the following command:

  gcloud compute snapshot-settings update \
      --project=my-project \
      --storage-location-policy=local-region

To configure as the storage location policy of your project's snapshot settings as a specific location of your choice (like us-central1), use the --storage-location-names flag and run the following command:

  gcloud compute snapshot-settings update \
      --project=my-project \
      --storage-location-policy=specific-locations \
      --storage-location-names=us-central1

REST

To add the snapshot settings or update existing the snapshot settings for your project, make a PATCH request to the snapshotSettings.update method:

  PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/snapshotSettings

  {
    "storageLocation": {
      "policy": "STORAGE_LOCATION",
      "locations": {
            "REGION_NAME": { "name": "REGION_NAME" }
      }
    }
  }

Replace the following:

PROJECT_ID: The ID of the project.
STORAGE_LOCATION: The snapshot storage location policy for your project. The value can be one of the following:
- NEAREST_MULTI_REGION: Specifies the location policy as the closest Cloud Storage multi-region to the location of your disk.
- LOCAL_REGION: Specifies the location policy as the same Cloud Storage region where your disk is located.
- SPECIFIC_LOCATIONS: Specifies the location policy as a custom Cloud Storage region location of your choice. If you specify this option, you must also specify the location that you want by using the locations parameter in your request.
REGION_NAME: Optional: If you include the policy parameter with a value of SPECIFIC_LOCATIONS, then you must specify a Cloud Storage region. You can specify only one region. Set this value to the name of the region that you want to specify as your storage location policy.

Examples to set storage location policy using snapshot settings

Consider an example project my-project in us-central1 region.

To configure the storage location policy of your project's snapshot settings as the Cloud Storage multi-region closest to your disk, make the following PATCH request:

    PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/snapshotSettings

    {
      "storageLocation": {
        "policy": "NEAREST_MULTI_REGION"
      }
    }

To configure the storage location policy of your project's snapshot settings as the same Cloud Storage region as your disk, make the following PATCH request:

    PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/snapshotSettings

    {
      "storageLocation": {
        "policy": "LOCAL_REGION"
      }
    }

To configure as the storage location policy of your project's snapshot settings as a specific location (like us-central1), make the following PATCH request:

    PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/snapshotSettings

    {
      "storageLocation": {
        "policy": "SPECIFIC_LOCATIONS",
        "locations": {
          "us-central1": { "name": "us-central1"}
        }
      }
    }

View the default storage location defined by a project's snapshot settings

You can view your project's snapshot settings by using the Compute Engine API and the gcloud CLI.

Permissions required for this task

To perform this task, you must have the following permissions:

compute.snapshotSettings.get on the project

gcloud

To view the snapshot settings for your project, use the gcloud compute snapshot-settings describe command:

  gcloud compute snapshot-settings describe \
      --project=PROJECT_ID

Replace PROJECT_ID with the ID of the project.

REST

To view the snapshot settings for your project, make a GET request to the snapshotSettings.get method:

  GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/snapshotSettings

Replace PROJECT_ID with the ID of the project.

What's next

Learn how to view, delete, and share disk snapshots.
Learn how to create scheduled snapshots for disks.
Learn how to create a disk image from your snapshot.