This document describes how to upload and replace existing template disks using the Appliance manager API.
Use case
Use this process to replace a template disk directly in the repository file system and ensure that Abiquo has the correct template details for the new disk.
- This request requires direct access to the Appliance Manager API
- The Appliance Manager API does not validate the request, so be sure to provide the correct path to your disk file or you could overwrite some other part of your file system!!
Here is an example use case
- Upload or download a template
- Use it to create a VM
- Update the template. Abiquo supports changes to:
- file content
- size
- format
- capacity
- controller
- When the user next deploys the VM, the platform will copy the updated disk
Basic steps
- Get the template details from the Abiquo API
- Create the replacement data object
- Replace the file using the Appliance manager API
1. Send a GET request to the API login resource to obtain an authorization token
If you wish to use token authentication, which is more secure and required for 2FA, do these steps.
Use basic authentication and get the token from the X-Abiquo-Token header.
curl --verbose -X GET "https://abiquo.example.com:443/api/login" -u adminuser:password -k | jq .
Or if you are using 2FA, you can get the 2FA verification code in the usual way (by email or from Google Authenticator).
Log in again and send the 2FA verification code.
curl --verbose -X GET "https://abiquo.example.com:443/api/login" -H "X-Abiquo-OTP: your2FAcode" | jq .
Now you can get the token from the X-Abiquo-Token header of the response.
In your API requests, use the token in a header with the following format. In these examples we have shortened the token to make the requests easier to read.
-H 'Authorization: Token a2e19816735381c1d074441cbd002aa01f9ed7dc4cd9f4e0683c3c88...'
For more details, see Authentication.
You can also get the token from the UI! Go to the browser Developer console on the Network tab and in the request responses look for the X-Abiquo-Token header.
2. Get the template details
Get the enterprise, for example, by using the "has" parameter to filter by a text string in the enterprise names from the list enterprises request.
https://wiki.abiquo.com/api/latest/EnterprisesResource.html#list-enterprises
If you are not already working with this enterprise, switch enterprise by updating the user from any enterprise (underscore character) to the new enterprise.
https://wiki.abiquo.com/api/latest/UsersResource.html#update-a-user-of-an-enterprise
- For more details see How to switch enterprises via API
Get the link to the enterprise's datacenter repository for the appropriate datacenter. The link to the datacenter repositories can be found in the Enterprise entity.
{
"title": "repositories",
"rel": "datacenterrepositories",
"type": "application/vnd.abiquo.datacenterrepositories+json",
"href": "https://abiquo.example.com:443/api/admin/enterprises/1/datacenterrepositories"
},
From this link you can get the datacenter repositories.
https://wiki.abiquo.com/api/latest/DatacenterRepositoriesResource.html#list-datacenter-repositories
Select the appropriate repo and then get the link to the virtual machine templates.
{
"title": "virtual machine templates",
"rel": "virtualmachinetemplates",
"type": "application/vnd.abiquo.virtualmachinetemplates+json",
"href": "https://abiquo.example.com:443/api/admin/enterprises/1/datacenterrepositories/7/virtualmachinetemplates"
},
Get the templates, and find the appropriate template. You can use the "has" parameter to search for the template by name.
The template will contain a link to the template disks.
Get the template disks, and find the disk you wish to replace.
Get the diskUrl and currentPath of the disk.
curl -X GET 'https://abiquo.example.com:443/api/admin/enterprises/1/datacenterrepositories/7/virtualmachinetemplates/520/disks' \
-H 'Accept: application/vnd.abiquo.disks+json;version=5.2' \
-H 'Authorization: Token abe12313535381c1d074441cbd002aa02de2df8b874b455acce1767c51580...'
Response payload:
{
"links": [],
"collection": [
{
"label": "Hard disk 1",
"sequence": 0,
"path": "1/boost-workshop-51-52-api.bcn.abiquo.com/845b6c5d-79b2-42a9-aacd-5aed445f3fcf-yVM.ova/yVM-disk1.vmdk",
"diskFormatType": "VMDK_STREAM_OPTIMIZED",
"diskFileSize": 15189504,
"hdRequired": 67108864,
"state": "DONE",
"diskControllerType": "IDE",
"creationDate": "2021-03-16T17:54:46.000+0000",
"datastoreTierRequired": false,
"links": [
{
"title": "disk",
"rel": "edit",
"type": "application/vnd.abiquo.disk+json",
"href": "https://abiquo.example.com:443/api/admin/enterprises/1/datacenterrepositories/7/virtualmachinetemplates/520/disks/636"
},
{
"title": "conversions",
"rel": "conversions",
"type": "application/vnd.abiquo.conversions+json",
"href": "https://abiquo.example.com:443/api/admin/enterprises/1/datacenterrepositories/7/virtualmachinetemplates/520/disks/636/conversions"
},
{
"title": "yVM_mj",
"rel": "virtualmachinetemplate",
"type": "application/vnd.abiquo.virtualmachinetemplate+json",
"href": "https://abiquo.example.com:443/api/admin/enterprises/1/datacenterrepositories/7/virtualmachinetemplates/520"
},
{
"title": "yVM-disk1",
"rel": "diskfile",
"href": "https://abiquo.example.com:443/am/files/1/boost-workshop-51-52-api.bcn.abiquo.com/845b6c5d-79b2-42a9-aacd-5aed445f3fcf-yVM.ova/yVM-disk1.vmdk"
}
]
},
{
"label": "MyDisk",
"sequence": 1,
"diskFormatType": "RAW",
"diskFileSize": 0,
"hdRequired": 62914560,
"state": "DONE",
"diskControllerType": "SCSI",
"diskController": "lsilogic",
"creationDate": "2021-05-07T20:20:32.000+0000",
"allocation": "THIN",
"datastoreTierRequired": false,
"links": [
{
"title": "disk",
"rel": "edit",
"type": "application/vnd.abiquo.disk+json",
"href": "https://abiquo.example.com:443/api/admin/enterprises/1/datacenterrepositories/7/virtualmachinetemplates/520/disks/717"
},
{
"title": "conversions",
"rel": "conversions",
"type": "application/vnd.abiquo.conversions+json",
"href": "https://abiquo.example.com:443/api/admin/enterprises/1/datacenterrepositories/7/virtualmachinetemplates/520/disks/717/conversions"
},
{
"title": "yVM_mj",
"rel": "virtualmachinetemplate",
"type": "application/vnd.abiquo.virtualmachinetemplate+json",
"href": "https://abiquo.example.com:443/api/admin/enterprises/1/datacenterrepositories/7/virtualmachinetemplates/520"
}
]
}
]
}
3. Create the replacement object
From the above response, we need
- the href URL from the disk edit link
- the path of the disk
From the example above, for the first disk with sequence a number of "0", we have the following.
"href": "https://abiquo.example.com:443/api/admin/enterprises/1/datacenterrepositories/7/virtualmachinetemplates/520/disks/636"
"path": "1/boost-workshop-51-52-api.bcn.abiquo.com/845b6c5d-79b2-42a9-aacd-5aed445f3fcf-yVM.ova/yVM-disk1.vmdk"
diskReplace.json
From the above response, the URL from the disk edit link is used as the diskUrl and the path is used as the currentPath in the JSON request payload to modify the template object.
Here is an example object.
{
"virtualMachineTemplateUrl":"https://abiquo.example.com:443/api/admin/enterprises/1/datacenterrepositories/7/virtualmachinetemplates/520",
"diskUrl":"https://abiquo.example.com:443/api/admin/enterprises/1/datacenterrepositories/7/virtualmachinetemplates/520/disks/636",
"currentPath":"1/boost-workshop-51-52-api.bcn.abiquo.com/845b6c5d-79b2-42a9-aacd-5aed445f3fcf-yVM.ova/yVM-disk1.vmdk",
"diskController": "lsilogic",
"diskControllerType": "SCSI",
"diskFileFormat":"VMDK_STREAM_OPTIMIZED",
"diskFilePath": "",
"label": "Hard disk 1",
"requiredHDInMB":120,
"sequence":0
}
For the "requiredHDInMB" you must enter the correct capacity or deployed size of the disk. The capacity value is stored in the disk file itself.
See Determine the size of a VM disk file.
Abiquo does not validate the value that you enter and if you enter an incorrect value, the platform will try to deploy the disk with its true capacity. The deploy may fail and the platform will not be able to properly check that the disk will fit on the hypervisor datastore.
Important note: You cannot resize (expand) a boot disk before you deploy a VM. After you expand any disk, remember to update the configuration of the disk in the VM operating system.
The default value for the diskControllerType is "IDE" and the default value for the diskController is NULL.
If your template uses a different controller, such as "SCSI" and "lsilogic", you must add these values in the diskReplace.json entity, as shown above. If you do not add them, the platform will overwrite your template with its default values.
You should note that the AM API does not support all of the values that are supported by the Abiquo API.
4. Replace the file
Replace the file using the Appliance manager API.
The URL to post to contains the enterprise ID and the template folder in the following format.
/am/erepos/{enterpriseId}/templates/{templateFolder}
The template folder is the folder path on the NFS Repository, without the file name. For our example:
"href": "https://abiquo.example.com:443/api/admin/enterprises/1/datacenterrepositories/7/virtualmachinetemplates/520/disks/636"
"path": "1/boost-workshop-51-52-api.bcn.abiquo.com/845b6c5d-79b2-42a9-aacd-5aed445f3fcf-yVM.ova/yVM-disk1.vmdk"
The folder path is as follows:
1/boost-workshop-51-52-api.bcn.abiquo.com/845b6c5d-79b2-42a9-aacd-5aed445f3fcf-yVM.ova
The template path does not contain the ID of the datacenter repository. It contains the folder name from /opt/vm_repository.
So in our example, the datacenter repository ID is 7 but the path is "1/boost-workshop..."
Use this information to build the request to replace the disk.
If your folder name contains spaces, encode the section of the name that contains spaces for the URL. For example, for a disk with "abc abc" in the name, you should encode it to
abc%20abc
With this encoding, the server will correctly read the URL as "abc%20abc".
If you use the request without encoding, it may destroy your original disk file.
cURL
% curl -v -k -H 'Authorization: Token a2e19816735381c1d074441cbd002aa01f9ed7dc4cd9f4e0683c3c88...' \ -X POST 'https://abiquo.example.com:443/am/erepos/1/templates/1/boost-workshop-51-52-api.bcn.abiquo.com/845b6c5d-79b2-42a9-aacd-5aed445f3fcf-yVM.ova' \ -F "diskInfo=@diskReplace.json" -F "diskFile=@newdisk.vmdk"
Replace newdisk.vmdk with the name of your disk file on the local file system.
Save the disk replacement object you created previously to a file called diskReplace.json
{
"virtualMachineTemplateUrl":"https://abiquo.example.com:443/api/admin/enterprises/1/datacenterrepositories/7/virtualmachinetemplates/520",
"diskUrl":"https://abiquo.example.com:443/api/admin/enterprises/1/datacenterrepositories/7/virtualmachinetemplates/520/disks/636",
"currentPath":"1/boost-workshop-51-52-api.bcn.abiquo.com/845b6c5d-79b2-42a9-aacd-5aed445f3fcf-yVM.ova/yVM-disk1.vmdk",
"diskControllerType": "IDE",
"diskFileFormat":"VMDK_STREAM_OPTIMIZED",
"requiredHDInMB":120,
"sequence":0
}
Example request:
% curl -v -k -H 'Authorization: Token a2e19816735381c1d074441cbd002aa01f9ed7dc4cd9f4e0683c3c88...' \ -X POST 'https://abiquo.example.com:443/am/erepos/1/templates/1/boost-workshop-51-52-api.bcn.abiquo.com/845b6c5d-79b2-42a9-aacd-5aed445f3fcf-yVM.ova' \ -F "diskInfo=@diskReplace.json" -F "diskFile=@newdisk.vmdk" Note: Unnecessary use of -X or --request, POST is already inferred. > POST /am/erepos/1/templates/1/boost-workshop-51-52-api.bcn.abiquo.com/845b6c5d-79b2-42a9-aacd-5aed445f3fcf-yVM.ova HTTP/1.1 > Host: abiquo.example.com > User-Agent: curl/7.64.1 > Accept: */* > Authorization: Token a2e19816735381c1d074441cbd002aa01f9ed7dc4cd9f4e0683c3c88... > Content-Length: 69061 > Content-Type: multipart/form-data; boundary=------------------------78e5513c23c993fa > Expect: 100-continue > < HTTP/1.1 100 Continue < HTTP/1.1 201 201 < Date: Tue, 08 Jun 2021 07:37:14 GMT < Server: Apache < Location: https://abiquo.example.com/am/erepos/1/templates/1/boost-workshop-51-52-api.bcn.abiquo.com/845b6c5d-79b2-42a9-aacd-5aed445f3fcf-yVM.ova/d523f99e-74bc-4dd0-93ba-3224eb91f9ee-newdisk.vmdk < Content-Length: 0 <
Success status code: 201 Created
5. Check the disk file
You can check the new disk file on the file system using the details in the Location link in the above response.
[user@abiquo 845b6c5d-79b2-42a9-aacd-5aed445f3fcf-yVM.ova]# ls d523f99e-74bc-4dd0-93ba-3224eb91f9ee-newdisk.vmdk formats yVM.mf yVM.ovf [user@abiquo 845b6c5d-79b2-42a9-aacd-5aed445f3fcf-yVM.ova]#
And in this case, we retrieved the template disks and checked the details of the disk file in the API.
{
"title": "d523f99e-74bc-4dd0-93ba-3224eb91f9ee-newdisk",
"rel": "diskfile",
"href": "https://abiquo.example.com:443/am/files/1/boost-workshop-51-52-api.bcn.abiquo.com/845b6c5d-79b2-42a9-aacd-5aed445f3fcf-yVM.ova/d523f99e-74bc-4dd0-93ba-3224eb91f9ee-newdisk.vmdk"
}