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.






    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:

    HabrExample1VE Linux 40100000125610010

    If everything is specified correctly, then the answer will come about the successful creation of a new virtual machine:

    VE create initiated152eyyBHO




    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:

    Web40VE Linux 40100000151210022 ';
        $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 initiated152eyyBHO


    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

    Also popular now: