Abiquo Documentation Cookies Policy

Our Documentation website uses cookies to improve your experience. Please visit our Cookie Policy page for more information about cookies and how we use them.

Skip to end of metadata
Go to start of metadata

Backup Integration

In Abiquo 3.1,1, some backup results fields have been changed to free text.

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 and sent as XML or JSON in response to API requests for metadata.

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.

In Abiquo 3.2, the new Backup Restore feature will require:

  • the backup result status field with a value of "done" or "complete" (in lower-case letters only)
  • a new backup result id field with a unique ID for the completed backup. The restore feature will search for the ID to retrieve details of a completed backup

Metadata XML Example

 Click here to show or hide the XML example
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<virtualmachinemetadata>
    <metadata>
        <backupSchedule>
            <complete>
                <daily>
                    <time>05:10:10 +0001</time>
                    <disks>
                        <disk>518</disk>
                    </disks>
                </daily>
            </complete>
            <snapshot>
                <defined_hour>
                    <time>2014/10/03 10:30:00 +0001</time>
                    <disks>
                        <disk>518</disk>
                    </disks>
                </defined_hour>
            </snapshot>
            <filesystem>
                <hourly>
                    <time>2</time>
                    <paths>
                        <path>/usr/bin</path>
                    </paths>
                </hourly>
            </filesystem>
        </backupSchedule>
        <backupResults>
            <results/>
        </backupResults>
    </metadata>
</virtualmachinemetadata>

 

Metadata JSON Example

 Click here to show or hide the JSON example
{
    "links": [],
    "metadata": {
        "backupSchedule": {
            "complete": {
                "daily": {
                    "time": "05:10:10 +0001",
                    "disks": [
                        "518"
                    ]
                }
            },
            "snapshot": {
                "defined_hour": {
                    "time": "2014/10/03 10:30:00 +0001",
                    "disks": [
                        "518"
                    ]
                }
            },
            "filesystem": {
                "hourly": {
                    "time": "2",
                    "paths": [
                        "/usr/bin"
                    ]
                }
            }
        },
        "backupResults": {
            "results": []
        }
    }
}

 

Outbound API Backup Events

You can connect to the Abiquo Outbound API and detect the following Backup events.

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'.

VIRTUAL_MACHINE_METADATA_MODIFIED_INFO

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

 

After a Backup Connector receives notification of a backup event (i.e. a modification of the user metadata) from the outbound API, you can retrieve the backup information using the Abiquo API. 

Alternatively, through the API you can also 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 link to the metadata element with the backup information.  

VM Backup Configurations

The following virtual machine backup configurations are valid:

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

Backup Results

The following table contains suggested values for some of the backup results elements:

Backup elementField typeSuggested valuesNotes
Statusfree text
  • done
  • completed
  • progress
  • failed
  • The UI will display the status stored in the field
  • In Abiquo 3.2, the new Backup restore feature will require the Backup result status field to have a value of "done" or "complete" (in lower-case letters only).
Typefree text
  • snapshot
  • filesystem
  • complete
  • Previously the UI interpreted an integer field for display as follows:
    • 1 = snapshot
    • 2 = filesystem
    • 3 = complete
  • From Abiquo 3.1.1, the field is free text and the UI will display the text exactly as it stored in the field
Namefree text
  • defined_hour
  • hourly
  • daily
  • weekly_planned
  • monthly
The UI will display the status stored in the field
SizeInteger(value in MB)The UI will display the size stored in the field

 

Example API Requests

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

Retrieve Backup Configuration and Data

Retrieve the metadata of a virtual machine. Note that the field validation has changed but the backup metadata data type has not changed in Abiquo 3.1.1

curl -X GET -H "Accept:application/vnd.abiquo.metadata+xml; version=3.1" 'https://example.com/api/cloud/virtualdatacenters/1/virtualappliances/1/virtualmachines/12/metadata'  | xmlindent -nbe -f

Example API Response

 Click here to show or hide the example
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<virtualmachinemetadata>
    <metadata>
        <backupSchedule>
            <complete>
                <monthly>
                    <disks>
                        <disk>2</disk>
                    </disks>
                    <time>10:00:00 +0000</time>
                </monthly>
            </complete>
            <snapshot>
                <hourly>
                    <disks>
                        <disk>2</disk>
                    </disks>
                    <time>2</time>
                </hourly>
            </snapshot>
            <filesystem>
                <defined_hour>
                    <paths>
                        <path>/</path>
                    </paths>
                    <time>2014/10/02 16:00:00 +0000</time>
                </defined_hour>
            </filesystem>
        </backupSchedule>
        <backupResults>
            <results/>
        </backupResults>
    </metadata>
</virtualmachinemetadata>

 

Write Backup Results to a Virtual Machine

To add the results of a 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" 'https://example.com/api/cloud/virtualdatacenters/1/virtualappliances/1/virtualmachines/12/metadata' -H 'Content-type:application/vnd.abiquo.metadata+xml; version=3.1' -H 'Accept:application/vnd.abiquo.metadata+xml; version=3.1' -d@/home/user/xmls/metadatafull.json | xmlindent -f -nbe
 Click here to show or hide the example
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<virtualmachinemetadata>
    <metadata>
        <backupSchedule>
            <complete>
                <daily>
                    <time>05:10:10 +0001</time>
                    <disks>
                        <disk>518</disk>
                    </disks>
                </daily>
            </complete>
            <snapshot>
                <defined_hour>
                    <time>2014/10/03 10:30:00 +0001</time>
                    <disks>
                        <disk>518</disk>
                    </disks>
                </defined_hour>
            </snapshot>
            <filesystem>
                <hourly>
                    <time>2</time>
                    <paths>
                        <path>/usr/bin</path>
                    </paths>
                </hourly>
            </filesystem>
        </backupSchedule>
        <backupResults>
            <results>
                <result>
                    <status>progress</status>
                    <name>defined_hour</name>
                    <type>snapshot</type>
                    <date>2014/10/03 16:00:00 +0000</date>
                    <size>250</size>
                </result>
                <result>
                    <status>done</status>
                    <name>hourly</name>
                    <type>complete</type>
                    <date>2014/10/03 16:00:00 +0000</date>
                    <size>317</size>
                </result>
            </results>
        </backupResults>
    </metadata>
</virtualmachinemetadata>

In JSON format, the equivalent backupResults would be as follows.

Note that the JSON does not contain a "virtualmachinemetadata" element or individual elements within lists (e.g. "result" elements).

curl -X PUT -u "user:password" 'https://example.com/api/cloud/virtualdatacenters/1/virtualappliances/1/virtualmachines/12/metadata' -H 'Content-type:application/vnd.abiquo.metadata+json;version=3.1' -H 'Accept:application/vnd.abiquo.metadata+json; version=3.1' -d@/home/user/xmls/metadatafull.json | xmlindent -f -nbe 

The following example shows the metadata returned, but only the "link" element has been added by the platform. The metadata sent would be the same as the metadata returned, but without the link element.

 Click here to hide or show the example
{
    "links": [],
    "metadata": {
        "backupSchedule": {
            "complete": {
                "daily": {
                    "time": "05:10:10 +0001",
                    "disks": [
                        "518"
                    ]
                }
            },
            "snapshot": {
                "defined_hour": {
                    "time": "2014/10/03 10:30:00 +0001",
                    "disks": [
                        "518"
                    ]
                }
            },
            "filesystem": {
                "hourly": {
                    "time": "2",
                    "paths": [
                        "/usr/bin"
                    ]
                }
            }
        },
        "backupResults": {
            "results": [
                {
                    "status": "progress",
                    "name": "defined_hour",
                    "type": "snapshot",
                    "date": "2014/10/03 16:00:00 +0000",
                    "size": "250"
                },
                {
                    "status": "done",
                    "name": "hourly",
                    "type": "complete",
                    "date": "2014/10/03 16:00:00 +0000",
                    "size": "317"
                }
            ]
        }
    }
}

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 free text fields are displayed for:
    • Backup Type
    • Backup Option
    • Status

Customizing UI backup texts

Just like all the other labels in the Abiquo UI, backup descriptions and texts for the datacenter and virtual machine can be easily customized. The datacenter backup descriptions are in the lang_en_US_labels.json file and can be customized in the lang_xx_XX_custom.json file. See Abiquo UI 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.