Volume Snapshot¶
Table of contents
Overview¶
A volume snapshot is a point-in-time capture of a VM’s volume; memory and CPU state are not captured. Snapshots can be taken on root volumes and data volumes, and are arranged in a chain manner that the initial snapshot is usually a full snapshot containing all contents of a volume, and subsequent snapshots are delta snapshots only containing changes since the last snapshot. A volume can be restored to its old contents by reverting to a snapshot; images and volumes can be created from snapshots.
As volume snapshots only capture volumes’ states, users need to flush changes in memory to file system in VMs’ operating system before taking snapshots.
Snapshot Type¶
There are two ways to create volume snapshots; one is hypervisor based that snapshots are created by hypervisors from VMs’ volumes; another is storage based that snapshots are created by storage systems that store VMs’ volumes. In this ZStack version, only hypervisor based snapshot is supported.
Snapshot Tree¶
Volume snapshots are normally arranged as a chain like:
however, once a volume is reverted to a snapshot and takes a snapshot again, the snapshot chain will grow as a tree where every chain is a branch:
Current volume is always following the last snapshot; when a snapshot chain has too many delta snapshots, it may hurt the volume’s disk IO performance, so ZStack sets max length of a snapshot chain to 16 by default; a new snapshot chain will be created after taking 16 snapshots.
The max length of a snapshot chain can be configured by incrementalSnapshot.maxNum.
Delete Snapshot¶
When deleting a snapshot, if it’s not a leaf that is the last one in a snapshot chain, all it’s descendants will be deleted as well. For example:
after deleting Snapshot1, the Snapshot2, Snapshot3, Snapshot1.1, and Snapshot1.2 will deleted too, and the snapshot chain turns to be:
Note
When deleting a volume, all snapshots taken from this volume will be deleted from primary storage.
Volume Snapshot Tree Inventory¶
Properties¶
Name | Description | Optional | Choices | Since |
---|---|---|---|---|
uuid | see Resource Properties | 0.6 | ||
volumeUuid | the uuid of volume the snapshot tree is created | 0.6 | ||
current | see current |
|
0.6 | |
tree | a tree of SnapshotLeafInventory | 0.6 | ||
createDate | see Resource Properties | 0.6 | ||
lastOpDate | see Resource Properties | 0.6 |
Example¶
{
"createDate": "Dec 7, 2015 11:45:02 PM",
"current": true,
"lastOpDate": "Dec 7, 2015 11:45:02 PM",
"tree": {
"children": [
{
"children": [
{
"children": [],
"inventory": {
"backupStorageRefs": [],
"createDate": "Dec 7, 2015 11:45:16 PM",
"format": "qcow2",
"lastOpDate": "Dec 7, 2015 11:45:16 PM",
"latest": true,
"name": "sp3",
"parentUuid": "3a859e89a39645018772e4d92ca02a09",
"primaryStorageInstallPath": "/opt/zstack/nfsprimarystorage/prim-a82b75ee064a48708960f42b800bd910/rootVolumes/acct-36c27e8ff05c4780bf6d2fa65700f22e/vol-2ad40ef516c540eeb138b7da24105f2e/snapshots/3a859e89a39645018772e4d92ca02a09.qcow2",
"primaryStorageUuid": "a82b75ee064a48708960f42b800bd910",
"size": 197120,
"state": "Enabled",
"status": "Ready",
"treeUuid": "acca6784c70b47fda68de18e2f8380d1",
"type": "Hypervisor",
"uuid": "b4d673e29f724320bb283c6dc4a59225",
"volumeType": "Root",
"volumeUuid": "2ad40ef516c540eeb138b7da24105f2e"
},
"parentUuid": "3a859e89a39645018772e4d92ca02a09"
}
],
"inventory": {
"backupStorageRefs": [],
"createDate": "Dec 7, 2015 11:45:10 PM",
"format": "qcow2",
"lastOpDate": "Dec 7, 2015 11:45:10 PM",
"latest": false,
"name": "sp2",
"parentUuid": "b885d1e6549c49caab97322243827ca1",
"primaryStorageInstallPath": "/opt/zstack/nfsprimarystorage/prim-a82b75ee064a48708960f42b800bd910/rootVolumes/acct-36c27e8ff05c4780bf6d2fa65700f22e/vol-2ad40ef516c540eeb138b7da24105f2e/snapshots/b885d1e6549c49caab97322243827ca1.qcow2",
"primaryStorageUuid": "a82b75ee064a48708960f42b800bd910",
"size": 197120,
"state": "Enabled",
"status": "Ready",
"treeUuid": "acca6784c70b47fda68de18e2f8380d1",
"type": "Hypervisor",
"uuid": "3a859e89a39645018772e4d92ca02a09",
"volumeType": "Root",
"volumeUuid": "2ad40ef516c540eeb138b7da24105f2e"
},
"parentUuid": "b885d1e6549c49caab97322243827ca1"
}
],
"inventory": {
"backupStorageRefs": [],
"createDate": "Dec 7, 2015 11:45:02 PM",
"format": "qcow2",
"lastOpDate": "Dec 7, 2015 11:45:02 PM",
"latest": false,
"name": "sp1",
"primaryStorageInstallPath": "/opt/zstack/nfsprimarystorage/prim-a82b75ee064a48708960f42b800bd910/rootVolumes/acct-36c27e8ff05c4780bf6d2fa65700f22e/vol-2ad40ef516c540eeb138b7da24105f2e/2ad40ef516c540eeb138b7da24105f2e.qcow2",
"primaryStorageUuid": "a82b75ee064a48708960f42b800bd910",
"size": 4718592,
"state": "Enabled",
"status": "Ready",
"treeUuid": "acca6784c70b47fda68de18e2f8380d1",
"type": "Hypervisor",
"uuid": "b885d1e6549c49caab97322243827ca1",
"volumeType": "Root",
"volumeUuid": "2ad40ef516c540eeb138b7da24105f2e"
}
},
"uuid": "acca6784c70b47fda68de18e2f8380d1",
"volumeUuid": "2ad40ef516c540eeb138b7da24105f2e"
}
SnapshotLeafInventory¶
SnapshotLeafInventory is the leaf structure of snapshot tree; a snapshot tree always starts with a root SnapshotLeafInventory.
Properties¶
Name | Description | Optional | Choices | Since |
---|---|---|---|---|
inventory | the volume snapshot inventory, see volume snapshot inventory | 0.6 | ||
parentUuid | uuid of volume snapshot inventory of parent leaf; if null, this leaf is the root leaf | true | 0.6 | |
children | a list of SnapshotLeafInventory which are child leafs | 0.6 |
Volume Snapshot Inventory¶
Properties¶
Name | Description | Optional | Choices | Since |
---|---|---|---|---|
uuid | see Resource Properties | 0.6 | ||
name | see Resource Properties | 0.6 | ||
description | see Resource Properties | true | 0.6 | |
type | see type |
|
0.6 | |
volumeUuid | uuid of volume the snapshot is created | 0.6 | ||
treeUuid | the uuid of tree this snapshot belongs | 0.6 | ||
parentUuid | uuid of parent snapshot in chain | 0.6 | ||
primaryStorageUuid | uuid of primary storage this snapshot locates | true | 0.6 | |
primaryStorageInstallPath | the path of this snapshot on primary storage | true | 0.6 | |
volumeType | the type of volume this snapshot is created |
|
0.6 | |
size | the snapshot size in bytes | 0.6 | ||
state | snapshot state, see state |
|
0.6 | |
status | snapshot status, see status |
|
0.6 | |
backupStorageRefs | a list of VolumeSnapshotBackupStorageRefInventory | 0.6 | ||
createDate | see Resource Properties | 0.6 | ||
lastOpDate | see Resource Properties | 0.6 |
Example¶
{
"backupStorageRefs": [],
"createDate": "Dec 7, 2015 11:45:02 PM",
"format": "qcow2",
"lastOpDate": "Dec 7, 2015 11:45:02 PM",
"latest": false,
"name": "sp1",
"primaryStorageInstallPath": "/opt/zstack/nfsprimarystorage/prim-a82b75ee064a48708960f42b800bd910/rootVolumes/acct-36c27e8ff05c4780bf6d2fa65700f22e/vol-2ad40ef516c540eeb138b7da24105f2e/2ad40ef516c540eeb138b7da24105f2e.qcow2",
"primaryStorageUuid": "a82b75ee064a48708960f42b800bd910",
"size": 4718592,
"state": "Enabled",
"status": "Ready",
"treeUuid": "acca6784c70b47fda68de18e2f8380d1",
"type": "Hypervisor",
"uuid": "b885d1e6549c49caab97322243827ca1",
"volumeType": "Root",
"volumeUuid": "2ad40ef516c540eeb138b7da24105f2e"
}
State¶
Volume snapshots have two states:
Enabled
The state allows operations to be proceeded
Disabled
The state that forbids operations; snapshots in this state cannot be used to revert volumes and create templates/volumes; and cannot be backup.
Status¶
Volume snapshots have following status:
Creating
The snapshot is being created from a volume
Ready
The snapshot is ready for any operations
Deleting
The snapshot is being deleted
VolumeSnapshotBackupStorageRefInventory¶
VolumeSnapshotBackupStorageRefInventory encompasses information about a copy of a snapshot on a backup storage.
Properties¶
Name | Description | Optional | Choices | Since |
---|---|---|---|---|
volumeSnapshotUuid | snapshot uuid | 0.6 | ||
backupStorageUuid | backup storage uuid | 0.6 | ||
installPath | the install path of snapshot copy on backup storage | 0.6 |
Operations¶
Create Snapshot¶
Users can use CreateVolumeSnapshot to create a volume snapshot. For example:
CreateVolumeSnapshot name=sp1 volumeUuid=2ad40ef516c540eeb138b7da24105f2e
Parameters¶
Name | Description | Optional | Choices | Since |
---|---|---|---|---|
name | resource name, see Resource Properties | 0.6 | ||
resourceUuid | resource uuid, see Create Resources | true | 0.6 | |
description | resource description, see Resource Properties | true | 0.6 | |
volumeUuid | volume uuid the snapshot is going to create | 0.6 |
Delete Snapshot¶
Users can use DeleteVolumeSnapshot to delete a snapshot. For example:
DeleteVolumeSnapshot uuid=b885d1e6549c49caab97322243827ca1
Warning
All descendant snapshots will deleted as well. see delete snapshot
Parameters¶
Name | Description | Optional | Choices | Since |
---|---|---|---|---|
deleteMode | see Delete Resources | true |
|
0.6 |
uuid | snapshot uuid | 0.6 |
Revert Volume From Snapshot¶
Users can use RevertVolumeFromSnapshot to revert a volume to a snapshot; after reverting, the volume will have contents when the snapshot was created. For example:
RevertVolumeFromSnapshot uuid=b885d1e6549c49caab97322243827ca1
the volume is the one where the snapshot is created.
Parameters¶
Name | Description | Optional | Choices | Since |
---|---|---|---|---|
uuid | snapshot uuid | 0.6 |
Backup Snapshot¶
Users can use BackupVolumeSnapshot to backup a snapshot to a backup storage. For example:
BackupVolumeSnapshot uuid=b885d1e6549c49caab97322243827ca1 backupStorageUuid=a82b75ee064a48708960f42b800bd910
ancestor snapshots not backup on any backup storage will be backup as well.
Parameters¶
Name | Description | Optional | Choices | Since |
---|---|---|---|---|
uuid | snapshot uuid | 0.6 | ||
backupStorageUuid | backup storage uuid; if omitted, ZStack will find a proper one. | true | 0.6 |
Delete Snapshot Backup¶
Users can use DeleteVolumeSnapshotFromBackupStorage to delete a copy of snapshot from backup storage. For example:
DeleteVolumeSnapshotFromBackupStorage uuid=b885d1e6549c49caab97322243827ca1 backupStorageUuid=a82b75ee064a48708960f42b800bd910,b885d1e6549c49caab97322243827ca1
if the copy is the only copy of this snapshot on backup storage, all copies of descendant snapshots of this snapshot will be deleted as well;
Parameters¶
Name | Description | Optional | Choices | Since |
---|---|---|---|---|
deleteMode | see Delete Resources | true |
|
0.6 |
uuid | snapshot uuid | 0.6 | ||
backupStorageUuids | a list of uuid of backup storage from which to delete the snapshot’s copy | 0.6 |
Query Volume Snapshot¶
Users can use QueryVolumeSnapshot to query volume snapshots. For example:
QueryVolumeSnapshot primaryStorageUuid=6572ce44c3f6422d8063b0fb262cbc62
QueryVolumeSnapshot volume.vmInstance.uuid=bd1652b1e44144e6b9b5b286b82edb69
Nested And Expanded Fields¶
Field | Inventory | Description | Since |
---|---|---|---|
volume | volume inventory | the volume the volume snapshot is created | 0.6 |
tree | volume snapshot tree inventory | the parent volume snapshot tree | 0.6 |
primaryStorage | primary storage inventory | primary storage the volume snapshot locates | 0.6 |
backupStorageRef | VolumeSnapshotBackupStorageRefInventory | the backup storage reference | 0.6 |
backupStorage | backup storage inventory | backup storage that the volume snapshot locates | 0.6 |
Global Configurations¶
incrementalSnapshot.maxNum¶
Name | Category | Default Value | Choices |
---|---|---|---|
incrementalSnapshot.maxNum | volumeSnapshot | 16 | > 0 |
The max length of a snapshot chain.
delete.parallelismDegree¶
Name | Category | Default Value | Choices |
---|---|---|---|
delete.parallelismDegree | volumeSnapshot | 1 | > 0 |
The number of snapshots that can be deleted in parallel when deleting a snapshot or a snpashot tree.
backup.parallelismDegree¶
Name | Category | Default Value | Choices |
---|---|---|---|
backup.parallelismDegree | volumeSnapshot | 5 | > 0 |
The number of snapshots that can be backup in parallel when backup snapshots.
Tags¶
Users can create user tags on a volume snapshot with resourceType=VolumeSnapshotVO. For example:
CreateUserTag resourceType=VolumeSnapshotVO tag=firstSnapshot resourceUuid=fae9a6f43c8e4017b0e2a251d67d650d
and create user tags on a volume snapshot tree with resourceType=VolumeSnapshotTreeVO. For example:
CreateUserTag resourceType=VolumeSnapshotVO tag=devops-tree resourceUuid=d6c49e73927d40abbfcf13852dc18367