Managing Parallels Automation for Cloud Infrastructure via API
The last time we talked about the cloud-based servers Parallels Automation for Cloud Infrastructure (PACI) - the estimated price and functionality. Including, briefly mentioned the availability of APIs for server management. Today we will take a closer look at the actions available through the API and examples of basic commands.
Unfortunately, the previous post was not rated very highly, but we received interesting questions, a lot of feedback and several bug reports from the habrayuzers who joined the testing . We will try to cover the topics you have covered in this and the following posts.
As we already said, the foundation of our cloud - Parallels Automation for Cloud Infrastructure - is a module of the Parallels Automation billing and service provisioning system. The product comes with an excellent RESTful API. We will not give the entire listing with API commands - you can see it in the official documentation . We’ll better show a few examples of this way of managing virtual machines and containers.
Working with cloud resources is done by sending API requests to the PACI management server. Answers come in XML format, the code is as readable and user-oriented as possible, and not processed by a soulless parser, so all fields have sensible names. In addition, you can easily automate the management, and XML itself is parsed without problems if you suddenly need it.
You need to access the API at the address of the PACI management server (in the future we will shorten it to baseURL):
If everything is more or less clear with ip_address hostname and port, then the remaining two fields are worth focusing on. / paci / should always look like / paci /, and nothing else. And the version is indicated in v1.0 format (numbers, respectively, may change in future versions of PACI).
So the finished baseURL will look like this:
Further communication with the virtual server is carried out using the baseURL extension “to the right” - we simply set / and add additional parameters to baseURL. / ve - access to the virtual server, and since the server usually has its own identifier, the server name / my-server-01 is added after / ve.
The baseURL string with two additional parameters takes the form:
Which is equivalent to the line:
Some queries allow the definition of additional parameters. Often, options are optional, but very useful. All additional parameters are listed after the question mark.
An example of such a query is the following line:
We have more or less sorted out the syntax, now let's move on to the possibilities.
The possibilities are quite wide. “Innocent” features are available:
And more serious things:
As you already know, you can view the list of servers with the command
A simple XML will come in response:
The description of the fields is in the documentation, but their names, in principle, speak for themselves.
You can stop or start the finished server with a simple request:
Instead of {ve-name}, insert the server name (the name field from the answer above), and after it we add a command to start or stop the server. Again, as easy as shelling pears, there’s nothing to stop here, in principle.
Creating a new server from the console is a bit more complicated. This command has a bunch of additional parameters, and you will have to keep restrictions on the use of certain resources in your head or peek at the cheat sheet, as this is not a GUI with sliders. If the parameters are exceeded, you will receive error 406: “Subscription limit for VE number exceeded".
The command itself looks like this:
And then all the magic begins. In addition to the request itself, it is also necessary to form an XML body for it, in which all the parameters of the required server will be written:
If everything is specified correctly, then the answer will come about the successful creation of a new virtual machine:
The functionality inherent in this group of teams allows you to save time and resources when deploying and scaling new systems.
The following examples assume that the images are already prepared, and you have familiarized yourself with their list of commands.
Let's say the server answered us that there is such an image:
Want to deploy another server from it? Nothing is easier! Standard request:
in our case it turns into
On this, in fact, work with creating a server from an image ends, but no one bothers to create a new server by simply cloning an existing one:
The list of available balancers is “ordered” in the same way as many other lists of available services, services and features:
In response, a short XML comes with information about the load balancers created:
Any existing server can be easily connected to an already working balancer:
Yes, and disconnecting is not more difficult:
So far, only functions have got into this part of the API. One of them is a list of available “pre-installed” server OSs:
List of ready-made presets for automatic backup:
GET request to get a list of servers:
XML response:
PUT request to start-stop the server:
XML response:
POST request to create a server:
XML response:
DELETE request to delete a server
XML response:
Non-commercial testing of Cloud Servers will continue until February 1, 2013. The development of the service largely depends on your feedback. Join now !
For the authors of the best reviews of the service, we have prepared prizes .
Cloud Servers from Infobox
Parallels Automation for Cloud Infrastructure API White Paper (PDF)
Infobox Blog
Unfortunately, the previous post was not rated very highly, but we received interesting questions, a lot of feedback and several bug reports from the habrayuzers who joined the testing . We will try to cover the topics you have covered in this and the following posts.
As we already said, the foundation of our cloud - Parallels Automation for Cloud Infrastructure - is a module of the Parallels Automation billing and service provisioning system. The product comes with an excellent RESTful API. We will not give the entire listing with API commands - you can see it in the official documentation . We’ll better show a few examples of this way of managing virtual machines and containers.
Syntax and Punctuation
Working with cloud resources is done by sending API requests to the PACI management server. Answers come in XML format, the code is as readable and user-oriented as possible, and not processed by a soulless parser, so all fields have sensible names. In addition, you can easily automate the management, and XML itself is parsed without problems if you suddenly need it.
You need to access the API at the address of the PACI management server (in the future we will shorten it to baseURL):
https://{ip_address | hostname}:port/paci/version
If everything is more or less clear with ip_address hostname and port, then the remaining two fields are worth focusing on. / paci / should always look like / paci /, and nothing else. And the version is indicated in v1.0 format (numbers, respectively, may change in future versions of PACI).
So the finished baseURL will look like this:
https://109.120.*.*:4465/paci/v1.0
Further communication with the virtual server is carried out using the baseURL extension “to the right” - we simply set / and add additional parameters to baseURL. / ve - access to the virtual server, and since the server usually has its own identifier, the server name / my-server-01 is added after / ve.
The baseURL string with two additional parameters takes the form:
https://109.120.*.*:4465/paci/v1.0/ve/my-server-01
Which is equivalent to the line:
baseURL/ve/my-server-01
Some queries allow the definition of additional parameters. Often, options are optional, but very useful. All additional parameters are listed after the question mark.
An example of such a query is the following line:
GET baseURL/ve?subscription=1000001
We have more or less sorted out the syntax, now let's move on to the possibilities.
What actions are available through the API?
The possibilities are quite wide. “Innocent” features are available:
- listing and monitoring of existing virtuals
- creation of new and management of already created servers
- image deployment
- cloning existing systems
- setting resources available to the server
And more serious things:
- creating new images
- managing already created server images
- creation, configuration, and, of course, removal of the load balancer
- connecting and disconnecting servers from the balancer
Server management
As you already know, you can view the list of servers with the command
GET baseURL/ve/
A simple XML will come in response:
The description of the fields is in the documentation, but their names, in principle, speak for themselves.
You can stop or start the finished server with a simple request:
PUT baseURL/ve/{ve-name}/start|stop
Instead of {ve-name}, insert the server name (the name field from the answer above), and after it we add a command to start or stop the server. Again, as easy as shelling pears, there’s nothing to stop here, in principle.
Creating a new server from the console is a bit more complicated. This command has a bunch of additional parameters, and you will have to keep restrictions on the use of certain resources in your head or peek at the cheat sheet, as this is not a GUI with sliders. If the parameters are exceeded, you will receive error 406: “Subscription limit for VE number exceeded".
The command itself looks like this:
POST baseURL/ve/
And then all the magic begins. In addition to the request itself, it is also necessary to form an XML body for it, in which all the parameters of the required server will be written:
HabrExample1 VE Linux 40 1000001 256 100 1 0
If everything is specified correctly, then the answer will come about the successful creation of a new virtual machine:
VE create initiated 152eyyBHO
Image management
The functionality inherent in this group of teams allows you to save time and resources when deploying and scaling new systems.
The following examples assume that the images are already prepared, and you have familiarized yourself with their list of commands.
GET baseURL/image
Let's say the server answered us that there is such an image:
Want to deploy another server from it? Nothing is easier! Standard request:
POST baseURL/ve/{subscription-id}/{ve-name}/from/{image-name}
in our case it turns into
POST baseURL/ve/1000003/Habr3/from/HabrExample3
On this, in fact, work with creating a server from an image ends, but no one bothers to create a new server by simply cloning an existing one:
POST baseURL/ve/{ve-name}/clone-to/{new-server-name}
Balancer management
The list of available balancers is “ordered” in the same way as many other lists of available services, services and features:
GET baseURL/load-balancer
In response, a short XML comes with information about the load balancers created:
Any existing server can be easily connected to an already working balancer:
POST baseURL/load-balancer/{lb-name}/{ve-name}
Yes, and disconnecting is not more difficult:
DELETE baseURL/load-balancer/{lb-name}/{ve-name}
Utilities
So far, only functions have got into this part of the API. One of them is a list of available “pre-installed” server OSs:
GET baseURL/template/{name}
List of ready-made presets for automatic backup:
GET baseURL/schedule
PHP code examples
GET request to get a list of servers:
:');
curl_setopt($process, CURLOPT_RETURNTRANSFER, TRUE);
$head = curl_exec($process);
curl_close($process);
?>
XML response:
PUT request to start-stop the server:
/';
$url = $mainStr.$queryStr;
$process = curl_init();
curl_setopt($process, CURLOPT_URL, $url);
curl_setopt($process, CURLOPT_HTTPHEADER, array('Content-Type: application/xml'));
curl_setopt($process, CURLOPT_PUT, 1);
curl_setopt($process, CURLOPT_HEADER, 1);
curl_setopt($process, CURLOPT_USERPWD, ':');
curl_setopt($process, CURLOPT_RETURNTRANSFER, TRUE);
$head = curl_exec($process);
curl_close($process);
?>
XML response:
* VE START initiated
POST request to create a server:
Web40 VE Linux 40 1000001 512 100 2 2 ';
$url = $mainStr.$queryStr;
$process = curl_init();
curl_setopt($process, CURLOPT_URL, $url);
curl_setopt($process, CURLOPT_HTTPHEADER, array('Content-Type: application/xml'));
curl_setopt($process, CURLOPT_POST, 1);
curl_setopt($process, CURLOPT_HEADER, 1);
curl_setopt($process, CURLOPT_USERPWD, ':');
curl_setopt($process, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($process, CURLOPT_POSTFIELDS, $serverInfo);
$head = curl_exec($process);
curl_close($process);
?>
XML response:
VE create initiated 152eyyBHO
DELETE request to delete a server
';
$url = $mainStr.$queryStr;
$process = curl_init();
curl_setopt($process, CURLOPT_URL, $url);
curl_setopt($process, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($process, CURLOPT_HEADER, 1);
curl_setopt($process, CURLOPT_USERPWD, ':');
curl_setopt($process, CURLOPT_RETURNTRANSFER, TRUE);
$head = curl_exec($process);
curl_close($process);
?>
XML response:
* VE DELETE initiated
Non-commercial testing of Cloud Servers will continue until February 1, 2013. The development of the service largely depends on your feedback. Join now !
For the authors of the best reviews of the service, we have prepared prizes .
Our previous posts on the topic
Cloud Servers from Infobox
Links to referred materials
Parallels Automation for Cloud Infrastructure API White Paper (PDF)
Infobox Blog