Most of them are outdated, but provide historical design context.
They are not user documentation and should not be treated as such.
Documentation is available here.
Gluster Volume Snapshot
Summary
This document describes the design for the volume snapshot feature under Gluster. GlusterFS provides crash recoverability for the volumes through snapshot feature and console needs to provide a web based mechanism to achieve the same feature.
This feature allows the administrators to create, schedule, list, delete, start, stop and restore to a given snapshot. With this administrators can view all the available snapshots taken for a volume and in case of crash can opt to restore to a point in time view using the existing snapshots.
Owner
- Feature owner: Shubhendu Tripathi shtripat@redhat.com
- GUI Component owner:
- Engine Component owner: Shubhendu Tripathi shtripat@redhat.com
- VDSM Component owner:
Current Status
- Status: Inception
- Last updated date: Mon Oct 24 2014
Design
The snapshot feature is being designed to enable administrators to create and maintain individual volumes snapshots. It also provides mechanism to restore a volume to a point in time snapshot in a crash situation.
New Entities
GlusterVolumeSnapshots
This entity stores the snapshots created for gluster volumes. Different volumes can have snapshots with same names.
Column name | Type | Description |
---|---|---|
snapshot_id | UUID | Id of the new snapshot |
volume_id | UUID | Id of the reference volume for which the snapshot is taken |
snapshot_name | String | Name of the snapshot |
description | String | Description |
status | String | Current status of the snapshot |
- GlusterVolumeSnapshotStatus
- STARTED
- STOPPED
GlusterVolumeSnapshotConfig
This entity stores the details of a configuration parameter for volume related to snapshot feature. Volume specific values for the parameters would be maintained as part of this entity.
Column name | Type | Description |
---|---|---|
cluster_id | UUID | Id of the reference cluster to which volume belongs to |
volume_id | UUID | Id of the reference volume |
param_name | String | Name of the configuration parameter |
param_value | String | Value of the configuration parameter |
Entities changes
None
Sync Jobs
The Gluster volume snapshot details would be periodically fetched (frequency 5 minutes) and updated into engine using a sync job.
BLL commands
- CreateGlusterVolumeSnapshot - creates a volume snapshot
- RestoreGlusterVolumeSnapshot - restore a given volume to a snapshot
- RemoveGlusterVolumeSnapshot - removes the given snapshot
- UpdateGlusterVolumeSnapshotConfig - sets the configuration values for a given volume
- ActivateGlusterVolumeSnapshot - activates the snapshot for further activities
- DeactivateGlusterVolumeSnapshot - deactivates an already activated snapshot
Engine Queries
- GetGlusterVolumeSnapshotsByVolumeId - lists all the snapshot for a given volume
- GetGlusterVolumeSnapshotsCountByVolumeId - gets the no of snapshots for a given volume
- GetGlusterVolumeSnapshotConfig - gets the volume snapshot configurations for a given volume
- GetGlusterVolumeSnapshotByVolumeIdAndSnapshotId - lists snapshot for the given snapshot id and volume id
- GetGlusterVolumeSnapshotConfigDetailsByVolumeId - lists all the snapshot configuration details for the given volume id
- GetAllGlusterVolumeSnapshotStatus - lists all the snapshots with their status
- GetGlusterVolumeSnapshotStatusByVolumeId - gets the status of a snapshot for a specific volume
- GetGlusterVolumeSnapshotStatusBySnapshotId - gets the status of a specific snapshot
VDSM Verbs
VDSM verbs for Snapshot creation
- glusterSnapshotCreate - creates a volume snapshot
- Input
- volumeName
- snapName
- [description]
- [force]
- Output
- UUID of the created snapshot
- Input
VDSM verbs for restoring snaps
- glusterSnapshotRestore - restores the given volume to the given snapshot
- Input
- snapshotName
- Output
- Success/Failure
- Input
VDSM verbs for deleting snaps
- glusterSnapshotDelete - deletes the given snapshot
- Input
- snapName
- Output
- Success/Failure
- Input
VDSM verbs for listing snaps
- glusterSanpshotList - gets the list of snapshots for a volume
- Input
- [volumeName]
- Output
- snapsList
- Input
Note: If volumeName is not passed, all the snaps are listed
VDSM verbs for snapshot configuration
- glusterSnapshotConfigSet - sets the snapshot configuration parameters for the given volume
- Input
- volumeName
- configList(name=value pair)
- Output
- Success/Failure
- Input
- glusterSnapshotConfigGet - gets the value of the snapshot configuration parameter for the given volume
- Input
- [volumeName]
- Ouptut
- Name=Value pair list
- Input
Note: If volumeName is not passed, configuration values for all the volumes are listed
VDSM verbs for the snapshots status
- glusterSnapshotStatus - gets the snapshot status details for a volume
- Input
- [volumeName]
- [snapName]
- Output
- snapshot status details
- Input
VDSM verbs for activating a snapshot
- glusterSnapshotActivate - activates the given snapshot
- Input
- snapName
- [force]
- Output
- Success/Failure
- Input
Note: If force is passed as true, even if some the bricks are down, they are brought up and snapshot is activated.
VDSM verbs for deactivating the snapshots
- glusterSnapshotDeactivate - deactivates the given snapshot
- Input
- snapName
- Output
- Success/Failure
- Input
VDSM verbs for getting the snapshot info
- glusterSnapshotInfo - gets the snapshot info
- Input
- [snapName]
- [volumeName]
- Output
- snapshot info details
- Input
REST APIs
The details of the REST for Gluster Volume Snapshot feature are as below -
Listing APIs
/api/clusters/{cluster-id}/glustervolumes/{volume-id}/volumesnapshots|rel=get
- lists all the snapshots for a given volume
Output:
<volume_snapshots>
<volume_snapshot href="" id="">
<actions>
</actions>
<name>{name}</name>
<link>{link}</link>
<volume href="" id=""/>
<description>{description}</description>
<status>{status}</status>
<createdAt>{timestamp}</createdAt>
</volume_snapshot>
</volume_snapshots>
/api/clusters/{cluster-id}/glustervolumes/{volume-id}/volumesnapshots/{volume-snapshot-id}|rel=get
- lists the details of a specific snapshot of a volume
Output:
<volume_snapshot href="" id="">
<actions>
</actions>
<name>{name}</name>
<link>{link}</link>
<volume href="" id=""/>
<description>{description}</description>
<status>{status}</status>
<createAt>{timestamp}</createAt>
</volume_snapshot>
/api/clusters/{cluster-id}/glustervolumes/{volume-id}|rel=get
- Gluster volume listing would be updated to list the snapshot configuration parameters and scheduling details of snapshots (if any) as well
Output:
<glustervolume>
........
<volume_snapshot_configuration_parameters>
<volume_snapshot_configuration_parameter>
<name>snap-max-hard-limit</name>
<value>{value}</value>
</volume_snapshot_configuration_parameter>
</volume_snapshot_configuration_parameters>
<volume_snapshot_schedule>
<cron_expression>{cron expression of the schedule}</cron_expression>
</volume_snapshot_schedule>
</glustervolume>
/api/clusters/{cluster-id}|rel=get
- Cluster listing would be updated to list the snapshot configuration parameters as well
Output:
<cluster>
........
<volume_snapshot_configuration_parameters>
<volume_snapshot_configuration_parameter>
<name>snap-max-hard-limit</name>
<value>{value}</value>
</volume_snapshot_configuration_parameter>
<volume_snapshot_configuration_parameter>
<name>snap-max-soft-limit</name>
<value>{value}</value>
</volume_snapshot_configuration_parameter>
<volume_snapshot_configuration_parameter>
<name>auto-delete</name>
<value>{value}</value>
</volume_snapshot_configuration_parameter>
</volume_snapshot_configuration_parameters>
</cluster>
Actions Supported
/ap/clusters/{cluster-id}/glustervolumes/{volume-id}/volumesnapshots|rel=add
- creates and adds a new snapshot for the given volume- Parameters
- name - String
- [description] - string
- [force] - boolean
- [scheduling_det] - details of scheduling if snapshots to be scheduled
- Parameters
Input:
<action>
<volume_snapshot>
<name>{name}</name>
<description>{description}</description>
<force>{true/false}</force>
</volume_snapshot>
</action>
/api/clusters/{cluster-id}/glustervolumes/{volume-id}/volumesnapshots/{volume-snapshot-id}|rel=delete
- deletes snapshot
/api/clusters/{cluster-id}/glustervolumes/{volume-id}/volumesnapshots/{volume-snapshot-id}/restore|rel=restore
- restores the given volume to the given snapshot
/api/clusters/{cluster-id}/glustervolumes/{volume-id}/volumesnapshots/{volume-snapshot-id}/activate|rel=activate
- activates the given volume snapshot
/api/clusters/{cluster-id}/glustervolumes/{volume-id}/volumesnapshots/{volume-snapshot-id}/deactivate|rel=deactivate
- deactivates the given volume snapshot
/api/clusters/{cluster-id}/glustervolumes/{volume-id}/rel=post
- to schedule snapshot creation for a volume use the below POST request on volume
Input:
<action>
<gluster_volume>
.
.
<volume_snapshot_schedule>
<cron_expression>{cron expression of the schedule}</cron_expression>
</volume_snapshot_schedule>
<gluster_volume>
</action>
/api/clusters/{cluster-id}/rel=post
- to set snapshot configuration parameters value for the given cluster use the below POST request on cluster- Parameters
- name-value pair of configuration parameters
- [force]
- Parameters
Input:
<action>
<cluster>
.
.
<volume_snapshot_configuration_parameters>
<volume_snapshot_configuration_parameter>
<name>{name-1}</name>
<value>{value-1}</value>
</volume_snapshot_configuration_parameter>
<volume_snapshot_configuration_parameter>
<name>{name-2}</name>
<value>{value-2}</value>
</volume_snapshot_configuration_parameter>
</volume_snapshot_configuration_parameters>
</cluster>
<force>true/false</force>
</action>
/api/clusters/{cluster-id}/glustervolumes/{volume-id}/rel=post
- to set snapshot configuration parameters for the given volume use the below POST request on volume- Parameters
- name-value pair of configuration parameters
- [force]
- Parameters
Input:
<action>
<gluster_volume>
.
.
<volume_snapshot_configuration_parameters>
<volume_snapshot_configuration_parameter>
<name>{name-1}</name>
<value>{value-1}</value>
</volume_snapshot_configuration_parameter>
<volume_snapshot_configuration_parameter>
<name>{name-2}</name>
<value>{value-2}</value>
</volume_snapshot_configuration_parameter>
</volume_snapshot_configuration_parameters>
</gluster_volume>
<force>true/false</force>
</action>