This tutorial describes how to create an Abiquo datacenter and incorporate a hypervisor, which are tasks of the cloud administrator.
Before you begin working with the API tutorials, you should complete the following prerequisites:
- The platform should be installed in a test environment, see Installation
- The platform should have a license added, on the License tab in Configuration view#Licenses
- You should have basic general knowledge of the Abiquo platform, see the Get started section
- You should have worked with the Abiquo user interface, for example, by working through the Abiquo quick tutorial
- You should have API credentials and a chosen authentication method, see Authentication
- This tutorial uses the Cloud Administrator default account and does not show proper authentication
This tutorial corresponds to the UI information on the Compute in datacenters page.
Create a datacenter
In this step you will create a new datacenter in a fresh install, sending a list of links to remote services.
You will need the URL of the server where the remote services are running. If you are working with a monolithic test system, then this will probably be the URL of your monolithic server.
Note that if you have previously created a datacenter, and you have already created some remote services, you can either delete them or add them to a new datacenter.
cURL:
curl -X POST https://mjsabq.bcn.abiquo.com/api/admin/datacenters \ -H 'Accept:application/vnd.abiquo.datacenter+json;version=4.6' \ -H 'Content-Type:application/vnd.abiquo.datacenter+json;version=4.6' \ -d @requestpayload.json \ -u user:password --verbose
Success status code: 201
Example request payload:
{
"links":[
],
"name":"BCDC",
"location":"Barcelona",
"remoteServices":{
"collection":[
{
"type":"VIRTUAL_FACTORY",
"uri":"http://example.com:8009/virtualfactory"
},
{
"type":"VIRTUAL_SYSTEM_MONITOR",
"uri":"http://example.com:8009/vsm"
},
{
"type":"APPLIANCE_MANAGER",
"uri":"http://example.com:8009/am"
},
{
"type":"NARS",
"uri":"http://example.com:8009/nars"
},
{
"type":"STORAGE_SYSTEM_MONITOR",
"uri":"http://example.com:8009/ssm"
},
{
"type":"BPM_SERVICE",
"uri":"http://example.com:8009/bpm-async"
},
{
"type":"DHCP_SERVICE",
"uri":"omapi://example.com:7911/"
},
{
"type":"DHCPv6",
"uri":"omapi://example.com:7911/"
},
{
"type":"REMOTE_ACCESS",
"uri":"guacd://example.com:4822/"
}
]
}
}
Example response payload:
In the response payload, you will see a set of links, which you can use to obtain more information about the datacenter elements.
One of the links identifies the datacenter in the platform. This link has a key "rel" (meaning "relation") and a value of "edit". If you need to pass a link to the datacenter to another request, then you should change the value of the "rel" link to "datacenter".
You will need the racks link in the next step, which is to create a rack.
Allow tenants to work with the datacenter
If you will be working with an enterprise other than the one of the user that created the datacenter, you will need to create a datacenter limit for your tenant that will allow the tenant to use the datacenter. This is the same as editing the enterprise in the UI and adding the datacenter to the enterprise's list of allowed datacenters. To do this, you will need the link to the datacenter, but you will need to change the value of the "rel" link from "edit" to "datacenter".
Add a rack
In Abiquo, hypervisors and container servers are organized in racks, in order to share the same network infrastructure and for high availability, for example.
To create a rack, you will need to make a POST request to the datacenter's racks link, which you can find in the response to the create datacenter request or from a GET to the datacenter link. In this example, we will use the racks link from the datacenter created above and a rack entity file. The rack entity is documented on the Abiquo API Reference page, but you should also read the Compute in datacenters page in the User Manual, which provides more information about Abiquo racks. In particular, you should pay attention to the network parameters, which establish the VLAN tags that are available for Abiquo to use in the switch for Abiquo private networks. Even if you are using an SDN system, you will still need to define the tag range for Abiquo.
cURL:
curl -X POST https://example.com/api/admin/datacenters/3/racks/ \ -H 'Accept:application/vnd.abiquo.rack+json;version=4.6' \ -H 'Content-Type:application/vnd.abiquo.rack+json;version=4.6' \ -d @requestpayload.json \ -u user:password --verbose
Success status code: 201
Request payload:
{
"vlanIdMin":2,
"vlanIdMax":4094,
"vlanPerVdcReserved":1,
"nrsq":10,
"name":"bcdc_rack_01",
"shortDescription":"KVM rack",
"vlansIdAvoided":"1-20"
}
Response payload:
Add a cloud node
A cloud node is the physical machine and hypervisor host or container server, for example.
Retrieve the machine list from a master hypervisor
Here we use a GET request to the "discover" link of the datacenter, but we need to supply the IP address of the manager host, and its credentials as parameters.
This example shows a master hypervisor (vCenter, XenServer or OracleVM), so the first step is to retrieve the list of hosts managed by the master hypervisor.
cURL:
curl -X GET 'https://example.com/api/admin/datacenters/3/action/discover?managerip=10.60.11.242&hypervisor=VMX_04&manageruser=administrator%40vsphere.local&managerpassword=hypervisorpassword' \ -H 'Accept:application/vnd.abiquo.managedhostlocators+json;version=4.6' \ -d @requestpayload.json \ -u user:password --verbose
Success status code: 200
Request payload:
-- none --
Response payload:
Retrieve a machine from a hypervisor address
Here we also use a GET request to the "discover" link of the datacenter, but we need to supply the IP address of the hypervisor host in addition to the master hypervisor address and credentials.
This example shows a host managed by a master hypervisor.
cURL:
curl -X GET 'https://example.com/api/admin/datacenters/3/action/discover?hypervisor=VMX_04&managerip=10.60.11.242&manageruser=administrator%40vsphere.local&managerpassword=hypervisorpassword!&ip=10.60.2.27' \ -H 'Accept:application/vnd.abiquo.machines+json;version=4.6' \ -d @requestpayload.json \ -u user:password --verbose
Success status code: 200
Request payload:
-- none --
Response payload:
Retrieve a KVM machine
And if you're doing a test, maybe you're just using a KVM, in which case you should use the following cURL, modifying the appropriate parameters.
GET https://example.com/api/admin/datacenters/3/action/discover?hypervisor=KVM&ip=mjskvm.bcn.abiquo.com -H 'Accept:application/vnd.abiquo.machines+json;version=4.6' \ -d @requestpayload.json \ -u user:password --verbose
Modify the machine details
To create a machine in Abiquo, you will need to modify the response object from the previous discovery request.
Generally, you will need to obtain a single machine object, enable datastores and add a network service type.
Retrieve network service type
A network service type is a tag for your networks to associate them with hypervisor NICs. By default, there is a "Service Network" type. Typically, the default Service Network type is created for each datacenter, and if you haven't created any extra network service types in your environment, the ID number of the network service type will be the same as the datacenter.
If you have created network service types in Abiquo, retrieve the network service types for your datacenter. Here you can use a GET request to the link with a "rel" value of "networkservicetypes" for your datacenter.
curl -X GET https://example.com/api/admin/datacenters/3/networkservicetypes \ -H 'Accept:application/vnd.abiquo.networkservicetypes+json;version=4.6' \ -d @requestpayload.json \ -u user:password --verbose
You will need the link with the "rel" value of "edit" to create the network service type link for the host NIC.
Modify the machines DTO
Here we will walk through some basic changes to the response object from the previous machine discovery step
Remove the colleciton list information to create only a single machine. To do this, remove the following lines from the top and bottom of the Machines list returned previously.
{ "links": [], "collection": [ .... ] }To enable datastores, change "enabled" to true (without any quotation marks) for all datastores you wish to enable. For example:
{ "name": "ds-bc2blade4", "rootPath": "/vmfs/volumes/58179796-afcc20cf-38a8-0015c5ff1d0d", "directory": "", "size": 137975824384, "usedSize": 110656225280, "enabled": true, "datastoreUUID": "c87563c2-8ed4-49b2-8bc9-10ab3555e905", "links": [] },Add a link with a rel of "networkservicetype" to the links section of at least one of the virtual switches that is attached to the service network, for example:
{ "name": "dvSwitchprimary", "mac": "00:15:c5:ff:1d:0d", "links": [ { "title": "Service Network", "rel": "networkservicetype", "type": "application/vnd.abiquo.networkservicetype+json", "href": "https://example.com:443/api/admin/datacenters/4/networkservicetypes/4" } ] }Add the "managerUser" and "managerPassword" attributes.
The final machine entity is shown in the following step where it is used to create the physical machine.
Create the physical machine
To add a physical machine, use the machine object you retrieved earlier and modified in the previous step. Perform a POST request to the link with a "rel" value of "machines" from the rack object you created earlier. This will add the physical machine to the platform and its state should be "managed". When you need to check its state, perform a GET request to the "checkstate" link.
In the user interface, the cloud node will be added to the rack and displayed in the tree view of the Infrastructure tab. After you've created the host, if you're interested in retrieving any existing virtual machines, see the section below.
cURL:
curl -X POST https://example.com/api/admin/datacenters/4/racks/4/machines \ -H 'Accept:application/vnd.abiquo.machine+json;version=4.2' \ -H 'Content-Type:application/vnd.abiquo.machine+json;version=4.2' \ -d @requestpayload.json \ -u user:password --verbose
Success status code: 201
Request payload:
Use the modified machine entity from the above step.
{
"name": "192.168.2.54",
"description": "192.168.2.54",
"state": "MANAGED",
"type": "VMX_04",
"ip": "192.168.2.54",
"hostname": "192.168.2.54",
"ipService": "192.168.2.54",
"ram": 8191,
"ramUsed": 0,
"cpu": 8,
"cpuUsed": 0,
"initiatorIQN": "iqn.1998-01.com.vmware:bc2blade4-79876e08",
"datastores": {
"links": [],
"collection": [
{
"name": "nfspooool",
"rootPath": "/vmfs/volumes/2ba3e301-47b71ed5",
"directory": "",
"size": 5939188432896,
"usedSize": 3987592658944,
"enabled": false,
"datastoreUUID": "2678ca1c-c14e-4693-984b-58dd69f05959",
"links": []
},
{
"name": "ds-bc2blade4",
"rootPath": "/vmfs/volumes/58179796-afcc20cf-38a8-0015c5ff1d0d",
"directory": "",
"size": 137975824384,
"usedSize": 110656225280,
"enabled": true,
"datastoreUUID": "c87563c2-8ed4-49b2-8bc9-10ab3555e905",
"links": []
},
{
"name": "nardolocallll",
"rootPath": "/vmfs/volumes/9d68c024-ba040d76",
"directory": "",
"size": 118013599744,
"usedSize": 71948795904,
"enabled": false,
"datastoreUUID": "86a231a1-216a-4d08-aa39-b91713623744",
"links": []
},
{
"name": "ABQ_411cb5cb-1079-4d14-8dd9-404e02533397",
"rootPath": "/vmfs/volumes/e790e2b9-7d7adc9f",
"directory": "",
"size": 5939188432896,
"usedSize": 3987592658944,
"enabled": false,
"datastoreUUID": "71a9fa3c-9edb-4bd1-8a69-323b0cb6f4f9",
"links": []
}
]
},
"networkInterfaces": {
"links": [],
"collection": [
{
"name": "vSwitch0",
"mac": "00:15:c5:ff:1d:0b",
"links": []
},
{
"name": "dvSwitchprimary",
"mac": "00:15:c5:ff:1d:0d",
"links": [
{
"title": "Service Network",
"rel": "networkservicetype",
"type": "application/vnd.abiquo.networkservicetype+json",
"href": "https://example.com:443/api/admin/datacenters/4/networkservicetypes/4"
}
]
}
]
},
"managerIp": "10.60.11.242",
"managerUser": "root",
"managerPassword": "managerPassword",
"links": []
}
Response payload:
Retrieve guests running on the host
In the user interface, you can check a box to Retrieve existing virtual machines when you create a physical machine. This means that the platform will take the guests you retrieve into consideration (for example, for scheduling and statistics), even though they are not managed by Abiquo unless you explicitly capture them. Here's how to retrieve the virtual machines in the API. First, you need to add the host, as described above. Then perform a GET request to the link with a "rel" value of "virtualmachines" and with the parameter "sync" set to "true".
https://example.com/api/admin/datacenters/4/racks/4/machines/4/virtualmachines?sync=true
To remove unmanaged machines, send a DELETE request to this link. Now when you perform the GET request again without the sync parameter, Abiquo will only display the guests that it manages. For more details, see https://wiki.abiquo.com/api/latest/VirtualMachinesInfrastructureResource.html and for information about retrieving all guests from the platform at the same time, see https://wiki.abiquo.com/api/latest/VirtualMachinesAdminResource.html. For information about capturing VMs from a host, see Import and capture virtual machines and How to capture a remote virtual machine from a managed hypervisor.