Alibaba Cloud allows you to create application-consistent snapshots for Elastic Compute Service (ECS) instances by calling API operations or by using ECS SDKs. These methods of creating application-consistent snapshots are suitable for scenarios such as batch O&M and custom development. This topic describes how to use ECS SDK for Go to create application-consistent snapshots for Linux and Windows instances.

Prerequisites

  • The Elastic Compute Service (ECS) instance based on which you want to create application-consistent snapshots runs one of the following operating systems:
    • Windows: Windows Server 2019, Windows Server 2016, and Windows Server 2012 R2.
    • Linux: CentOS 7.6 or later, Ubuntu 18.04 or later, and Alibaba Cloud Linux 2.1903 LTS 64-bit.
  • The disks of the ECS instance are enhanced SSDs (ESSDs) and the file systems are ext3, ext4, XFS, or New Technology File System (NTFS). Network file systems or shared file systems are not supported.
  • The Cloud Assistant client is installed on the instance. For more information, see Install the Cloud Assistant client.
    Note By default, the Cloud Assistant client is pre-installed on ECS instances that were created from public images after December 1, 2017.

Background information

The following table describes the differences between file system-consistent snapshots and application-consistent snapshots.
Snapshot type Description Implementation
Application-consistent snapshot Application-consistent snapshots back up data stored in memory and database transactions in progress when the snapshots are created. This ensures consistency between application system data and database transactions. The application-consistent snapshots can be used for data rollbacks to prevent data corruption and data loss and to ensure that logs are not rolled back when databases start and that applications start in a consistent state.

Application-consistent snapshots are identified by the APPConsistent:True tag.

The implementation methods of the application-consistent snapshot feature vary based on operating systems.
  • For Windows operating systems, the feature is implemented by using Volume Shadow Copy Service (VSS).
  • For Linux operating systems, the feature is implemented by using custom shell scripts. You must write your own scripts based on your applications. When you use custom scripts, Alibaba Cloud does not take responsibility for application consistency issues.
File system-consistent snapshot If the application-consistent snapshot feature is enabled but relevant conditions are not met, file system-consistent snapshots are created.

File system-consistent snapshots synchronize the memory and disk information of file systems when the snapshots are created, and freeze write operations on file systems to ensure file system consistency. File system-consistent snapshots can be used to prevent operating systems from performing disk checks (chkdsk) and file system consistency checks (fsck).

File system-consistent snapshots are identified by the FsConsistent:True tag.

The implementation methods of the application-consistent snapshot feature vary based on operating systems.
  • For Windows operating systems, if no VSS writers are available, file system-consistent snapshots are created by default.
  • For Linux operating systems, if no application scripts are available, file system-consistent snapshots are created by default.

Preparations

Before you call an API operation to create file system- or application-consistent snapshots, make the following preparations.

  1. Create a Resource Access Management (RAM) role for the application-consistent snapshot feature.
    For more information, see Step 1 to Step 4 in Step 1: Configure a RAM role for the ECS instance.
  2. Download and install the Go runtime environment.
    For more information, see Download and install.
  3. Download and install ECS SDK for Go.
    For more information, see Get started.

After the preceding preparations are made, perform the procedures described in the following table based on the operating system of your instance.

Procedure for Linux instances Procedure for Windows instances
  1. Step 1: Configure a RAM role for the ECS instance
  2. Step 2: Call the RunCommand operation to create file system-consistent snapshots for Linux instances
  3. Step 3: Call the DescribeInvocationResults operation to check whether snapshots are created
  1. Step 1: Configure a RAM role for the ECS instance
  2. Step 2: Call the RunCommand operation to create application-consistent snapshots for Windows instances
  3. Step 3: Call the DescribeInvocationResults operation to check whether snapshots are created

Step 1: Configure a RAM role for the ECS instance

Call the AttachInstanceRamRole operation to attach the AppSnapshotRoleName RAM role to the ECS instance.

Sample code of ECS SDK for Go:
package main
import (
    "fmt"
    "github.com/aliyun/alibaba-cloud-sdk-go/services/ecs"
)

func main() {
    client, err := ecs.NewClientWithAccessKey(
        "cn-hangzhou",       //Specify the region ID of the instance.
        "<accessKeyId>",     //Specify your AccessKey ID.
        "<accessKeySecret>") //Specify your AccessKey secret.

    //Call the AttachInstanceRamRole operation to attach the specified RAM role to the instance.
    request := ecs.CreateAttachInstanceRamRoleRequest()
    request.Scheme = "https"

    request.RamRoleName = "AppSnapshotRoleName"          //Specify the name of the RAM role.
    request.InstanceIds = "[\"i-bp17r83nppqf141v****\"]" //Specify the ID of the instance.

    response, err := client.AttachInstanceRamRole(request)
    if err != nil {
        fmt.Print(err.Error())
    }

    fmt.Println(response.String())
}
A response similar to the following one is displayed. For more information about the parameters in the response, see AttachInstanceRamRole. Response

Step 2: Call the RunCommand operation to create file system-consistent snapshots for Linux instances

Call the RunCommand operation related to Cloud Assistant to create file system-consistent snapshots for one or more Linux instances.

Sample code of ECS SDK for Go:
package main

import (
    "fmt"
    "github.com/aliyun/alibaba-cloud-sdk-go/services/ecs"
)

func main() {
    client, err := ecs.NewClientWithAccessKey(
        "cn-hangzhou",    //Specify the region ID of the instance.
        "<accessKeyId>",  //Specify your AccessKey ID.
        "<accessKeySecret>") //Specify your AccessKey secret.

    //Call the RunCommand operation to create file system-consistent snapshots for the instance. 
    request := ecs.CreateRunCommandRequest()
    request.Scheme = "https"

    request.Type = "RunShellScript"
    //For information about the command used to create file system-consistent snapshots, see CommandContent. 
    request.CommandContent = "acs-plugin-manager --exec --plugin app-snapshot-plugin --params=-RamRoleName=\"AppSnapshotRoleName\",-InstantAccess=true,-EnableFsFreeze=true,-TimeoutInSeconds=30,-PreScriptPath=\"/tmp/prescript.sh\",-PostScriptPath=\"/tmp/postscript.sh\",-InstantAccessRentationDays=1,-ExcludeDiskId=\"\",-Name=\"LinuxApp1\""
    request.InstanceId = &[]string{"i-bp17r83nppqf141v****"} //Specify the ID of the instance.

    response, err := client.RunCommand(request)
    if err != nil {
        fmt.Print(err.Error())
    }
    fmt.Printf("response is %#v\n", response)
}
Components of the CommandContent value:
  • acs-plugin-manager --exec --plugin app-snapshot-plugin indicates the app-snapshot-plugin plug-in used to run Cloud Assistant commands.
  • --params= indicates the configuration parameters of the plug-in. The following table describes these parameters.
    Parameter Type Required Description
    ExcludeDiskId String No The disks to exclude from the snapshots.
    InstantAccess Boolean No Specifies whether to enable the instant access feature. Valid values:
    • true: enables the instant access feature.
    • false: disables the instant access feature.
    InstantAccessRentationDays Integer No The number of days for which the instant access feature remains enabled. The instant access feature is automatically disabled when the specified duration ends.

    Valid values: 1 to 65536. Default: 1.

    Name String Yes The name of the snapshot-consistent group.
    Description String No The description of the snapshot-consistent group.
    RamRoleName String Yes The RAM role attached to the instance. For more information, see Step 1: Configure a RAM role for the ECS instance.
    PreScriptPath String No The path of the application pre-freeze script (tmp/prescript.sh). The prescript.sh script must meet the following conditions:
    • Only the root user is granted read, write, and execute permissions (chmod 700) on the script as the owner.
    • You must customize the script based on your application.
    Note To create application-consistent snapshots for Linux instances, you must specify this parameter. If script configurations such as permissions, save path, or file name are invalid, file system-consistent snapshots are created.
    PostScriptPath String No The path of the application post-thaw script (/tmp/postscript.sh). The postscript.sh script must meet the following conditions:
    • Only the root user is granted read, write, and execute permissions (chmod 700) on the script as the owner.
    • You must customize the script based on your application.
    Note To create application-consistent snapshots for Linux instances, you must specify this parameter. If script configurations such as permissions, save path, or file name are invalid, file system-consistent snapshots are created.
    EnableFsFreeze Boolean No Specifies whether to enable Linux fsfreeze to put file systems into the read-only state before you create snapshots.

    Default value: True.

    TimeoutInSeconds Integer No The I/O freeze timeout period.

    Default value: 30. Unit: seconds.

    ScriptTimeoutInSeconds Integer No The timeout period for script execution.

    Default value: 1800. Unit: seconds.

A response similar to the following one is displayed. For more information about the parameters in the response, see RunCommand. linux

Step 2: Call the RunCommand operation to create application-consistent snapshots for Windows instances

Call the RunCommand operation related to Cloud Assistant to create application-consistent snapshots for one or more Windows instances.

Sample code of ECS SDK for Go:
package main

import (
    "fmt"
    "github.com/aliyun/alibaba-cloud-sdk-go/services/ecs"
)

func main() {
    client, err := ecs.NewClientWithAccessKey(
        "cn-hangzhou",       //Specify the region ID of the instance.
        "<accessKeyId>",     //Specify your AccessKey ID.
        "<accessKeySecret>") //Specify your AccessKey secret.

    request := ecs.CreateRunCommandRequest()
    request.Scheme = "https"

    request.Type = "RunBatScript"
    //For information about the command used to create application-consistent snapshots, see CommandContent. 
    request.CommandContent = "acs-plugin-manager --exec --plugin app-snapshot-plugin-win --params=-RamRoleName=\"AppSnapshotRoleName\",-InstantAccess=true,-EnableWriters=true,-Description=\"AppSnapshot\",-InstantAccessRentationDays=1,-ExcludeDiskId=\"\",-Name=\"APPSnapshot-1\""
    request.InstanceId = &[]string{"i-bp11vqwgh574****"} //Specify the ID of the instance.
    request.Timeout = "1800"

    response, err := client.RunCommand(request)
    if err != nil {
        fmt.Print(err.Error())
    }
    fmt.Printf("response is %#v\n", response)
}
Components of the CommandContent value:
  • acs-plugin-manager --exec --plugin app-snapshot-plugin-win indicates the app-snapshot-plugin-win plug-in used to run Cloud Assistant commands.
  • --params= indicates the configuration parameters of the plug-in. The following table describes these parameters.
    Parameter Type Required Description
    ExcludeDiskId String No The disks to exclude from the snapshots.
    InstantAccess Boolean No Specifies whether to enable the instant access feature. Valid values:
    • true: enables the instant access feature.
    • false: disables the instant access feature.
    InstantAccessRentationDays Integer No The number of days for which the instant access feature remains enabled. The instant access feature is automatically disabled when the specified duration ends.

    Valid values: 1 to 65536. Default: 1.

    Name String Yes The name of the snapshot-consistent group.
    Description String No The description of the snapshot-consistent group.
    RamRoleName String Yes The RAM role attached to the instance. For more information, see Step 1: Configure a RAM role for the ECS instance.
    EnableWriters Boolen No Specifies whether to create application-consistent snapshots. Valid values:
    • true: creates application-consistent snapshots.
    • false: creates file system-consistent snapshots.
    Default value: true.
A response similar to the following one is displayed. For more information about the parameters in the response, see RunCommand. Response for the Windows instance

Step 3: Call the DescribeInvocationResults operation to check whether snapshots are created

Call the DescribeInvocationResults operation to check whether the Cloud Assistant command is run.

Sample code of ECS SDK for Go:
package main

import (
    "fmt"
    "github.com/aliyun/alibaba-cloud-sdk-go/services/ecs"
)

func main() {
    client, err := ecs.NewClientWithAccessKey(
        "cn-hangzhou",    //Specify the region ID of the instance.
        "<accessKeyId>",  //Specify your AccessKey ID.
        "<accessKeySecret>") //Specify your AccessKey secret.

    //Call the DescribeInvocationResults operation to check whether snapshots are created.
    request := ecs.CreateDescribeInvocationResultsRequest()
    request.Scheme = "https"

    request.InvokeId = "t-hz01qsegaxi****"        //The execution ID of the command. You can obtain the execution ID in the response in Step 2. 
    request.InstanceId = "i-bp17r83nppqf141v****" //The instance ID.
    request.CommandId = "c-hz01qsegaxd****"       //The command ID. You can obtain the command ID in the response in Step 2. 

    response, err := client.DescribeInvocationResults(request)
    if err != nil {
        fmt.Print(err.Error())
    }
    fmt.Printf("response is %#v\n", response)
}
A response similar to the following one is displayed. For more information about the parameters in the response, see DescribeInvocationResults. Check the results
  • ExitCode indicates the error code. A value of 0 indicates that command was run in a proper manner. A numeric value other than 0 indicates that an error has occurred. Troubleshoot the error based on the returned error code. For more information, see Error codes.
  • Output indicates the command output, which is Base64-encoded.
    If the command is run in a proper manner, the content of Output is Base64-encoded and contains the ID of the created snapshot-consistent group, as shown in the following example.
    [snapshotgroup="ssg-bp170v57ca9j01jb****"][message="Finish whole Processes of Snapshot successfully"]

Error codes

After you perform the preceding operations to create an application-consistent snapshot, an error code (ExitCode) may be returned. If an application-consistent snapshot cannot be created, you can troubleshoot the error based on the returned error code.
Error code (ExitCode) Description
0 The application-consistent snapshot is created.
1 One or more specified conditions are not met. Examples:
  • The disk category is not supported.
  • The snapshot name is invalid.
  • The network connection fails.
  • No RAM role is attached to the instance.
  • The operating system of the instance is not supported.
2 The type or number of the parameters that follow --params is invalid.
3 One of the following errors may occur:
  • No ESSDs are attached to the instance.
  • The RAM role attached to the instance has no permissions to call snapshot-related API operations.
4 The snapshot-consistent group cannot be created.
5 The snapshot-consistent group is not in the expected state.
6 The request to create the snapshot-consistent group timed out.
7 A single disk snapshot in the snapshot-consistent group is not in the expected state.
8 Tags cannot be added to the snapshot.
9 The application pre-freeze script cannot be executed.
10 The application post-thaw script cannot be executed.
11 The I/O of the file systems cannot be frozen.
12 The I/O of the file systems cannot be thawed.
13 No RAM role is attached to the instance.
14 The number of snapshots exceeds the upper limit.
15 The snapshot is not in the expected state.
16 The snapshot cannot be created because the previous snapshot is being created and the instant access feature is disabled.
255 An unknown error has occurred.