Create Linux application consistent disk snapshots

Stay organized with collections Save and categorize content based on your preferences.

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

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

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

1. To prepare the guest environment for application consistency, create custom shell 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 the guest-flush option enabled. The guest-flush option starts your pre and post snapshot scripts.

Before you begin

• Create a Linux VM.
• Update the guest environment.
• If you haven't already, then 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 by selecting one of the following options:
  

  Select the tab for how you plan to use the samples on this page:

  Console

  When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

  gcloud

  1. After installing the Google Cloud CLI, initialize it by running the following command:

     gcloudinit

     If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  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.

  After installing the Google Cloud CLI, initialize it by running the following command:

  gcloudinit

  If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  For more information, see Authenticate for using REST in the Google Cloud authentication documentation.

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:

• Compute Instance Admin (v1) (roles/compute.instanceAdmin.v1)
• To connect to a VM that can run as a service account: Service Account User (v1) (roles/iam.serviceAccountUser)

For more information about granting roles, see Manage 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 the Required permissions section:

You might also be able to get these permissions with custom roles or other predefined roles.

Limitations

Creating application consistent snapshots on Linux has the following limitations:

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

Create pre and post snapshot scripts

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

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

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

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

 #!/bin/bash sudo fsfreeze -f [example-disk-location] 

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

 #!/bin/bash sudo 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.

Referencing specific disks in your scripts

The first argument passed to your pre and post snapshot scripts is a list of disks for which you are creating snapshots. You can use this argument in your scripts for various checks. For example, if your VM has multiple disks attached but you only specified one disk in your snapshot request, you can check 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 as 1/0 while an additional disk attached to the VM might appear as 2/0.

Edit your guest environment configuration file

Configure your application consistent snapshot settings by updating 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 changes and exit the editor.

    [Snapshots] enabled = ENABLED timeout_in_seconds = TIMEOUT_SECONDS

   Replace the following:

   • ENABLED: Set to true to enable the application consistent snapshot feature. The default value is false.

   • TIMEOUT_SECONDS: The number of seconds the pre or post snapshot script can take to finish running before timing out. The integer value must be between 0 and 300. The default value is 60.

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

   $ sudo systemctl restart google-guest-agent.service 

Create a snapshot with guest-flush enabled

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

Create a snapshot schedule with guest-flush enabled

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

For example, after configuring your guest environment configuration file and creating custom scripts, the following command creates hourly application consistent snapshots:

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

To learn more, see About snapshot schedules for disks.

Troubleshooting

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

Review the logs

1. Go to the Logs Explorer page in the Google Cloud console:

   Go to Logs Explorer

2. Paste the following query in the Log query pane:

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

3. Run the query and investigate the logs:

   

Check configurations

• If no pre or post snapshot scripts are found on the instance to freeze the activity/IOPS on the file system, no snapshot will be created. Make sure you've followed the steps in Create pre and post snapshot scripts.

• If there is a script error or timeout, no snapshot is created. Review Preparing for consistent snapshots. Note that the maximum timeout period that you can configure in your settings is 300 seconds. Try repeating the entire process using the sample scripts.

• A disk must be attached to a VM to capture a snapshot of the disk with guest-flush enabled. To learn how to create a Linux VM and attach a disk, see Creating a VM.

What's next

• Restore a snapshot.
• Create schedules for disk snapshots.