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
Your ECS instance runs one of the following operating systems:
Windows: Windows Server 2022, 2019, 2016, or 2012 R2.
Linux: CentOS 7.6 or later, Ubuntu 18.04 or later, and Alibaba Cloud Linux 2 or 3.
The disks of the 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.
Cloud Assistant Agent is pre-installed on the ECS instance. For information about how to install Cloud Assistant Agent, see Install Cloud Assistant Agent.
NoteBy default, Cloud Assistant Agent is pre-installed on instances that were created from public images after December 1, 2017.
A Resource Access Management (RAM) role is created for the application-consistent snapshot feature.
For more information, see Step 1 to Step 4 in Procedure.
Download and install the Go runtime environment.
For more information, see Download and install.
Download and install ECS SDK for Go.
For more information, see Get started with Alibaba Cloud Classic SDK for Go.
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 | The implementation methods of the application-consistent snapshot feature vary based on operating systems.
|
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 | The implementation methods of the application-consistent snapshot feature vary based on operating systems.
|
Step 1: Configure a RAM role for an ECS instance
Call the AttachInstanceRamRole operation to attach the AppSnapshotRoleName RAM role to an ECS instance.
Sample code of ECS SDK for Go:
package main
import (
"fmt"
"os"
"github.com/aliyun/alibaba-cloud-sdk-go/services/ecs"
)
func main() {
// Make sure that the ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables are configured in the code runtime environment.
// If the project code is leaked, the AccessKey pair may be leaked and security issues may occur on all resources of your account. The following sample code shows how to use environment variables to obtain an AccessKey pair and use the AccessKey pair to call API operations. We recommend that you use Security Token Service (STS) tokens, which provide higher security.
client, err := ecs.NewClientWithAccessKey(
"cn-hangzhou",
os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"),
os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_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.
Step 2: Call the RunCommand operation to create the file system-consistent snapshots for Linux instances
Linux instances
Call the RunCommand operation, which is 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"
"os"
"github.com/aliyun/alibaba-cloud-sdk-go/services/ecs"
)
func main() {
// Make sure that the ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables are configured in the code runtime environment.
// If the project code is leaked, the AccessKey pair may be leaked and security issues may occur on all resources of your account. The following sample code provides an example on how to use environment variables to obtain an AccessKey pair and use the AccessKey pair to call API operations. We recommend that you use STS tokens, which provide higher security.
client, err := ecs.NewClientWithAccessKey(
"cn-hangzhou", // Specify the region ID of the instance.
os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"),
os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
// Call the RunCommand operation to create file system-consistent snapshots for the instance.
request := ecs.CreateRunCommandRequest()
request.Scheme = "https"
request.Type = "RunShellScript"
// You can view the command used to create file system-consistent snapshots in the CommandContent value.
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 theapp-snapshot-plugin
Cloud Assistant plug-in.--params=
indicates the parameters of the plug-in. The following table describes the 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
false
NoteFrom 11:00 on October 12, 2023, canary release is performed by region to upgrade the instant access feature, and new snapshots of ESSDs at the performance levels 0, 1, 2, and 3 and ESSD AutoPL disks are instantly available after creation without the need for additional configurations. For more information, see Use 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 value: 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 the Step 1: Configure a RAM role for an ECS instance section of this topic.
PreScriptPath
String
No
The path of the application pre-freeze script (tmp/prescript.sh). The prescript.sh script must meet the following requirements:
Only the root user is granted the read, write, and execute permissions (chmod 700) on the script as the owner.
The script is customized based on your application.
NoteTo create application-consistent snapshots for Linux instances, 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 requirements:
Only the root user is granted the read, write, and execute permissions (chmod 700) on the script as the owner.
The script is customized based on your application.
NoteTo create application-consistent snapshots for Linux instances, 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.
Windows instances
Call the RunCommand operation, which is 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"
"os"
"github.com/aliyun/alibaba-cloud-sdk-go/services/ecs"
)
func main() {
// Make sure that the ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables are configured in the code runtime environment.
// If the project code is leaked, the AccessKey pair may be leaked and security issues may occur on all resources of your account. The following sample code provides an example on how to use environment variables to obtain an AccessKey pair and use the AccessKey pair to call API operations. We recommend that you use STS tokens, which provide higher security.
client, err := ecs.NewClientWithAccessKey(
"cn-hangzhou", // Specify the region ID of the instance.
os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"),
os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
request := ecs.CreateRunCommandRequest()
request.Scheme = "https"
request.Type = "RunBatScript"
// You can view the command used to create application-consistent snapshots in the CommandContent value.
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 theapp-snapshot-plugin-win
Cloud Assistant plug-in.--params=
indicates the parameters of the plug-in. The following table describes the 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
false
NoteFrom 11:00 on October 12, 2023, canary release is performed by region to upgrade the instant access feature, and new snapshots of ESSDs at the performance levels 0, 1, 2, and 3 and ESSD AutoPL disks are instantly available after creation without the need for additional configurations. For more information, see Use 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 value: 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 the Step 1: Configure a RAM role for an ECS instance section of this topic.
EnableWriters
Boolen
No
Specifies whether to create application-consistent snapshots. Valid values:
true
false
Default value: true.
A response similar to the following one is displayed. For more information about the parameters in the response, see RunCommand.
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"
"os"
"github.com/aliyun/alibaba-cloud-sdk-go/services/ecs"
)
func main() {
// Make sure that the ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables are configured in the code runtime environment.
// If the project code is leaked, the AccessKey pair may be leaked and security issues may occur on all resources of your account. The following sample code provides an example on how to use environment variables to obtain an AccessKey pair and use the AccessKey pair to call API operations. We recommend that you use STS tokens, which provide higher security.
client, err := ecs.NewClientWithAccessKey(
"cn-hangzhou", // Specify the region ID of the instance.
os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"),
os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
// Call the DescribeInvocationResults operation to check whether snapshots are created.
request := ecs.CreateDescribeInvocationResultsRequest()
request.Scheme = "https"
request.InvokeId = "t-hz01qsegaxi****" // The task ID of the command. You can obtain the task ID in the response in the previous step.
request.InstanceId = "i-bp17r83nppqf141v****" // The instance ID.
request.CommandId = "c-hz01qsegaxd****" // The command ID. You can obtain the command ID in the response in the previous step.
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.
ExitCode indicates the error code. A value of
0
indicates that the command was run successfully. A numeric value other than0
indicates that an error occurred. Troubleshoot the issue based on the error code. For more information, see the Error codes section of this topic.Output indicates the command output, which is Base64-encoded.
If the command was run successfully, the value 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:
|
2 | The type or number of the parameters that follow |
3 | One of the following errors may occur:
|
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. |
255 | An unknown error has occurred. |