Abiquo virtual machine metadata
Abiquo stores some information in VMs as metadata and allows users to store custom metadata too. To access metadata, use the link with the "rel" value of "metadata" in the VM.
Writing metadata will overwrite ALL existing metadata, so the first step is to retrieve the existing metadata in the appropriate format. Abiquo recommends JSON format. Then add new metadata keys and values as required.
Note: Do not use a conversion tool to convert between JSON and XML format because this may produce an incompatible data transfer object.
For the metadata attribute/object, Abiquo has the reserved keys that are described in the following table.Metadata type Reserved Keys Description Chef Bootstrap script Metrics Custom
VM metadata tutorial
This tutorial will show you have to retrieve and update metadata to add a startup script to your VM via API.
To work through this tutorial, you will need:
- A VM that is not deployed (or powered off)
- This tutorial shows a VM that is not deployed
- An optional monitoring server
- User with privileges to modify VMs, optionally enable monitoring, and manage backups (which previously used metadata).
Get the VM and the metadata link
To get started, use the query to retrieve all of your VMs from the cloud and select the desired VM.
* No special privileges are required to get all the VMs that your user can access * Here we are filtering the VMs using the "has" parameter to select the one that has "ABQ_2fade" in the name curl -X GET https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualmachines?has=ABQ_2fade \ -H "Accept: application/vnd.abiquo.virtualmachines+json; version=4.2" \ -u user:password --verbose | pjson
From the VM data object, the link to the VM metadata is the one with the "rel" value of metadata.
{
"title": "metadata",
"rel": "metadata",
"type": "application/vnd.abiquo.metadata+json",
"href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2/virtualmachines/24/metadata"
},
There is also a metadata attribute in the VM with a null value, but the correct way to access metadata is using the metadata link.
Retrieve existing VM metadata
Use the VM metadata link from the step above to retrieve any existing metadata.
curl -X GET http://localhost:9000/api/cloud/virtualdatacenters/2/virtualappliances/2/virtualmachines/24/metadata \
-H 'Accept:application/vnd.abiquo.metadata+json; version=4.2' \
-u user:password --verbose
When there is no metadata, the query returns a 200 status code, and the data object has an empty links list and a null metadata attribute.
{
"links": [],
"metadata": null
}
Enable monitoring, select metrics and retrieve metadata again
First, in the UI, just enable "Fetch metrics" and don't select any metrics to retrieve. Then retrieve metadata again using the same GET request as in the previous step.
The metadata object will now have an empty monitoring-metrics list.
{
"links": [],
"metadata": {
"monitoring-metrics": []
}
}
Now select one or more metrics to retrieve. Here we selected two of the built-in metrics from a KVM hypervisor and performed the GET request again.
{
"links": [],
"metadata": {
"monitoring-metrics": [
{
"name": "cpu_time"
},
{
"name": "used_mem"
}
]
}
}
Prepare a VM startup script
The platform will store the VM startup script in the VM metadata under the startup-script key.
Abiquo supports cloud-config scripts with cloud-init templates in private cloud, and in public cloud.
To add the startup script to the JSON object, you will need to escape any special characters, such as quotation marks, in the script.
So for example, we have the following script for use with a cloud-init template on a Linux system.
Disclaimer: this is a sample script for illustrative purposes only. Please see cloud-init documentation to find out how this script works.
#cloud-config
hostname: "userdatahostname"
users:
- name: "myuser"
# mkpasswd --method=SHA-512 --rounds=4096 mypass
passwd: "$6$rounds=4096$aD0didNw/$Pau0z3YK2Ss5MWYoxScEedfMa.1N5qRqK0xYrgs79qdjHdoFUIRmVXpeEewDduSbImu7sqIjSRm40xO6PpJhk/"
groups:
- "sudo"
ssh_authorized_keys:
- "ssh-rsa USER_ID_RSA.PUB"
After you escape the special characters it will look like this:
#cloud-config\r\nhostname: \"userdatahostname\"\r\nusers:\r\n - name: \"myuser\"\r\n \t# mkpasswd --method=SHA-512 --rounds=4096 mypass\r\n passwd: \"$6$rounds=4096$aD0didNw\/$Pau0z3YK2Ss5MWYoxScEedfMa.1N5qRqK0xYrgs79qdjHdoFUIRmVXpeEewDduSbImu7sqIjSRm40xO6PpJhk\/\" \r\n groups:\r\n - \"sudo\"\r\nssh_authorized_keys:\r\n - \"ssh-rsa USER_ID_RSA.PUB\"
Tip: you can use a JSON string escape/unescape tool to create this format.
Add the startup script to the metadata object with the "startup-script" key. Don't forget to add a comma after the previous object. After you add the startup script, the metadata object should look something like this:
{
"links": [],
"metadata": {
"monitoring-metrics": [
{
"name": "cpu_time"
},
{
"name": "used_mem"
}
],
"startup-script":
"#cloud-config\r\nhostname: \"userdatahostname\"\r\nusers:\r\n - name: \"myuser\"\r\n \t# mkpasswd --method=SHA-512 --rounds=4096 mypass\r\n passwd: \"$6$rounds=4096$aD0didNw\/$Pau0z3YK2Ss5MWYoxScEedfMa.1N5qRqK0xYrgs79qdjHdoFUIRmVXpeEewDduSbImu7sqIjSRm40xO6PpJhk\/\" \r\n groups:\r\n - \"sudo\"\r\nssh_authorized_keys:\r\n - \"ssh-rsa USER_ID_RSA.PUB\""
}
}
Update VM metadata
To update the VM metadata, perform a PUT request to the metadata link.
curl -X PUT http://localhost:9000/api/cloud/virtualdatacenters/2/virtualappliances/2/virtualmachines/24/metadata \
-H 'Accept:application/vnd.abiquo.metadata+json; version=4.2' \
-H 'Content-Type:application/vnd.abiquo.metadata+json; version=4.2' \
-d @requestpayload.json \
-u user:password --verbose
In this case, the requestpayload.json file should contain the JSON object from the previous step.
{
"links": [],
"metadata": {
"monitoring-metrics": [
{
"name": "cpu_time"
},
{
"name": "used_mem"
}
],
"startup-script":
"#cloud-config\r\nhostname: \"userdatahostname\"\r\nusers:\r\n - name: \"myuser\"\r\n \t# mkpasswd --method=SHA-512 --rounds=4096 mypass\r\n passwd: \"$6$rounds=4096$aD0didNw\/$Pau0z3YK2Ss5MWYoxScEedfMa.1N5qRqK0xYrgs79qdjHdoFUIRmVXpeEewDduSbImu7sqIjSRm40xO6PpJhk\/\" \r\n groups:\r\n - \"sudo\"\r\nssh_authorized_keys:\r\n - \"ssh-rsa USER_ID_RSA.PUB\""
}
}
If the request is successful, it will return a status code of 200 and the updated metadata object.
{
"links": [],
"metadata": {
"monitoring-metrics": [
{
"name": "cpu_time"
},
{
"name": "used_mem"
}
],
"startup-script": "#cloud-config\r\nhostname: \"userdatahostname\"\r\nusers:\r\n - name: \"myuser\"\r\n \t# mkpasswd --method=SHA-512 --rounds=4096 mypass\r\n passwd: \"$6$rounds=4096$aD0didNw/$Pau0z3YK2Ss5MWYoxScEedfMa.1N5qRqK0xYrgs79qdjHdoFUIRmVXpeEewDduSbImu7sqIjSRm40xO6PpJhk/\" \r\n groups:\r\n - \"sudo\"\r\nssh_authorized_keys:\r\n - \"ssh-rsa USER_ID_RSA.PUB\""
}
}
So that's a wrap! 
Access metadata as part of the VM
Here we made a GET request to obtain the VM object and removed the links to make it smaller. Here, the metadata object is part of the VM but the links list is not shown.
{
"id": 24,
"uuid": "2fade39a-fe59-44b4-be3f-b96b63b48153",
"name": "ABQ_2fade39a-fe59-44b4-be3f-b96b63b48153",
"label": "VM_metadata",
"description": "A virtual machine",
"cpu": 1,
"ram": 48,
"vdrpEnabled": true,
"vdrpPort": 0,
"idState": 1,
"state": "NOT_ALLOCATED",
"idType": 0,
"type": "MANAGED",
"highDisponibility": 0,
"password": "uMvMpfyD",
"metadata": {
"monitoring-metrics": [
{
"name": "cpu_time"
},
{
"name": "used_mem"
}
],
"startup-script": "#cloud-config\r\nhostname: \"userdatahostname\"\r\nusers:\r\n - name: \"myuser\"\r\n \t# mkpasswd --method=SHA-512 --rounds=4096 mypass\r\n passwd: \"$6$rounds=4096$aD0didNw/$Pau0z3YK2Ss5MWYoxScEedfMa.1N5qRqK0xYrgs79qdjHdoFUIRmVXpeEewDduSbImu7sqIjSRm40xO6PpJhk/\" \r\n groups:\r\n - \"sudo\"\r\nssh_authorized_keys:\r\n - \"ssh-rsa USER_ID_RSA.PUB\""
},
"monitored": true,
"protected": false,
"variables": {},
"creationTimestamp": 1520865331000,
"backuppolicies": [],
"generateGuestInitialPassword": false,
"natrules": [],
....
}
So the most complete and most convenient way to work with VM metadata is using the metadata link!
Delete metadata
If you ever need to delete the VM metadata, just send a DELETE request to the metadata link. But remember that this request will delete ALL metadata, leaving just the empty links list and the null metadata key, as shown in the first example when we retrieved the empty metadata object.
Related links
API references about working with VM metadata: