Abiquo 2.6


Skip to end of metadata
Go to start of metadata

Introduction to Backup Front-End

The backup front-end feature enables our customers to integrate their external backup systems with Abiquo. User backup requirements will be stored as key-values in the virtual machine metadata. Abiquo customers can create a connector that receives information about required backups and sends it to their data center’s backup system. Connectors can subscribe to backup-related events through the outbound API and retrieve backup information stored in a VM using an API call. This feature will enable customers to fully delegate backup decisions to users, who will order backups through the UI. These backups will then be performed outside of Abiquo.  

Using the default privileges:

  • Cloud administrators configure the backup methods to offer at datacenter level  

  • Cloud users configure their VM backup requirements in the Abiquo UI

Beyond version V2.6, Abiquo will offer specific backup connectors to leading backup technologies.

Specifications

External backup systems may have any of the following options. Cloud administrators can select those that will be available to users based on their external backup systems and resources. If a Cloud Admin changes the available configuration, this only changes NEW VMs. Old VMs can still have the old configuration.

Methods

  1. Complete - Complete copy of the VM

  2. Filesystem - Specific backup of a directory (or directories) on the VM  

  3. Snapshot - Differential backup of the state and data of a VM at a specific point in time

    Snapshots are Differential Backups of the VM State and Data

    Note that Abiquo uses the VMware definition of Snapshot backup, which means that a "snapshot file is only a change log of the original virtual disk". See  VMware Snapshot Best Practices and  Understanding VMware Snapshots .

Granularity

  • defined hour

  • hourly

  • daily

  • weekly plan

  • monthly

Configuring Backups

Enable Backups for a Datacenter

To enable users to configure VM backups for a datacenter.  Go to the Infrastructure tab and open the datacenter.  Mark the checkbox to Enable Backup for this Datacenter.

Set Available Backup Configuration

Select the Backups that you will make available to your users and click Save.

  • When you change an existing backup configuration, the changes will highlighted. 
    • Backups you added will be shown with green text
    • Backups you removed will be shown in red text. 

 

 

Assign Backup Privileges to Your Users

By default the privileges that allow users to configure backups of their virtual machines are only assigned to the Cloud Administrator. You can assign these privileges to your cloud administrators, enterprise administrators or users as required.

PrivilegeDescription
Manage datacenter backup configurationThis privilege allows the user to manage backup configuration at datacenter level
Manage virtual machine backup configuration

This privilege allows a user to manage backup configuration at virtual machine level

Manage virtual machine backup schedule

This privilege allows a user to specify an additional option for backup configuration by setting backup dates and times

Configure Virtual Machine Backups

If backups are configured in your datacenter, when you configure your virtual machine, you will see the Backup Configuration tab.

Configure Backup Type

If you have the privilege to Manage virtual machine backup configuration, you can set the basic backup configuration for your virtual machines. This means you can choose the basic backup type and the disk.

Click on the Backup Configuration tab, then click on the Backups page.

  • Click the checkbox to enable backup

  • Select backup options from those available in your datacenter

Select Disks for Snapshot or Complete Backup 
  • Click Select Disks
  • Select the disks for backup 
    • The disks are shown in sequence order
    • The system disk is the first disk in the list
  • Click OK to confirm

Enter a Path for Filesystem Backup

For a filesystem backup, enter the folder or directory path to back up. Click Add to add the path to the list.

To remove a path, click the x beside it in the Path list.

Click Close to continue

Configure Backup Schedule

If you have the additional privilege to Manage virtual machine backup schedule you can further configure your virtual machine backups. This means you can configure the exact date and time of a backup.

Be careful when configuring the backup time.

Backup Times

Abiquo uses ISO 8601 and users should be informed of the time standard used in the datacenter

Time zones in ISO 8601 are represented as local time (with the location unspecified), as UTC, or as an offset from UTC

 

View the Results of Latest Backups

Click on the Latest Backups page to view the results of your latest backups. The results shown may vary depending on your datacenter's backup system.

 

User Backup Events

When you change the virtual machine's backup configuration, the backup feature will produce the events described in the following table.

 

Event Identifier

Event Description

VIRTUAL_MACHINE_METADATA_MODIFIED_INFO

Backup Configuration for virtual machine 'entity.name' has been modified.

Administrator Backup Events

When you change the datacenter's backup configuration, the backup feature will produce the events described in the following table.

 

Event Identifier

Event Description

DATACENTER_BACKUP_CREATE_INFO

Backup Configuration 'template.name' has been created for datacenter 'datacenter.name'.

DATACENTER_BACKUP_MODIFY_INFO

Backup Configuration for datacenter 'DC_NAME' has been modified.

DATACENTER_BACKUP_DELETE_INFO

Deleted Backup Configuration 'BU_NAME' for datacenter 'DC_NAME'.

 

Backup Integration

The backup front-end feature is implemented as a free text field called “metadata” in the virtual machine, with a key-value format for backup configuration. The field is stored as JSON in the database but sent as XML in response to API requests. The example below shows different backup options.

A backup is configured under the backupSchedule tag. The backup results are stored under the backupResults tag.

The backup data will be validated and only keywords will be processed. For example, if you added ‘ "<foo> </foo>” instead of “<disk> </disk>” to the example in the “disks” section, it would be ignored.

Example Backup VM Metadata

<virtualmachinemetadata>
<metadata>
    <backupSchedule>
        <complete>
            <defined_hour>
                <time>10:30:00 -0300</time>
                <disks>
                  <disk>256</disk>
		    <disk>255</disk>
                </disks>
            </defined_hour>
        </complete>
        <snapshot> 
            <defined_hour>
                <differential>true</differential>
                <time>10:30:00 -0300</time>
            </defined_hour>
            <weekly_planned>
                <full/>
                <time>10:30 GMT+1</time>
                <monday></monday>
                <tuesday></tuesday>
            </weekly_planned>
        </snapshot>
        <filesystem>
            <weekly_planned>
                <time>10:30:00 -0300</time>
                <monday></monday>
                <tuesday></tuesday>
                <paths>
                    <path>/home/user/Documents/doc1</path>
                </paths>
            </weekly_planned>
            <defined_hour>
                <paths>
                    <path>/home/user/doc1</path>
                </paths>
            </defined_hour>
        </filesystem>
    </backupSchedule>
    <backupResults>
        <results>
            <result>
                <name>defined_hour</name>
                <status>done</status>
                <date>2015/05/01 17:25:00 -0300</date>
                <size>100</size>
                <type>1</type>
            </result>
            <result>
                <name>hourly</name>
                <status>progress</status>
                <date>2013/05/10 10:00:00 +0400</date>
                <size>100</size>
                <type>1</type>
            </result>
        </results>
    </backupResults>
</metadata>
</virtualmachinemetadata>

VM Backup Configurations

The following virtual machine backup configurations are valid:

  • complete + granularity + disks
  • snapshot + granularity + paths
  • filesystem + granularity + disks

Backup Results

The following values are valid for these backup results elements:

Status:

  • done
  • canceled
  • progress
  • failed

Type:

TypeDescription
1snapshot
2filesystem
3complete

Name:

  • defined_hour
  • hourly
  • daily
  • weekly_planned
  • monthly

Size:

  • Value in MB

API Integration

After a Backup Connector receives notification of a backup event from the outbound API, you can retrieve the backup information using the Abiquo API.  Also through the Abiquo API, you can retrieve virtual machines with metadata and filter on the metadata keys. So for example, you could retrieve all of the virtual machines requiring complete backups for your datacenter.    

The virtualmachine media type contains the metadata element with the backup information. The virtualmachinewithnode and virtualmachinewithnodeextended media types do not.  You can get just the metadata for a virtual machine using the metadata media type and using a get over the metadata link.

Example API Requests

The following section shows basic examples of API requests that could be used in backup integration.

Get enable backup options of all backup types
curl -X GET http://example.com/api/admin/datacenters/1/backups \
        -H 'Accept: application/vnd.abiquo.backups+xml;version=2.6' \
        -u user:pass --verbose


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<backups>
    <backup>
        <link rel="backup" type="application/vnd.abiquo.backup+xml; version=2.6" href="http://localhost:80/api/admin/datacenters/1/backups/1"/>
        <link rel="datacenter" type="application/vnd.abiquo.datacenter+xml" href="http://localhost:80/api/admin/datacenters/1"/>
        <link rel="template" type="application/vnd.abiquo.backup+xml; version=2.6" href="http://localhost:80/api/config/backups/1"/>
        <id>1</id>
        <attributes>
            <attribute>defined_hour</attribute>
        </attributes>
    </backup>
    <backup>
        <link rel="backup" type="application/vnd.abiquo.backup+xml; version=2.6" href="http://localhost:80/api/admin/datacenters/1/backups/3"/>
        <link rel="datacenter" type="application/vnd.abiquo.datacenter+xml" href="http://localhost:80/api/admin/datacenters/1"/>
        <link rel="template" type="application/vnd.abiquo.backup+xml; version=2.6" href="http://localhost:80/api/config/backups/3"/>
        <id>2</id>
        <attributes>
            <attribute>monthly</attribute>
        </attributes>
    </backup>
</backups>

 

Modify enable backup options of all backup types
curl -X PUT http://example.com/api/admin/datacenters/1/backups\
	 -H 'Accept: application/vnd.abiquo.backups+xml; version=2.6'	\
	 -H 'Content-Type: application/vnd.abiquo.backups+xml; version=2.6'	\
	 -d @entity.xml	\
	 -u user:password --verbose


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<backups>
    <backup>
        <link rel="backup" type="application/vnd.abiquo.backup+xml; version=2.6" href="http://localhost:80/api/admin/datacenters/1/backups/3"/>
        <link rel="datacenter" type="application/vnd.abiquo.datacenter+xml" href="http://localhost:80/api/admin/datacenters/1"/>
        <link rel="template" type="application/vnd.abiquo.backup+xml; version=2.6" href="http://localhost:80/api/config/backups/3"/>
        <id>5</id>
        <attributes>
            <attribute>daily</attribute>
            <attribute>defined_hour</attribute>
        </attributes>
    </backup>
    <backup>
        <link rel="backup" type="application/vnd.abiquo.backup+xml; version=2.6" href="http://localhost:80/api/admin/datacenters/1/backups/2"/>
        <link rel="datacenter" type="application/vnd.abiquo.datacenter+xml" href="http://localhost:80/api/admin/datacenters/1"/>
        <link rel="template" type="application/vnd.abiquo.backup+xml; version=2.6" href="http://localhost:80/api/config/backups/2"/>
        <id>6</id>
        <attributes>
            <attribute>hourly</attribute>
        </attributes>
    </backup>
</backups>

More examples available in DatacenterResource

Retrieve Backup Configuration and Data

Retrieve the metadata of a virtual machine.

curl -verbose -u user:password http://example.com/api/cloud/virtualdatacenters/3/virtualappliances/3/virtualmachines/7/metadata -X GET -H "accept:application/vnd.abiquo.metadata+xml; version=2.6" | xmlindent -nbe -f

Example API Response

> GET /api/cloud/virtualdatacenters/3/virtualappliances/3/virtualmachines/7/metadata HTTP/1.1
> Authorization: Basic YWRtaW46eGFiaXF1bw==
> User-Agent: curl/7.15.5 (x86_64-redhat-linux-gnu) libcurl/7.15.5 OpenSSL/0.9.8b zlib/1.2.3 libidn/0.6.5
> Host: 10.60.1.18
> Referer: rbose
> accept:application/vnd.abiquo.metadata+xml; version=2.6
> 
< HTTP/1.1 200 OK
< Server: Apache-Coyote/1.1
< Set-Cookie: auth=YWRtaW46MTM3NTk4MDUxNjk3Nzo5NDk3YjE4MDEwN2Y1NWI4NDczZGY5ZDI2YmUwZTliNjpBQklRVU8; Expires=Thu, 08-Aug-2013 16:48:36 GMT; Path=/api
< Set-Cookie: JSESSIONID=D941FBA2B5CF9F651B68EF60397482B0; Path=/api
< Content-Type: application/vnd.abiquo.metadata+xml;version=2.6
< Content-Length: 447
< Date: Thu, 08 Aug 2013 16:18:37 GMT
 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<virtualmachinemetadata>
    <metadata>
        <backupSchedule>
            <complete>
                <defined_hour>
                    <time>2013/03/21 13:20:00 +1200</time>
                    <disks>
                        <disk>2042</disk>
                    </disks>
                </defined_hour>
            </complete>
            <snapshot>
                <defined_hour>
                    <disks>
                        <disk>2042</disk>
                    </disks>
                </defined_hour>
            </snapshot>
            <filesystem>
                <defined_hour>
                    <paths>
                        <path>/home</path>
                    </paths>
                </defined_hour>
            </filesystem>
        </backupSchedule>
    </metadata>
</virtualmachinemetadata>
Write Backup Results to a Virtual Machine

To add the results of this backup to the virtual machine metadata, copy the retrieved data, add the new data and perform a put request to virtual machine metadata.

curl -X PUT -u user:password 'http://example.com/api/cloud/virtualdatacenters/3/virtualappliances/3/virtualmachines/7/metadata' -H 'Content-type:application/vnd.abiquo.metadata+xml' -d@/home/mjsmyth/xmls/metadatafull.xml | xmlindent -f -nbe
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<virtualmachinemetadata>
    <metadata>
        <backupSchedule>
            <complete>
                <defined_hour>
                    <time>2013/03/21 13:20:00 +1200</time>
                    <disks>
                        <disk>2042</disk>
                    </disks>
                </defined_hour>
            </complete>
            <snapshot>
                <defined_hour>
                    <disks>
                        <disk>2042</disk>
                    </disks>
                </defined_hour>
            </snapshot>
            <filesystem>
                <defined_hour>
                    <paths>
                        <path>/home</path>
                    </paths>
                </defined_hour>
            </filesystem>
        </backupSchedule>
        <backupResults>
            <results>
                <result>
                    <status>done</status>
                    <name>defined_hour</name>
                    <type>1</type>
                    <date>2013/03/21 13:30:00 +1200</date>
                    <size>500</size>
                </result>
            </results>
        </backupResults>
    </metadata>
</virtualmachinemetadata>

More examples available in VirtualMachineResource

The put request will return the metadata as confirmation of the successful request.

Display of Backup Results in the Abiquo GUI

In the Abiquo GUI on the Latest Backups tab:

  • The backup size is interpreted in MB
  • The backup type is interpreted as:
    1. Snapshot backup
    2. Filesystem backup
    3. Complete backup

Customizing backup descriptions

Just like all the other labels in the Abiquo GUI, backup descriptions for the datacenter can be easily customized. The datacenter backup descriptions are in the Infrastructure.properties GUI labels file. The virtual machine backup descriptions are in the VirtualAppliance.properties file. See Abiquo GUI Localization

 

Limitations and clarifications

Customers must create their own connectors to read the backup requests from Abiquo and send them to their own backup system. The option for users to create an instant backup is not offered. However, if users have access to a defined hour backup, then they can set one to be performed as soon as possible.