Abiquo Backup Integration v3.1.1

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 element	Field type	Suggested values	Notes
Status	free 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).
Type	free 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
Name	free text	defined_hour hourly daily weekly_planned monthly	The UI will display the status stored in the field
Size	Integer	(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.

Space shortcuts