Create Linux application consistent disk snapshots

You can create application consistent snapshots of disks attached toLinux virtual machine (VM) instances. In general, the quality of yourdisk snapshot depends on how well your applications can recover fromsnapshots that you create during heavy write workloads.Application consistent snapshots capture the state of application data atthe time of backup with all application transactions completed and all pendingwrites flushed to the disk.

To create snapshots that are application consistent, pause apps or operatingsystem processes that write data to the disk, flush the disk buffers,and sync the file system before you create the snapshot. Depending on yourapplication, these and other steps might be required to ensure that allapplication transactions are complete and captured in the backup.

To create an application consistent snapshot of your disks, use thefollowing process:

  1. To prepare the guest environment for application consistency, create customshell scripts to run before and after the snapshot is captured
  2. Configure snapshot settings on your virtual machine (VM) instance.
  3. Create a snapshot with theguest-flush option enabled. Theguest-flushoption starts your pre and post snapshot scripts.

Before you begin

Required roles and permissions

To get the permissions that you need to manage standard snapshots, ask your administrator to grant you the following IAM roles on the project:

For more information about granting roles, seeManage access to projects, folders, and organizations.

These predefined roles contain the permissions required to manage standard snapshots. To see the exact permissions that are required, expand theRequired permissions section:

Required permissions

The following permissions are required to manage standard snapshots:

  • To create a snapshot of a zonal disk:
    • compute.snapshots.create on the project
    • compute.disks.createSnapshot on the disk
  • To create a snapshot of a regional disk using the data on the disk:
    • compute.snapshots.create on the project
    • compute.instances.useReadOnly on the source VM
    • compute.disks.createSnapshot on the disk
  • To create a snapshot of a regional disk from a replica recovery checkpoint:
    • compute.snapshots.create on the project
    • compute.disks.createSnapshot on the disk
  • To create a snapshot schedule:compute.resourcePolicies.create on the project or organization
  • To attach a snapshot schedule to a disk:
    • compute.disks.addResourcePolicies on the disk
    • compute.resourcePolicies.use on the resource policy
  • To delete a snapshot:
    • compute.snapshots.delete on the snapshot
    • compute.snapshots.list on the project

You might also be able to get these permissions withcustom roles or otherpredefined roles.

Limitations

Creating application consistent snapshots on Linux has thefollowing limitations:

  • Application consistency is guaranteed only by the behavior of your custom preand post snapshot scripts, not by the snapshot operation itself.
  • When using theguest-flush option in your snapshot creation request, thesnapshot isn't created if the script returns an error or reaches thetimeout limit.

Create pre and post snapshot scripts

Before you proceed,update the guest environmentso that you are running the latest software on your Linux VM.

To facilitate application consistency, create pre and post snapshot shellscripts to run before and after the snapshot is captured. Use the pre and postscripts for operations such as:

  • Pause apps or operating system processes running on the VM that writesdata to the disk.
  • Flush the disk buffers. For example, MySQL has aFLUSH statement. Use whichever tool is available for your application.
  • Syncyour file system.

The following code example shows a pre snapshot script. Note the leading#! characters.

Caution: Runningfsfreeze -f blocks any running process that tries toaccess the file system, so use with caution if your application islatency-sensitive.
#!/bin/bashsudo fsfreeze -f [example-disk-location]

The following code example shows a post snapshot script. Note theleading#! characters.

#!/bin/bashsudo fsfreeze -u [example-disk-location]

You must save your scripts on your VM in the directory/etc/google/snapshots/. The full path of your pre script must be/etc/google/snapshots/pre.sh and the full path of your post script must be/etc/google/snapshots/post.sh.

Note: You must copy the scripts to every VM on which you want to enableLinux application consistent snapshots.

Referencing specific disks in your scripts

The first argument passed to your pre and post snapshot scripts is alist of disks for which you are creating snapshots. You can use this argumentin your scripts for various checks. For example, if your VM has multiple disksattached but you only specified one disk in your snapshot request, you cancheck which disk the snapshot is being created for.

The argument is formatted as follows:

  • SCSI-attached disks: a comma-separated list of<target/lun> pairs.
  • NVME-attached disks: a comma-separated list of<nvme:namespace> pairs.

For example, your SCSI-attached boot disk might appear as1/0 while anadditional disk attached to the VM might appear as2/0.

Edit your guest environment configuration file

Configure your application consistent snapshot settings byupdating a specific configuration file on your VM.

  1. Open or create your guest environment configuration file.

    edit /etc/default/instance_configs.cfg

  2. Add the following section to the configuration file, then save your changesand exit the editor.

    [Snapshots]enabled =ENABLEDtimeout_in_seconds =TIMEOUT_SECONDS

    Replace the following:

  3. Restart the Guest Agent to use the new configuration settings.

    $ sudo systemctl restart google-guest-agent.service

Create a snapshot withguest-flush enabled

Using the Google Cloud console, the Google Cloud CLI, or REST,create a snapshot with theguest-flush option enabled. This starts runningthe pre and post snapshot scripts before and after the snapshot is captured.

Console

  1. Go to theCreate a Snapshot page in the Google Cloud console.

    Go to the Create a Snapshot page
  2. Enter a snapshotName.

  3. Select aSnapshot type. The default is aSTANDARD snapshot, which is the best option for long-term back up and disaster recovery.

    ChooseArchive snapshot for more cost-efficient data retention.

  4. Optional: Enter aDescription of the snapshot.
  5. UnderSource disk, select the existing disk that you want to create a snapshot of.

  6. In theLocation section,choose your snapshot storage location.

    The predefined or customized default location defined in your snapshot settings is automatically selected. Optionally, you can override the snapshot settings and store your snapshots in a custom storage location by doing the following:

    1. Choose the type of storage location that you want for your snapshot.

      • ChooseMulti-regional for higher availability at a higher cost.
      • ChooseRegional snapshots for more control over the physical location of your data at a lower cost.
    2. In theSelect location field, select the specific region or multi-region that you want to use. To use the region or multi-region that is closest to your source disk, selectBased on disk's location.
  7. Check theEnable application consistent snapshot option.
  8. ClickCreate to create the snapshot.

gcloud

You can create your snapshot in the storage location policydefined by yoursnapshot settings orusing an alternative storage location of your choice. For more information, seeChoose your snapshot storage location.

  • To create a snapshot in the predefined or customized default location configured in your snapshot settings, use thegcloud compute snapshots create command.

    gcloud compute snapshots createSNAPSHOT_NAME \    --source-disk-zone=SOURCE_ZONE \    --source-disk=SOURCE_DISK_NAME \    --snapshot-type=SNAPSHOT_TYPE \    --guest-flush

  • Alternatively, to override the snapshot settings and create a snapshot in a custom storage location, include the--storage-location flag to indicate where to store your snapshot.

    gcloud compute snapshots createSNAPSHOT_NAME \    --source-disk-zone=SOURCE_ZONE \    --source-disk=SOURCE_DISK_NAME \    --snapshot-type=SNAPSHOT_TYPE \    --storage-location=STORAGE_LOCATION \    --guest-flush

  • (Preview) To create a regionally scoped snapshot in an allowed region, include the--region flag to indicate where to create your snapshot.

    gcloud beta compute snapshots createSNAPSHOT_NAME \    --region=SNAPSHOT_SCOPE_REGION    --source-disk=SOURCE_DISK_NAME \    --source-disk-zone=SOURCE_ZONE \    --snapshot-type=SNAPSHOT_TYPE

Replace the following:

  • SNAPSHOT_NAME: A name for the snapshot.
  • SOURCE_ZONE: The zone of the source disk.
  • SOURCE_DISK_NAME: The name of the disk volume from which you want to create a snapshot.
  • SNAPSHOT_TYPE: The snapshot type, eitherSTANDARD orARCHIVE. If a snapshot type is not specified, aSTANDARD snapshot is created.

  • STORAGE_LOCATION: Optional: For globally scoped snapshots, theCloud Storage multi-region or theCloud Storage region where you want to store your snapshot. You can specify only one storage location.

    Use the--storage-location parameter only when you want to override the predefined or customized default storage location configured in your snapshot settings.

  • SNAPSHOT_SCOPE_REGION: Optional: For regionally scoped snapshots, the region that the snapshot is scoped to. If you include this parameter, you can't use the--storage-location parameter. TheSTORAGE_LOCATION is automatically set to theSNAPSHOT_SCOPE_REGION.

Note: Google recommends using thegcloud compute snapshots create command instead of thegcloud compute disks snapshot command because it supports more features, such as creating snapshots in a project different from the source disk project.

REST

You can create your snapshot in the storage location policydefined by yoursnapshot settings orusing an alternative storage location of your choice. For more information, seeChoose your snapshot storage location.

  • To create a snapshot in the predefined or customized default location configured in your snapshot settings, make aPOST request to thesnapshots.insert method:

    POST https://compute.googleapis.com/compute/beta/projects/DESTINATION_PROJECT_ID/global/snapshots{  "name": "SNAPSHOT_NAME",  "sourceDisk": "projects/SOURCE_PROJECT_ID/zones/SOURCE_ZONE/disks/SOURCE_DISK_NAME",  "snapshotType": "SNAPSHOT_TYPE",  "guestFlush": true,}

  • Alternatively, to override the snapshot settings and create a snapshot in a custom storage location, make aPOST request to thesnapshots.insert method and include thestorageLocations property in your request:

    POST https://compute.googleapis.com/compute/beta/projects/DESTINATION_PROJECT_ID/global/snapshots{  "name": "SNAPSHOT_NAME",  "sourceDisk": "projects/SOURCE_PROJECT_ID/zones/SOURCE_ZONE/disks/SOURCE_DISK_NAME",  "snapshotType": "SNAPSHOT_TYPE",  "storageLocations": [      "STORAGE_LOCATION"  ],  "guestFlush": true,}

  • (Preview) To create a regionally scoped snapshot in an allowed region, make aPOST request to thesnapshots.insert method and define the creation region:

    POST https://compute.googleapis.com/compute/beta/projects/DESTINATION_PROJECT_ID/regions/SNAPSHOT_SCOPE_REGION/snapshots{    "name": "SNAPSHOT_NAME",    "sourceDisk": "projects/SOURCE_PROJECT_ID/zones/SOURCE_ZONE/disks/SOURCE_DISK_NAME",    "snapshotType": "SNAPSHOT_TYPE"}

Replace the following:

  • DESTINATION_PROJECT_ID: The ID of project in which you want to create the snapshot.
  • SNAPSHOT_NAME: A name for the snapshot.
  • SOURCE_PROJECT_ID: The ID of the source disk project.
  • SOURCE_ZONE: The zone of the source disk.
  • SOURCE_DISK_NAME: The name of the disk from which you want to create a snapshot.
  • SNAPSHOT_TYPE: The snapshot type, eitherSTANDARD orARCHIVE. If a snapshot type is not specified, aSTANDARD snapshot is created.

  • STORAGE_LOCATION: Optional: For globally scoped snapshots, theCloud Storage multi-region or theCloud Storage region where you want to store your snapshot. You can specify only one storage location.

    Use thestorageLocations parameter only when you want to override the predefined or customized default storage location configured in your snapshot settings.

  • SNAPSHOT_SCOPE_REGION: Optional: For regionally scoped snapshots, the region that the snapshot is scoped to. If you include this parameter, you can't use thestorageLocations parameter. TheSTORAGE_LOCATION is automatically set to theSNAPSHOT_SCOPE_REGION.

Note: Google recommends using thesnapshots.insert method instead of thedisks.createSnapshot method because it supports more features, such as creating snapshots in a project different from the source disk project.

Create a snapshot schedule withguest-flush enabled

Use scheduled snapshots to regularly and automatically backup your zonal andregional Persistent Disk and Google Cloud Hyperdisk. If you want to scheduleapplication consistent snapshots for your backup, use the--guest-flushoption when you create the snapshot schedule so that the pre and post snapshotscripts execute before and after each scheduled snapshot.

For example, afterconfiguring your guest environment configuration file andcreating custom scripts, the following command createshourly application consistent snapshots:

gcloud compute resource-policies create snapshot-scheduleSCHEDULE_NAME \  --description "MY HOURLY SNAPSHOT SCHEDULE" \  --start-time 22:00 \  --hourly-schedule 4 \  --guest-flush \  --max-retention-daysSNAPSHOT_RETENTION_AGE

To learn more, seeAbout snapshot schedules for disks.

Troubleshooting

Troubleshoot the snapshot schedule and creation process by reviewingreviewing logs and checking configurations.

Review the logs

  1. Go to theLogs Explorer page in theGoogle Cloud console:

    Go to Logs Explorer

  2. Paste the following query in theLog query pane:

    resource.type="gce_disk"jsonPayload.event_subtype="compute.disks.createSnapshot" ORprotoPayload.methodName="ScheduledSnapshots"

  3. Run the query and investigate the logs:

    snapshot creation log query.

Check configurations

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-07-11 UTC.